config-type-safety.mdc

---
description: Config and type safety rules - no defaults, no non-null assertions outside config
globs:
  - "**/config/index.ts"
  - "**/config/*.ts"
alwaysApply: false
---

# Config and Type Safety Rules

## Critical Requirements

### 1. Never Set Default Values in Config Files

**NEVER** set default values for environment variables in `config/index.ts` files. This includes:

- Empty strings: `process.env.VAR || ''`
- Fallback values: `process.env.VAR || 'default'`
- Nullish coalescing: `process.env.VAR ?? ''`

**Why**: Default values hide configuration errors and allow apps to start with invalid state.

### 2. Use Non-Null Assertions (`!`) in Config Files Only

Config files are the **one exception** where `!` assertions are allowed, because:

- All env vars must pass through startup validation before config is used
- Validation ensures required values exist before the app starts
- This keeps config files clean and typed as `string` (not `string | undefined`)

**Pattern for config files:**

```typescript
/* eslint-disable @typescript-eslint/no-non-null-assertion -- env vars validated at startup */

export const config = {
  nodeEnv: process.env.NODE_ENV!,
  apiPort: process.env.API_PORT!,
  database: {
    host: process.env.DB_HOST!,
  },
};
```

### 3. Avoid Non-Null Assertions Elsewhere

Outside of config files, **avoid** `!` assertions. Prefer proper null checks, optional chaining, or type guards.

## Approved Patterns

### Backend Apps (api, management-api)

1. **Create startup validation** (`lib/startup/validation.ts`).
2. **Call validation early in app startup** before importing config.
3. **Use `!` in config with eslint-disable** (`config/index.ts`).

### Next.js Apps (web, management-web)

Validate at build time via app validate-env scripts and prebuild hooks where configured.

## Summary

| Location | `!` Allowed | Default Values |
| -------- | ----------- | ---------------- |
| `config/index.ts` | ✅ Yes (with eslint-disable) | ❌ Never |
| Other files | ❌ Avoid | Use at point of use if needed |