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)
- 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
- 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()
})
- 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.