Manage Secrets and Config in Bun Apps

By Khimananda Oli | Last reviewed: August 2026

Bun’s native compatibility with Node.js APIs makes it easy to manage secrets and config in Bun apps, but that familiarity often leads teams to copy insecure patterns from legacy projects. While Bun automatically loads .env files without external dependencies, production environments demand stricter validation, type safety, and integration with platform-native secret stores rather than static files. This guide covers the complete lifecycle of configuration management in Bun, from local development ergonomics to audit-ready production architectures.

How do you manage secrets and config in Bun apps during local development?

Bun ships with first-class support for environment variables, eliminating the need for dotenv packages that Node.js projects traditionally require. When you run bun run index.ts, Bun automatically reads .env files in your project root and populates Bun.env. This object is a proxy over process.env but provides cleaner ergonomics and direct integration with Bun’s runtime.

Automatic .env Loading Hierarchy

Bun follows a specific precedence order when loading environment files. Understanding this hierarchy prevents subtle bugs where staging values leak into local development or vice versa:

• .env.local — Highest priority, always ignored by git, intended for personal overrides
• .env.[mode] — Environment-specific file (e.g., .env.development, .env.test)
• .env — Base defaults shared across all environments

# .env (committed to repo with safe defaults only)
APP_PORT=3000
LOG_LEVEL=info
DB_HOST=localhost
DB_NAME=myapp_dev

# .env.local (gitignored, contains real credentials)
DB_PASSWORD=supersecret_local_password
JWT_SECRET=local-dev-signing-key-not-for-prod
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

A common mistake I see in teams adopting Bun is placing real credentials in the base .env file because "it works locally." This creates immediate risk when a new developer clones the repo or when CI pipelines accidentally pick up committed secrets. Always treat .env as a template of non-sensitive defaults and put actual credentials exclusively in .env.local.

Accessing Variables Safely

While Bun.env.MY_VAR works identically to process.env.MY_VAR, prefer Bun.env in Bun-native codebases for clarity and future-proofing. Both return string | undefined, which means you must handle missing values explicitly:

// ❌ Dangerous: silent undefined propagation
const port = Bun.env.APP_PORT;
server.listen(port); // NaN if missing, crashes at runtime

// ✅ Safe: fail fast with clear error
const port = Number(Bun.env.APP_PORT);
if (!port || isNaN(port)) {
  throw new Error("APP_PORT is required and must be a valid number");
}

For deeper context on securing infrastructure credentials beyond application-level env vars, refer to our guide on Kubernetes secrets management done right, which covers cluster-level secret handling that complements application-layer patterns.

How do you validate configuration with type safety in Bun?

Raw environment variables are untyped strings. In production systems, especially those subject to SOC 2 or ISO 27001 audits, you need guaranteed shape validation at startup—not runtime failures three hours after deploy when an obscure code path accesses a malformed config value. Schema validation libraries like Zod integrate cleanly with Bun and provide both runtime checking and TypeScript inference.

Building a Validated Config Module

Create a single source of truth for configuration. This module parses, validates, and exports a fully typed object. If any required value is missing or malformed, the application refuses to start:

// src/config.ts
import { z } from "zod";

const configSchema = z.object({
  APP_PORT: z.coerce.number().int().positive().default(3000),
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  REDIS_URL: z.string().url().optional(),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
});

export type AppConfig = z.infer<typeof configSchema>;

function loadConfig(): AppConfig {
  const result = configSchema.safeParse(Bun.env);
  
  if (!result.success) {
    console.error("❌ Invalid configuration:");
    for (const issue of result.error.issues) {
      console.error(`   ${issue.path.join(".")}: ${issue.message}`);
    }
    process.exit(1);
  }
  
  return result.data;
}

// Singleton: validate once at import time
export const config = loadConfig();

This pattern gives you autocomplete throughout your codebase. Any consumer importing config gets full IntelliSense and compile-time guarantees. More importantly, validation errors surface immediately during deployment with actionable messages, not cryptic runtime exceptions deep in request handlers.

How do you handle secrets in Bun Docker containers and CI pipelines?

Docker and CI environments require different secret injection strategies than local development. The fundamental rule: never bake secrets into image layers. Even deleted files persist in layer history and are trivially extractable. Instead, inject secrets at runtime through orchestrator-native mechanisms.

Docker Runtime Injection

Your Dockerfile should contain zero secrets. Use multi-stage builds to keep the final image minimal, and pass configuration entirely through environment variables or mounted secret files at container start:

# Dockerfile
FROM oven/bun:1.2-alpine AS base
WORKDIR /app

FROM base AS install
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile --production

FROM base AS release
COPY --from=install /app/node_modules ./node_modules
COPY src ./src
COPY tsconfig.json ./

# No .env files copied. No secrets in image.
USER bun
EXPOSE 3000
CMD ["bun", "run", "src/index.ts"]

At runtime, inject secrets via your orchestration platform:

# docker-compose.yml (local testing only, never in prod)
services:
  app:
    build: .
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - JWT_SECRET=${JWT_SECRET}
    # Or use Docker secrets in Swarm/Kubernetes
    # secrets:
    #   - db_password

In CI pipelines like GitHub Actions or GitLab CI, use the platform’s native secret store. Never echo secrets to logs, even masked ones. For comprehensive CI security practices, see our article on handling secrets in CI/CD pipelines safely.

How do you integrate Bun with cloud secret managers in production?

For production workloads, especially those requiring compliance certifications, environment variables alone are insufficient. Cloud secret managers provide rotation, access auditing, encryption-at-rest, and fine-grained IAM policies. Bun can fetch these at startup or lazily during execution.

AWS Secrets Manager Integration

Fetch secrets at application bootstrap and merge them into your validated config. This keeps the validation layer intact while sourcing values from a managed store:

// src/secrets/aws.ts
import { GetSecretValueCommand, SecretsManagerClient } from "@aws-sdk/client-secrets-manager";

const client = new SecretsManagerClient({ region: "ap-south-1" });

export async function fetchAwsSecret(secretId: string): Promise<Record<string, string>> {
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: secretId })
  );
  
  if (!response.SecretString) {
    throw new Error(`Secret ${secretId} has no string value`);
  }
  
  return JSON.parse(response.SecretString);
}

// Usage in config.ts
// const awsSecrets = await fetchAwsSecret("myapp/prod/database");
// Merge into Bun.env BEFORE Zod validation runs

Comparison: Secret Storage Approaches for Bun

If you’re running Bun on Kubernetes, combine K8s Secrets with an external operator like External Secrets Operator to sync from AWS/GCP/Azure without granting pods direct cloud API access. Our guide on secrets management with HashiCorp Vault covers advanced multi-backend setups for hybrid environments.

What security pitfalls should you avoid when configuring Bun apps?

Even with proper tooling, misconfiguration remains the leading cause of secret exposure. These are the most frequent issues I encounter during security reviews and audit preparations:

1. Logging entire config objects. Structured logging is essential for observability, but dumping config or Bun.env into log streams exposes credentials in centralized logging platforms. Always redact or exclude sensitive fields. See our structured logging best practices guide for safe patterns.
2. Committing .env files to git. Add .env.local, .env.*.local, and any environment-specific files containing credentials to .gitignore immediately. Use gitleaks or similar tools in pre-commit hooks to catch accidental commits before they reach remote repositories.
3. Hardcoding fallback secrets. Default values like JWT_SECRET || "changeme" create silent security holes. In production, fail loudly instead of falling back to weak defaults. Reserve permissive defaults strictly for development environments.
4. Sharing secrets across environments. Staging and production must have completely separate credentials. A compromised staging database should never grant access to production data. Use distinct secret paths/namespaces per environment.
5. Ignoring secret rotation. Static credentials that never rotate are a ticking clock. Implement automated rotation through your secret manager and ensure your Bun app handles credential refresh gracefully, either through restart or hot-reload mechanisms.

Next Steps for Secure Bun Configuration

Getting configuration right in Bun requires treating it as a first-class engineering concern, not an afterthought. Start with validated schemas using Zod, enforce strict separation between local and production secret sources, and integrate with your cloud provider’s managed secret store before your next compliance review. If your team needs help designing audit-ready secret management architecture for Bun applications or migrating legacy Node.js configs to secure Bun patterns, reach out to discuss your infrastructure.