{"_id":"@akshitaa11/envguard","name":"@akshitaa11/envguard","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@akshitaa11/envguard","version":"1.0.0","description":"Static analysis for environment variables — finds dead vars, missing vars, and framework misconfigurations by scanning your source code","main":"dist/index.js","bin":{"envguard":"dist/cli.js"},"scripts":{"build":"tsc","dev":"ts-node src/cli.ts","test":"jest","lint":"eslint src --ext .ts"},"keywords":["env","dotenv","linter","static-analysis","cli","devtools"],"author":{"name":"Akshita"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/akshitaa011/envguard.git"},"dependencies":{"@babel/parser":"^7.23.0","@babel/traverse":"^7.23.0","@babel/types":"^7.23.0","chalk":"^4.1.2","commander":"^11.1.0","dotenv":"^16.3.1","glob":"^10.3.10","table":"^6.8.1"},"devDependencies":{"@types/babel__traverse":"^7.20.4","@types/jest":"^29.5.8","@types/node":"^20.9.0","jest":"^29.7.0","ts-jest":"^29.1.1","typescript":"^5.2.2"},"jest":{"preset":"ts-jest","testEnvironment":"node","testMatch":["**/tests/**/*.test.ts"]},"_id":"@akshitaa11/envguard@1.0.0","gitHead":"a0b6c33df17f9dc07f5f239e5c9ee9014ba4dc5a","types":"./dist/index.d.ts","bugs":{"url":"https://github.com/akshitaa011/envguard/issues"},"homepage":"https://github.com/akshitaa011/envguard#readme","_nodeVersion":"22.14.0","_npmVersion":"11.1.0","dist":{"integrity":"sha512-xVEYkw32eGph/oDIsoyYFn5sdKca4+8Izbhyzxy0gDHTwEYP+D8j+OMdr2QhUJMMK43q49XV5eKmX+6r4SIQZQ==","shasum":"c9c1ae7d916da2381e3aa40177275f68e8f951db","tarball":"https://registry.npmjs.org/@akshitaa11/envguard/-/envguard-1.0.0.tgz","fileCount":54,"unpackedSize":152369,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDhuPjnJiMpJdR5Zh1QXa05nHaxakGgCTkaJtR4HLqFMgIgDUJtc1U+HI4QBhlgVw8A4gPSeOuOb+vRM9+0r4RSq+U="}]},"_npmUser":{"name":"akshitaa11","email":"akshitasinghal300@gmail.com"},"directories":{},"maintainers":[{"name":"akshitaa11","email":"akshitasinghal300@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/envguard_1.0.0_1779528229597_0.6254914872496458"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-23T09:23:49.084Z","1.0.0":"2026-05-23T09:23:49.740Z","modified":"2026-05-23T09:23:49.927Z"},"maintainers":[{"name":"akshitaa11","email":"akshitasinghal300@gmail.com"}],"description":"Static analysis for environment variables — finds dead vars, missing vars, and framework misconfigurations by scanning your source code","homepage":"https://github.com/akshitaa011/envguard#readme","keywords":["env","dotenv","linter","static-analysis","cli","devtools"],"repository":{"type":"git","url":"git+https://github.com/akshitaa011/envguard.git"},"author":{"name":"Akshita"},"bugs":{"url":"https://github.com/akshitaa011/envguard/issues"},"license":"MIT","readme":"# ⚡ envguard\n\n> Static analysis for environment variables — finds dead vars, missing vars, and framework misconfigurations by scanning your source code.\n\n[![npm version](https://badge.fury.io/js/envguard.svg)](https://badge.fury.io/js/envguard)\n[![CI](https://github.com/akshitaa011/envguard/actions/workflows/envguard.yml/badge.svg)](https://github.com/akshitaa011/envguard/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nUnlike other `.env` linters that only check the `.env` file in isolation, **envguard scans your actual source code using an AST parser** and cross-references it against your declared variables.\n\n---\n\n## The Problem\n\nEvery team has this in their `.env`:\n\n```\nDATABASE_URL=postgres://...\nOLD_STRIPE_KEY=sk_live_XXXXXXX      # hasn't been used since Q2\nLEGACY_REDIS_URL=redis://...        # service was deprecated\nANALYTICS_SECRET=abc123             # what even is this\n```\n\nAnd in code:\n```js\nconst api = process.env.OPENAI_API_KEY;  // crashes in production — never declared!\n```\n\nenvguard catches both.\n\n---\n\n## What It Detects\n\n| Category | Description |\n|---|---|\n| 🗑️ **Dead** | Declared in `.env`, never referenced in source code |\n| ⚠️ **Missing** | Used in source code, not in `.env` — will be `undefined` at runtime |\n| 🔧 **Framework issues** | Next.js server vars in client code, Vite prefix violations, CRA prefix violations |\n| ❓ **Dynamic** | `process.env[variable]` — flagged for manual review |\n\n---\n\n## Installation\n\n```bash\n# Global (for CLI use)\nnpm install -g envguard\n\n# Local (for project integration)\nnpm install --save-dev envguard\n```\n\n---\n\n## Usage\n\n### Basic scan\n```bash\n# Scan current directory (auto-detects framework)\nenvguard check\n\n# Scan a specific directory\nenvguard check ./my-app\n\n# Specify framework explicitly\nenvguard check . --framework nextjs\n```\n\n### Output formats\n```bash\n# Human-readable table (default)\nenvguard check . --output table\n\n# JSON (for programmatic use)\nenvguard check . --output json\n\n# SARIF (for GitHub Code Scanning)\nenvguard check . --output sarif > results.sarif\n```\n\n### CI: fail the build on missing vars\n```bash\n# Exit code 1 if any variables are used but not declared\nenvguard check . --fail-on missing\n\n# Fail on dead OR missing vars\nenvguard check . --fail-on dead,missing\n\n# Fail on framework errors too\nenvguard check . --fail-on missing,warnings\n```\n\n### List all vars\n```bash\nenvguard list\n```\n\n---\n\n## Example Output\n\n```\n  ⚡ envguard — environment variable analysis\n  Framework: nextjs | Root: .\n\n  ✅ 4 healthy  │  🗑️  2 dead  │  ⚠️  1 missing  │  ❓ 0 dynamic\n\n  🗑️  Dead Variables (2)\n  Declared in .env but never referenced in source code\n\n  ┌─────────────────────────┬───────────┬────────┬──────┐\n  │ Key                     │ Value     │ File   │ Line │\n  ├─────────────────────────┼───────────┼────────┼──────┤\n  │ OLD_STRIPE_KEY          │ sk_li**** │ .env   │ 3    │\n  │ LEGACY_REDIS_URL        │ red****   │ .env   │ 4    │\n  └─────────────────────────┴───────────┴────────┴──────┘\n\n  ⚠️  Missing Variables (1)\n  Used in source code but NOT declared in .env\n\n  ┌─────────────────┬──────────────────────────┬────────────────────┬──────┐\n  │ Key             │ Access Pattern           │ File               │ Line │\n  ├─────────────────┼──────────────────────────┼────────────────────┼──────┤\n  │ OPENAI_API_KEY  │ process.env.OPENAI_API_… │ src/lib/openai.ts  │ 12   │\n  └─────────────────┴──────────────────────────┴────────────────────┴──────┘\n\n  ✖ Issues found. See above for details.\n```\n\n---\n\n## Framework Support\n\n### Next.js\n- Warns if a non-`NEXT_PUBLIC_` var is used in a client-side component (will be `undefined` in the browser)\n- Warns if `NEXT_PUBLIC_` var name suggests it contains a secret (exposed in browser bundle)\n- Errors if `import.meta.env` is used (Vite syntax, not Next.js)\n\n### Vite\n- Errors if a var without `VITE_` prefix is accessed via `import.meta.env` (Vite won't expose it)\n- Warns if `VITE_` prefix is used on what looks like a secret key (exposed in bundle)\n- Warns if `process.env` is used in client files (use `import.meta.env` instead)\n\n### React (CRA)\n- Errors if a var without `REACT_APP_` prefix is used in component files\n\n### Express / Node\n- Warns if critical-looking vars (DB, SECRET, TOKEN) have empty values\n\n---\n\n## GitHub Action\n\nAdd to any project's `.github/workflows/`:\n\n```yaml\n- name: Check env variables\n  uses: akshitaa011/envguard@v1\n  with:\n    fail-on: missing\n    upload-sarif: true   # Results appear as inline PR annotations\n```\n\n---\n\n## API (Library Usage)\n\n```typescript\nimport { analyze } from 'envguard';\n\nconst result = await analyze({\n  root: './my-project',\n  framework: 'nextjs',\n  failOn: ['missing'],\n});\n\nconsole.log(`Dead: ${result.dead.length}`);\nconsole.log(`Missing: ${result.missing.length}`);\nconsole.log(`Warnings: ${result.warnings.length}`);\n```\n\n---\n\n## Detection Patterns\n\nenvguard detects all of these:\n\n```javascript\n// Standard access\nprocess.env.API_KEY\n\n// Bracket string access\nprocess.env['API_KEY']\n\n// Dynamic access (flagged as unanalyzable)\nprocess.env[dynamicVar]\n\n// Destructuring\nconst { API_KEY, DB_URL } = process.env\n\n// Vite client-side\nimport.meta.env.VITE_API_URL\nimport.meta.env['VITE_API_URL']\n\n// Optional chaining\nprocess.env?.API_KEY\n```\n\n---\n\n## Options\n\n| Option | Description | Default |\n|---|---|---|\n| `--env-file` | Path to `.env` file | Auto-detected |\n| `--env-example` | Path to `.env.example` | `.env.example` |\n| `--framework` | Framework override | Auto-detected |\n| `--output` | `table` \\| `json` \\| `sarif` | `table` |\n| `--fail-on` | `dead,missing,warnings` | `missing` |\n| `--include` | Glob patterns to scan | All JS/TS files |\n| `--exclude` | Dirs to skip | `node_modules,dist,...` |\n| `--quiet` | Hide healthy list | `false` |\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/akshitaa011/envguard\ncd envguard\nnpm install\nnpm test\nnpm run build\n```\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-6224f7fbb8f32284f24b0aae00ec3fbd"}