Add the ability to read multiple .env.* files

[damms005]

Discussed in #89

^{Originally posted by gmartinez January 23, 2025}
I have an app that makes use of Laravel ability to use multiple .env files (eg; .env.$string), how about make zero-config have the ability to read all .env.* files in place ?

[traycerai]

Plan

Observations

• All existing .env parsing is hardcoded to read a single .env file via getWorkspaceFileContent or dotenv.parse.
• Key parsing functions live in laravel-core.ts, adonis-core.ts, and laravel-local-sqlite-provider.ts.
• The project already depends on dotenv and filesystem utilities.
• We need a deterministic order: load base .env first, then all .env.* files sorted lexically.

Approach

1. Add helpers to discover and merge multiple .env.* files in the workspace.
2. Replace single-file reads in core and provider modules with new merge logic.
3. Ensure precedence: later-suffixed files override earlier values.
4. Write unit tests for various .env combinations.
5. Update docs and changelog.
6. Maintain backwards compatibility: if only .env exists, behavior is unchanged.

Reasoning

1. Explored extension.ts to locate entrypoints.
2. Identified .env usage in laravel-core.ts, adonis-core.ts, and laravel-local-sqlite-provider.ts.
3. Confirmed getWorkspaceFileContent('.env') is the single source of truth.
4. Verified dotenv is available for parsing.
5. Devised modular helper approach to inject new functionality.

Proposed File Changes

📄 src/services/workspace.ts ^(MODIFY) 🔗

Referred Files

• 📄 src/services/workspace.ts ^(MODIFY)

• At the bottom of src/services/workspace.ts, add two new async functions:
  1. listEnvFiles(): Promise<string[]> —
     • Use filesystem methods to list files in workspace root.
     • Filter names matching /^\.env(\..+)?$/, excluding .env.example.
  2. loadMergedEnv(): Promise<Record<string,string>> —
     • Call listEnvFiles().
     • Sort files: .env first (if present), then other .env.* lex order.
     • For each file, read content (readFileSync) and parse via dotenv.parse.
     • Merge into a single map, letting later files override.
• Export both functions for reuse.

📄 src/services/laravel/laravel-core.ts ^(MODIFY) 🔗

Referred Files

• 📄 src/services/workspace.ts ^(MODIFY)

• Replace existing getEnvFileValue(key) implementation:
  1. Import loadMergedEnv from services/workspace.
  2. In getEnvFileValue, call const allEnv = await loadMergedEnv().
  3. Return allEnv[envFileKey]?.trim() instead of manually reading .env.

📄 src/services/adonis/adonis-core.ts ^(MODIFY) 🔗

Referred Files

• 📄 src/services/workspace.ts ^(MODIFY)

• Similarly replace getEnvFileValue(key):
  1. Import loadMergedEnv.
  2. Call const allEnv = await loadMergedEnv().
  3. Return allEnv[envFileKey]?.trim().

📄 src/providers/sqlite/laravel-local-sqlite-provider.ts ^(MODIFY) 🔗

Referred Files

• 📄 src/services/workspace.ts ^(MODIFY)

• Replace direct getWorkspaceFileContent('.env') + parse with new helper:
  1. Import loadMergedEnv from services/workspace.
  2. In canBeUsedInCurrentWorkspace, call const env = await loadMergedEnv().
  3. Remove parse(envFileContents); use env.DB_CONNECTION, env.DB_DATABASE, etc.

📄 README.md ^(MODIFY) 🔗

Referred Files

• 📄 src/services/workspace.ts ^(MODIFY)

• In README, add a note under configuration:

  Supports multiple environment files: .env, .env.local, .env.development, etc. Values are merged in lex order, with later files overriding earlier ones.

📄 CHANGELOG.md ^(MODIFY) 🔗

• In the next release section, add:
  Added support for multiple '.env.*' files in workspace. Base '.env' is loaded first, then others in lex order.

Sequence Diagram

sequenceDiagram
    participant Caller as Core/Provider
    participant EnvHelper as WorkspaceService
    participant FS as FileSystem
    participant Dotenv

    Caller->>EnvHelper: loadMergedEnv()
    EnvHelper->>FS: list files in workspace
    FS-->>EnvHelper: [".env", ".env.development", ".env.local"]
    EnvHelper->>EnvHelper: sort files [base, others lex]
    loop parse each file
        EnvHelper->>FS: read file content
        FS-->>EnvHelper: file buffer
        EnvHelper->>Dotenv: parse(buffer)
        Dotenv-->>EnvHelper: map
        EnvHelper->>EnvHelper: merge into accumulator
    end
    EnvHelper-->>Caller: merged env map
    Caller-->>Caller: extract requested key

Loading

Import In IDE

Developer Humor

“I used to think one .env file was enough… then I met their siblings! 🎉”

---

Execution Information

Branch: main
Commit: a771b01

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.