normalize config sources

Ensure all runtime and project configuration is explicit, type-safe, and machine-independent. Motivation - Implicit or ad-hoc config (raw process.env usage, feature flags only in local env, or file:///absolute asset paths) causes type errors, unresolved imports, and “works on my machine” failures in CI and collaborators’ environments.

copy reviewer prompt

Prompt

Reviewer Prompt
Deploy Agent

Ensure all runtime and project configuration is explicit, type-safe, and machine-independent.

Motivation

  • Implicit or ad-hoc config (raw process.env usage, feature flags only in local env, or file:///absolute asset paths) causes type errors, unresolved imports, and “works on my machine” failures in CI and collaborators’ environments.

Rules (actionable)

  1. Use a typed env accessor and parse values with defaults
    • Avoid raw process.env access across codebase. Use a shared helper (e.g. std-env or a thin wrapper) so values are typed and consistent.
    • Parse numeric/env values explicitly and provide sane defaults. Example: import { env } from ‘std-env’

    const preferredPort = env.PORT ? parseInt(env.PORT, 10) : 5173

  2. Put feature flags and experimental toggles in project config
    • Add an explicit experimental block to your project schema so flags are part of repository config and travel with the project/CI.
    • Prefer schema validation (Zod or equivalent) so configs are discoverable and validated at startup/build time. Example: export const LikeC4ExperimentalSchema = z.object({ dynamicViewBranches: z.boolean().optional().meta({ description: ‘…’ }) })

    export const LikeC4ProjectJsonConfigSchema = z.object({ // … experimental: LikeC4ExperimentalSchema.optional() })

  3. Normalize asset and file paths in generated/virtual modules
    • Disallow file:// URIs in model/config data. Convert them to repository-relative or project-root-relative paths.
    • When emitting imports in virtual modules for Vite, compute paths relative to the source file or use Vite’s filesystem prefix (/@fs) if appropriate. Test that ?inline requests resolve in dev and build.
    • Detect local images (e.g. startsWith(‘.’) or no protocol) and rewrite imports so Vite can resolve them: e.g. import Icon from './path/to/icon.svg?inline' or /@fs/path/to/icon.svg?inline after computing correct project-relative path.

Checks to run

  • Typecheck: ensure env access types and schema types pass.
  • Dev server import-analysis: run Vite and verify no “Failed to resolve import” errors for generated virtual modules.
  • CI reproducibility: ensure project config (including experimental flags) is present in repository and yields same behavior in CI as locally.

Why this helps

  • Makes configuration explicit and versioned with the project (avoids “works on my machine”).
  • Prevents subtle runtime failures from unresolved imports or incorrect env parsing.
  • Improves developer experience and CI reliability by standardizing where and how configuration is read and validated.

Source discussions