.env loading quirks across the VS Code extensions (dotEnvPath, cwd, missing babel.cjs)

[unrevised6419]

Follow-up to #2951. Loading .env from graphql.config.ts behaves differently in each GraphQL VS Code extension, and the documented dotenv/config pattern works only by accident. Below is what I found digging into the published bundles (graphql.vscode-graphql 0.13.4, graphql.vscode-graphql-execution 0.3.4, graphql-config 5.1.7).

1. dotenv/config resolves .env against process.cwd(), which is not the workspace

Both extensions call loadConfig({ rootDir: <workspace folder> }). rootDir only tells cosmiconfig where to look for graphql.config.*. The config module itself is evaluated with the process's working directory, which is whatever VS Code was launched from (for example / when started from the Dock, or the repo when started with code .).

So these only work when VS Code happens to be started from the project directory:

import "dotenv/config";
// or
process.loadEnvFile();

What works everywhere is resolving the path from the config file's own location:

import path from "node:path";
import { loadEnvFile } from "node:process";

loadEnvFile(path.resolve(import.meta.dirname, ".env"));

The CommonJS equivalent (graphql.config.js / graphql.config.cjs):

const path = require("node:path");

process.loadEnvFile(path.resolve(__dirname, ".env"));

// or, with dotenv:
// require("dotenv").config({ path: path.resolve(__dirname, ".env") });

Runtime support for process.loadEnvFile. The config is evaluated by the Node.js runtime that ships inside VS Code (Electron), not by the Node installed on the machine. process.loadEnvFile was added in Node v21.7.0 / v20.12.0 (experimental until v22.21.0 / v24.10.0). VS Code 1.90 and 1.91 ship Node 20.9.0 and don't have it; VS Code 1.92 (July 2024, Electron 30, Node 20.14.0) is the first release that does. Both vscode-graphql and vscode-graphql-execution declare "engines": { "vscode": "^1.63.0" }, so on VS Code 1.63–1.91 use dotenv with an explicit path instead; it works on any version.

loadEnvFile throws when the file is missing, so a wrong path fails early instead of silently leaving the variables undefined.

process.chdir(rootDir) is not a good fix inside the extensions: the extension host is shared with every other extension, loading is async (so concurrent loads would race on one global cwd), and multi-root workspaces have several roots.

2. graphql-config.dotEnvPath only reaches the language server

The fix from #2951 (and #3964) is the graphql-config.dotEnvPath setting. In vscode-graphql it amounts to:

dotenv.config({ path: path.resolve(rootDir, dotEnvPath) });

That runs in the language server process (out/serverIpc / out/serverStdio), so it populates that process's process.env only.

vscode-graphql-execution evaluates the config in the extension host, a different process, and has no equivalent: dotEnvPath appears neither in its package.json nor in its bundle. So extensions.endpoints.default.url: process.env.X (or ${X} interpolation in YAML) stays undefined for the execution extension even with the setting configured.

3. vscode-graphql-execution ships jiti without its transform

The execution extension bundles jiti v2, whose createJiti wrapper lazily loads the Babel transform:

createRequire(import.meta.url)("../dist/babel.cjs")

After bundling, that resolves to <extension>/dist/babel.cjs, and the published extension does not include that file (dist/ only holds extension.js, helpers/, providers/). As far as I can tell, this means the execution extension cannot compile a graphql.config.ts on its own. It only picks up a compiled copy when jiti's shared cache ($TMPDIR/jiti/) already holds one for the current file contents, written by the language server, codegen, or the CLI. Because the cache key includes a content hash, every edit to the config breaks it again until something else recompiles it. That makes the .env issues above look intermittent.

The language server bundle does not have this problem, since its Babel transform (including the import.meta.dirname / import.meta.filename rewrite) is inlined.

Suggestions

1. vscode-graphql-execution honours graphql-config.dotEnvPath, resolved against the workspace folder, before evaluating the config.
2. Ship jiti's dist/babel.cjs with the execution extension (or mark jiti external / copy the file in esbuild.js).
3. Update the docs and examples to resolve .env relative to the config file instead of using import "dotenv/config".

Happy to open issues or PRs for any of these if they sound right.