hirogakatageri/svelte-env-vars-check

SvelteKit Env Vars Check

Audit SvelteKit environment variable usage for PUBLIC/PRIVATE pattern compliance and process.env violations, then optionally migrate to correct patterns.

SvelteKit Env Var Rules

| Pattern | Module | Who can use it | |---------|--------|----------------| | PUBLIC_* vars | $env/static/public or $env/dynamic/public | Client and server | | Non-public vars | $env/static/private or $env/dynamic/private | Server only | | process.env.* | — | Never — not supported by SvelteKit |

Violations:

1. Client-side using PRIVATE — a client file imports from $env/static/private or $env/dynamic/private
2. Server-side not using PRIVATE — a server file accesses env vars through process.env instead of $env/static/private or $env/dynamic/private
3. process.env anywhere — any file using process.env.* instead of SvelteKit env modules

---

Phase 1: Discover Files

1.1 Identify client-side files

Client-side files are those that run in the browser. In SvelteKit:

• src/**/*.svelte (all Svelte components and pages)
• src/**/+page.ts and src/**/+layout.ts (universal loaders — run on both client and server)
• src/lib/**/*.ts and src/lib/**/*.js not inside a server/ subdirectory

Run:

find src -type f \( -name "*.svelte" -o -name "+page.ts" -o -name "+layout.ts" \) | sort
find src/lib -type f \( -name "*.ts" -o -name "*.js" \) | grep -v '/server/' | sort

1.2 Identify server-side files

Server-side files only run on the server. In SvelteKit:

• src/**/+page.server.ts and src/**/+layout.server.ts
• src/**/+server.ts (API routes / form actions)
• src/lib/server/**/* (server-only library code)

Run:

find src -type f \( -name "+page.server.ts" -o -name "+layout.server.ts" -o -name "+server.ts" \) | sort
find src/lib/server -type f 2>/dev/null | sort

---

Phase 2: Scan for Violations

2.1 Scan for process.env usage (any file)

grep -rn "process\.env\." src/ --include="*.ts" --include="*.js" --include="*.svelte"

Record each match: file path, line number, full line, env var name extracted from process.env.SOME_VAR.

2.2 Scan for PRIVATE imports in client-side files

grep -rn "\$env/static/private\|\$env/dynamic/private" src/ --include="*.svelte" --include="*.ts" --include="*.js"

Cross-reference results against the client-side file list from Phase 1. Any match in a client-side file is a violation.

2.3 Scan for missing PRIVATE pattern in server-side files

grep -rn "\$env/static/public\|\$env/dynamic/public\|process\.env\." src/ --include="*.ts" --include="*.js"

Cross-reference results against the server-side file list from Phase 1. Both of the following are hard violations:

• A server file using process.env instead of a private import
• A server file importing from $env/static/public or $env/dynamic/public

Server-side code must exclusively use $env/static/private or $env/dynamic/private for all env vars. If a var needs to be accessible on the server, it should not carry a PUBLIC_ prefix — rename it and move it to the private module.

2.4 Collect all env var names

From all matches above, extract the env var names:

• From process.env.SOME_VAR → SOME_VAR
• From import { SOME_VAR } from '$env/...' → SOME_VAR

---

Phase 3: Build and Display the Violations Report

Group findings into three categories and display them:

SvelteKit Env Vars Audit Report
================================

Violation 1 — Client-side using PRIVATE pattern
------------------------------------------------
Files that import from $env/static/private or $env/dynamic/private:

  src/routes/dashboard/+page.svelte:12
    import { SECRET_KEY } from '$env/static/private'

  [list each violation]

  Total: N violation(s)

Violation 2 — Server-side not using PRIVATE pattern
----------------------------------------------------
Server files using process.env or importing from $env/*/public instead of $env/static/private or $env/dynamic/private:

  src/routes/api/+server.ts:8
    const key = process.env.API_KEY

  src/routes/data/+server.ts:3
    import { PUBLIC_API_URL } from '$env/static/public'

  [list each violation]

  Total: N violation(s)

Violation 3 — process.env usage
--------------------------------
Any file using process.env instead of SvelteKit env modules:

  src/lib/utils.ts:22
    if (process.env.NODE_ENV === 'production')

  [list each violation]

  Total: N violation(s)

Summary
-------
  Client PRIVATE violations:  N
  Server non-PRIVATE violations: N
  process.env violations:     N
  Total violations:           N

If there are no violations in a category, show:

  (none found)

If there are zero total violations across all categories:

No violations found. All env var usage follows SvelteKit PUBLIC/PRIVATE patterns.

Stop here — do not ask about migration.

---

Phase 4: Ask About Migration

After displaying the report, ask:

Would you like to migrate these violations to the correct SvelteKit env var patterns?

Migration will:
  • Replace process.env.VAR in client files → import PUBLIC_VAR from $env/static/public (or dynamic)
  • Replace process.env.VAR in server files → import VAR from $env/static/private (or dynamic)
  • Move private imports from client files → advise moving logic to server side
  • Update .env variable names where PUBLIC_ prefix is needed

Note: Migrations that cannot be automated safely (e.g., private vars used in client
components that need architectural changes) will be flagged for manual review instead.

Proceed with migration? (yes / no)

If no: skip to Phase 6 (final table only).

4.1 Ask About Timing

If the user answers yes, ask a follow-up before proceeding:

Should env vars be compile-time (static) or runtime (dynamic)?

  [1] static  — $env/static/public  and $env/static/private
                Values are inlined at build time. Faster, but the app must be
                rebuilt to pick up .env changes.

  [2] dynamic — $env/dynamic/public and $env/dynamic/private
                Values are read at request time. The app picks up .env changes
                without a rebuild, but vars are not tree-shaken.

  [3] mixed   — I will specify per-variable.

Choice (1 / 2 / 3):

If 1 (static): use $env/static/public and $env/static/private throughout migration.

If 2 (dynamic): use $env/dynamic/public and $env/dynamic/private throughout migration.

If 3 (mixed): before migrating each distinct env var, ask:

  VAR_NAME — static or dynamic? (s / d)

Record the choice and apply it consistently wherever that var is imported.

---

Phase 5: Perform Migration

Use the timing choice from Phase 4.1 to determine which module to import from:

• Static public → $env/static/public
• Dynamic public → $env/dynamic/public
• Static private → $env/static/private
• Dynamic private → $env/dynamic/private

Work through violations file by file. For each file, read it first, then apply changes.

5.1 Migrate process.env.VAR in client-side files

Action: Replace process.env.VAR with the imported public variable.

Steps:

1. For each process.env.VAR occurrence in a client file:
   • Determine the new name: PUBLIC_VAR (add PUBLIC_ prefix if not already present)
   • Resolve the module based on the timing choice (e.g., $env/static/public or $env/dynamic/public)
   • Add an import at the top of the file:

     import { PUBLIC_VAR } from '$env/<timing>/public';
     

   • Replace all process.env.VAR occurrences with PUBLIC_VAR
2. If the file already imports from the same module, add PUBLIC_VAR to the existing import destructure.
3. Note: The user must also add PUBLIC_VAR=<value> to their .env file (flag this).

5.2 Migrate process.env.VAR in server-side files

Action: Replace process.env.VAR with the imported private variable.

Steps:

1. For each process.env.VAR occurrence in a server file:
   • Keep the same name: VAR (no prefix change needed for private vars)
   • Resolve the module based on the timing choice (e.g., $env/static/private or $env/dynamic/private)
   • Add an import at the top of the file:

     import { VAR } from '$env/<timing>/private';
     

   • Replace all process.env.VAR occurrences with VAR
2. If the file already imports from the same module, add VAR to the existing import destructure.

5.3 Migrate $env/*/public imports in server-side files

Action: Replace public imports with private imports and strip the PUBLIC_ prefix from the var name.

Steps:

1. For each import { PUBLIC_VAR } from '$env/*/public' in a server file:
   • Rename the imported binding: PUBLIC_VAR → VAR (strip PUBLIC_ prefix)
   • Resolve the module based on the timing choice (e.g., $env/static/private or $env/dynamic/private)
   • Replace the import with:

     import { VAR } from '$env/<timing>/private';
     

   • Replace all usages of PUBLIC_VAR in that file with VAR
2. Note: The user must also add VAR=<value> (without PUBLIC_ prefix) to their .env file — flag this.
3. If the same var is still needed in client-side files under its PUBLIC_ name, those client imports remain valid and are untouched.

5.4 Handle PRIVATE imports in client-side files

These require architectural changes that cannot be automated safely.

For each client file with a private import:

⚠️  Cannot auto-migrate: src/routes/dashboard/+page.svelte

  This file imports private env vars (PRIVATE pattern) but runs on the client.
  Private vars must not be exposed to the client.

  Options:
  a) Move the logic that uses this var to a +page.server.ts or +server.ts file
     and pass the result as page data.
  b) If the var is safe to expose publicly, rename it to PUBLIC_VAR and import
     from $env/static/public instead.

  Flagged for manual review.

5.5 Handle process.env.VAR in universal files (+page.ts, +layout.ts)

Universal loaders run on both server and client. Flag these for manual review:

⚠️  Universal file (runs on client + server): src/routes/+page.ts

  process.env.VAR at line N needs manual review.
  - If VAR should be public: use $env/static/public with PUBLIC_ prefix
  - If VAR should be private: move this logic to +page.server.ts

5.6 After each file migration

State what was changed:

✓ Migrated: src/routes/api/+server.ts
  - Replaced process.env.API_KEY → import { API_KEY } from '$env/static/private'
  - Replaced process.env.DB_URL  → import { DB_URL } from '$env/static/private'

---

Phase 6: Final Report Table

After the audit (and migration if performed), output a table of all env vars found:

Environment Variables Inventory
================================

| Name of Env Var | Description |
|-----------------|-------------|
| PUBLIC_API_URL  | Public API base URL — used in client-side fetch calls (src/lib/api.ts). Visibility: client and server. Timing: static. |
| API_KEY         | Private API authentication key — used in server route src/routes/api/+server.ts. Visibility: server only. Timing: dynamic. |
| DB_URL          | Database connection string — used in src/lib/server/db.ts. Visibility: server only. Timing: static. |
| PUBLIC_APP_NAME | Application display name — used in layout component. Visibility: client and server. Timing: static. |

Description column should include:

• What the var is used for (inferred from context)
• Where it appears (file path)
• Visibility: Client and server (PUBLIC_*) or Server only (private)
• Timing: static ($env/static/*) or dynamic ($env/dynamic/*)

If migration was performed, mark migrated vars:

• [migrated] — successfully auto-migrated
• [manual review] — flagged for architectural change

---

Rules

• Never modify files without user confirmation — always ask first (Phase 4).
• Read each file before editing — never blindly apply replacements without reading current content.
• Preserve existing import structure — merge into existing import statements rather than adding duplicate imports.
• Flag, don't guess — if the correct migration for a var is ambiguous, flag it for manual review instead of guessing.
• Stay in src/ — only scan and modify files under the src/ directory.
• .env changes are out of scope — tell the user which .env variables need to be renamed (e.g., VAR → PUBLIC_VAR) but do not modify .env files automatically.