deno-global-config-research.md

Should Deno Have a Global Config File?

Bun's Global Config

Bun uses bunfig.toml (TOML format) with a two-tier system:

	Local	Global
File	bunfig.toml (project root)	$HOME/.bunfig.toml or $XDG_CONFIG_HOME/.bunfig.toml
Dot prefix	No	Yes

Same schema for both. Settings include: registry/scopes, install behavior, JSX config, preload scripts, log level, telemetry, test runner defaults, CA certs, etc.

Precedence: CLI flags > local bunfig.toml > global .bunfig.toml. Merging is shallow — a local [install] section entirely replaces the global one, not individual keys within it.

Exception: The [run] section only loads from local config, not global.

---

Deno's Current State

Deno has no global config. Configuration is purely project-based:

• deno.json / deno.jsonc discovered by walking up from the working directory
• Some env vars serve as pseudo-global config: DENO_DIR, DENO_INSTALL_ROOT, DENO_NO_UPDATE_CHECK, DENO_V8_FLAGS
• .npmrc is the only file that checks the home directory (for npm registry auth)

---

Should Deno Have a Global Config?

Strong candidates for global config settings

1. Registry authentication — JSR/npm tokens that shouldn't live in project repos. Currently .npmrc partially handles this, but it's npm-only.

2. Default permissions — A user might always want --allow-env in their dev workflow. Currently requires flags every time.

3. Telemetry/update preferences — DENO_NO_UPDATE_CHECK is already an env var; a config file is more discoverable.

4. Proxy/CA certificate settings — Corporate environments need this everywhere, not per-project.

5. Default unstable flags — Power users enabling the same unstable features across all projects.

6. Editor/tooling integration — Default formatter settings, lint preferences for personal projects without a deno.json.

7. Cache directory — Currently DENO_DIR env var; could live in config.

Arguments for

• Env vars are hard to discover and manage — a config file is self-documenting
• Reduces boilerplate for users who work across many small projects/scripts
• Corporate/enterprise environments need machine-wide defaults (proxies, registries, CA certs)
• Every major JS runtime/tool has this: npm (~/.npmrc), Bun (~/.bunfig.toml), Cargo (~/.cargo/config.toml), git (~/.gitconfig)

Arguments against

• Adds complexity to config resolution — "where is this setting coming from?"
• Deno's philosophy leans toward explicit, project-local configuration
• Risk of "works on my machine" when global config masks missing project config
• More env vars + CLI flags might be sufficient

Recommendation

A lightweight global config at ~/.deno/config.json (or $XDG_CONFIG_HOME/deno/config.json) would be valuable, scoped to settings that are genuinely user-level: registry auth, proxy/CA certs, telemetry, default cache dir, and maybe default unstable flags. Project-semantic settings (lint rules, fmt options, import maps, tasks) should stay out of the global config entirely to avoid the "works on my machine" problem. Bun's approach of using the same schema globally and locally with shallow merge is simple but creates that exact risk — Deno could be more intentional by having a smaller, distinct schema for the global config.