.env Contextual Peek

Peek at environment variables directly from your code without leaving the editor.

.env Contextual Peek is a lightweight, privacy-focused VS Code extension that lets you inspect environment variable references (process.env.DATABASE_URL, import.meta.env.VITE_API_URL, etc.) inline. It reveals configuration status, source file location, and masked values at a glance, eliminating the friction of switching between source files and .env files.

The Problem

When working with modern web and Node.js applications, developers constantly reference environment variables:

• "Did I define STRIPE_WEBHOOK_SECRET in .env.local or .env?"
• "Is this variable missing in my local environment?"
• "Where was this variable defined, and what line is it on?"

Checking these questions usually requires hunting down .env files, opening them, searching for the key, and switching back. .env Contextual Peek brings this information directly to your cursor with zero context switching.

Example Hover Preview

Configured Variable

Hovering over process.env.DATABASE_URL:

### DATABASE_URL

Configured ✓
**Source:** `.env.local`
**Value:** `••••••••` 🔒
**Also defined in:** `.env`

Open definition

Missing / Unconfigured Variable

Hovering over process.env.UNSET_TOKEN:

### UNSET_TOKEN

Not configured ⚠
No matching definition found in workspace `.env*` files.

Features

• Contextual Hover: Instantly inspect configuration status, source .env file, and masked value.
• Go to Definition (F12 / Cmd+Click): Jump directly from your code reference to the exact line in the corresponding .env file.
• One-Click Navigation: Click Open definition in the hover card to center the file and line in your editor.
• Masked by Default: Values are always masked (••••••••) to protect secrets from shoulder surfing or screen sharing.
• Multiple File Tracking: If a variable is defined in multiple files, the extension displays the winning file and lists alternative sources.
• Instant Caching & Live Sync: File watchers detect file changes, creations, and deletions in real-time.
• Zero Telemetry & 100% Offline: Operates entirely on your local machine. No external network requests, analytics, or background telemetry.

Supported Syntax

The extension recognizes standard JavaScript and TypeScript patterns across .js, .ts, .jsx, and .tsx files:

Node.js / CommonJS / ES Modules

• process.env.VARIABLE_NAME
• process.env["VARIABLE_NAME"]
• process.env['VARIABLE_NAME']

Vite / Modern Bundlers

• import.meta.env.VARIABLE_NAME
• import.meta.env["VARIABLE_NAME"]
• import.meta.env['VARIABLE_NAME']

Supported Environment Files

The extension searches within the open workspace for standard .env* files, including:

• .env
• .env.local
• .env.development
• .env.production
• .env.test
• .env.development.local
• .env.production.local
• .env.test.local
• Any custom workspace .env* file

Build outputs, dependency directories, and caches (node_modules, .git, dist, build, coverage, .next, .nuxt, .turbo, .cache) are automatically excluded.

Resolution Precedence

When a variable is defined across multiple .env* files in the workspace, .env Contextual Peek resolves the primary definition using a predictable, filename-based resolution precedence:

Ties between files in the same tier are broken deterministically by alphabetical order.

Important Distinction: This precedence strategy is an internal resolution order used by the extension to determine which file to highlight and jump to in the editor. The extension does not attempt to replicate runtime framework loading rules (e.g. Next.js, Vite, or NestJS runtime modes), because the active runtime mode is not known statically in the editor.

Security & Privacy

Security and data privacy are core design principles:

• Masked Values: All values are masked by default (••••••••).
• Strict URI & Command Security: Hover navigation links use validated internal commands. File paths are verified to exist within the workspace and strictly validated to be .env files before opening.
• Safe Parsing: The custom parser extracts keys and raw values safely. It never executes shell syntax ($(...), backticks) and never evaluates arbitrary code.
• Zero Telemetry: The extension contains zero tracking code, zero analytics, and makes zero network requests. No secret values ever leave your local machine or are written to external logs.

Configuration

Commands

Access these commands from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

• .env Contextual Peek: Open Environment File (envContextualPeek.openEnvFile):
  Shows a QuickPick menu listing all discovered workspace .env* files with their variable counts and allows you to jump directly to any file.

• .env Contextual Peek: Refresh Environment Variables (envContextualPeek.refresh):
  Forces a complete re-scan and re-index of all workspace environment files.

Limitations

• JavaScript / TypeScript Focused: Version 1.0 focuses on JS/TS syntax (process.env and import.meta.env). Other languages (Python os.environ, Rust, Go, etc.) are not covered in v1.
• Static Resolution Only: The extension performs static inspection of workspace files. It does not inspect machine-level environment variables (e.g. export FOO=bar in your terminal shell or system daemon).

Repository & Feedback

• GitHub Repository: https://github.com/AJ-Kaarthick/env-contextual-peek
• Issue Tracker: https://github.com/AJ-Kaarthick/env-contextual-peek/issues

License

This project is licensed under the MIT License.