Skip to content

capabilities.md

Latest commit

 

History

History
196 lines (143 loc) · 4.4 KB

capabilities.md

File metadata and controls

196 lines (143 loc) · 4.4 KB

Capabilities

This document describes everything vscode-dotenv-diff can do, and how it behaves in different scenarios.

Ignores runtime/build-tool keys by default:

PWD
NODE_ENV
VITE_MODE
MODE
BASE_URL
PROD
DEV
SSR
DOTENV_KEY
CI
GITHUB_ACTIONS
INIT_CWD
TZ
PORT
PATH
HOME
USER
SHELL
LANG
TMP
TEMP
TMPDIR
NODE_PATH

1. Autocomplete for missing keys in .env

When editing a .env file, the extension suggests environment variable keys that are used in source files but missing from the current .env document.

In monorepos, suggestions are scoped to source files that resolve to the same nearest .env as the file you are editing.

Suggestions appear on empty lines.

Autocomplete

Example suggestions:

API_URL=
JWT_SECRET=
REDIS_URL=

Selecting a suggestion inserts the key in the form KEY=.

If multiple keys are missing, the suggestion list also includes Add all missing environment variables, which inserts all missing keys in one action.

2. Missing environment variables

When a source file references an environment variable and that key is not present in the nearest .env file, the extension underlines the reference with a warning.

Not Defined

Example:

apps/frontend/.env

DB_HOST=localhost
DB_PORT=5432

apps/frontend/src/app.ts

const host = process.env.DB_HOST;     // defined in .env
const secret = process.env.SECRET;    // not defined in .env

Warning message:

Environment variable "SECRET" is not defined in .env

3. Unused environment variables

When a key is defined in a .env file but never referenced anywhere in the workspace, the key is flagged with a warning directly on that line in the .env file.

Unused

Example:

.env

DB_HOST=

Warning message:

Environment variable "DB_HOST" is defined in .env but never used

4. Monorepo support

The extension automatically finds the nearest .env file by walking up the directory tree from the source file. No configuration required.

Example structure:

apps/
├── frontend/
│   ├── .env              ← used for frontend source files
│   └── src/
│       └── app.ts
├── backend/
│   ├── .env              ← used for backend source files
│   └── src/
│       └── server.ts
└── .env                  ← fallback if no closer .env exists

Each source file always resolves to its nearest .env — independently of other files.

This nearest-.env behavior is used by diagnostics and autocomplete suggestions.

5. Supported syntax

The extension recognises the following patterns:

// Node.js – dot and bracket notation
process.env.MY_KEY
process.env["MY_KEY"]
process.env['MY_KEY']

// Node.js – destructuring
const { MY_KEY } = process.env
const { MY_KEY: alias, OTHER_KEY = "fallback" } = process.env

// Vite / import.meta
import.meta.env.MY_KEY
import.meta.env["MY_KEY"]
import.meta.env['MY_KEY']

// SvelteKit – dynamic (env object)
import { env } from '$env/dynamic/private';
import { env } from '$env/dynamic/public';
env.MY_KEY
const { MY_KEY } = env
const { MY_KEY: alias, OTHER_KEY = "fallback" } = env

// SvelteKit – dynamic (any alias name works)
import { env as anyName } from '$env/dynamic/private';
import { env as anyName } from '$env/dynamic/public';
anyName.MY_KEY
const { MY_KEY } = anyName

// Multiple aliased imports in the same file are also supported:
import { env as publicEnv } from '$env/dynamic/public';
import { env as privateEnv } from '$env/dynamic/private';
publicEnv.PUBLIC_API_URL
privateEnv.SECRET_KEY

// SvelteKit – static (named imports)
import { MY_KEY } from '$env/static/private';
import { MY_KEY } from '$env/static/public';
import { MY_KEY as alias } from '$env/static/private';
MY_KEY

Only UPPER_CASE key names are matched, which is the standard convention for environment variables.

Scanned file types: .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .svelte

6. Skipped files

The extension intentionally skips:

  • node_modules/**
  • Test files (.test.ts, .spec.ts etc.)

Known limitations

  • .env.local, .env.production etc. are not resolved — only .env
  • Template literal expressions are scanned, but dynamic key access is not supported:
  process.env[`MY_${suffix}`] // not detected