env-fill

Zero-dependency missing-env-var detector with an in-browser form that writes values back to .env. Fill API keys right in your app's UI — they never touch your coding agent's chat context.

零依赖的「缺失环境变量检测器」，带一个浏览器内填写表单，把值写回 .env。 直接在应用界面里填 API Key —— 密钥不进 coding agent 的对话上下文。

Why / 解决什么

When you build apps with a coding agent, you constantly need to put API keys into env vars. You don't want the secret in the agent's context, but opening .env to hunt for the right field every time is annoying. env-fill detects which required vars are missing, redirects to a setup page, and lets you fill them in the browser — the value goes straight from browser to disk.

用 coding agent 开发时常要往环境变量塞 API Key：既不想密钥进 agent 上下文，又不想每次翻 .env 找字段。 env-fill 检测缺哪些必填变量、把页面请求引导到设置页、让你在浏览器填，值从浏览器直达磁盘。

Install / 安装

npm install @duanyijia/env-fill
# or, straight from GitHub:
npm install github:YijiaDuan/env-fill

Zero dependencies. Node >= 16. Works with plain http, Express, or any Connect-style server.

Usage / 用法

Plain Node http

const http = require("http");
const { createEnvSetup, loadEnvFiles } = require("@duanyijia/env-fill");

loadEnvFiles(); // read existing .env / .env.local into process.env

const envSetup = createEnvSetup({
  vars: [
    { key: "OPENAI_API_KEY", label: "OpenAI API Key", required: true, help: "From platform.openai.com" },
    { key: "BASE_URL", label: "API Base URL", required: false, secret: false },
  ],
});

http.createServer(async (req, res) => {
  if (await envSetup.handle(req, res)) return; // serves /__setup + gates missing vars

  // ...your real app...
  res.end("hello");
}).listen(3000);

Express

app.use(envSetup.middleware);

Then start your app and open it. While a required var is missing, any page request redirects to /__setup. Fill the form, hit save — values are written to .env.local and injected into the running process.

启动后打开应用：只要有必填变量缺失，页面请求会跳到 /__setup。填完保存，值写入 .env.local 并注入当前进程。

💡 Read env vars at request time (process.env.X) rather than once at module load, so values take effect immediately without a restart. 建议在请求时读 process.env.X，而不是模块加载时读一次，这样填完即时生效、无需重启。

API

| Export | Description | |---|---| | createEnvSetup(opts) | Returns { handle, middleware, missing, ... }. | | loadEnvFiles(files?) | Parse .env files into process.env (no overwrite). Defaults to [".env", ".env.local"]. | | writeEnvFile(file, updates) | Merge key=value pairs into an env file, preserving other lines. |

createEnvSetup options

| Option | Default | Description | |---|---|---| | vars | — | [{ key, label, help, required, secret, placeholder }] | | envFile | .env.local | File values are written to. | | route | /__setup | Route serving the form. | | enabled | NODE_ENV !== "production" | Disabled in production so the write endpoint never ships. | | gate | true | Redirect page requests to the form while required vars are missing. |

Security / 安全

• Disabled in production by default — the disk-write endpoint won't ship to prod.
• Add .env* to your .gitignore (this repo's .gitignore already does).
• Secrets go browser → disk; they never enter the coding agent's context.

Demo

npm run demo   # http://localhost:4321

License

MIT