Skip to content

Docs request: Add Codespaces/.env best practices guidance (.env vs .env.local) #420

Description

Summary

Please add an official Codespaces documentation section covering best practices for organizing and handling environment variable files such as .env and .env.local.

Codespaces users often rely on dotenv-compatible workflows across Node.js, Next.js, React, Vite, Vue, and similar stacks. Today there is no single canonical guidance from GitHub that clearly explains safe naming, gitignore strategy, precedence order, and secret handling in Codespaces contexts.

Why this matters

  • Prevents accidental secret leaks from committed local override files.
  • Improves consistency across teams and frameworks.
  • Reduces onboarding friction in repos using dev containers and dotenv files.
  • Clarifies how Codespaces secrets should be used instead of committed credentials.

Proposed documentation content

1) Recommended dotenv file organization

Include a table like:

File Purpose Version Control Typical Use
.env Shared defaults Commit (no real secrets) Base app config
.env.local Local machine overrides Ignore Developer-specific secrets
.env.development Development environment defaults Commit (no secrets) Dev-only non-sensitive values
.env.production Production environment defaults Commit (no secrets) Production non-sensitive settings
.env.test Test environment defaults Commit (no secrets) Test config
.env.production.local Local production overrides Ignore Rare machine-specific production secrets

2) Precedence and loading order guidance

Document the typical override sequence and mention that framework behavior can differ. A practical pattern:

  1. .env
  2. .env.local
  3. .env.{NODE_ENV}
  4. .env.{NODE_ENV}.local

Also include examples for common frameworks (Next.js, CRA, Vite, Node + dotenv).

3) Security and gitignore recommendations

Recommend entries such as:

.env.local
.env.*.local

And reinforce:

  • Never commit real secrets.
  • Use GitHub Codespaces secrets and/or Actions secrets for sensitive values.
  • Keep .env.example for required variable names with dummy placeholders.

4) Codespaces-specific implementation pattern

Show a sample devcontainer setup that injects Codespaces secrets through containerEnv or remoteEnv, optionally generating .env.local in postCreateCommand for apps that expect file-based loading.

5) Common mistakes section

Examples:

  • Committing real credentials in .env or .env.local.
  • Treating .env.local as shared defaults.
  • Missing .env.example documentation.
  • Assuming all frameworks use identical load order.

Suggested one-line rule

Keep shared defaults in .env (without secrets), local secrets in .env.local (ignored), and environment-specific defaults in .env.{environment} files.

Request

Could this be added either:

  • directly in Codespaces documentation, or
  • as a dedicated sample/best-practices page linked from codespaces-devcontainer-samples?

Thanks for considering this; it would materially improve security and consistency for many Codespaces users.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions