@withmata/blueprints 0.2.0 → 0.3.2

package/blueprints/features/env-t3/BLUEPRINT.md

@@ -0,0 +1,332 @@
+# Environment Variables Blueprint — T3 Env + Zod Validation
+
+## Tier
+
+Feature
+
+## Status
+
+Complete.
+
+## Problem
+
+Environment variable management is tedious and error-prone across projects. Developers forget to add new variables to `.env.example`, miss the split between client and server vars in Next.js, deploy with missing variables that only crash at runtime, and have no type safety when accessing `process.env`. This blueprint creates a validated, type-safe environment variable system using `@t3-oss/env` + Zod that catches missing or malformed variables at build time.
+
+This blueprint covers both Next.js apps (client/server split with `@t3-oss/env-nextjs`) and backend apps (server-only with `@t3-oss/env-core`).
+
+## Blueprint Dependencies
+
+None. This blueprint is standalone and can be installed into any project.
+
+### Interaction with Other Blueprints
+
+Feature blueprints that introduce environment variables (auth, db, etc.) should merge their vars into the env files this blueprint creates. The `// CONFIGURE:` comments mark where to add new variables.
+
+- **auth-better-auth**: Adds `BETTER_AUTH_URL`, `BETTER_AUTH_SECRET`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` to `env/server.ts`
+- **db-drizzle-postgres**: Adds `DATABASE_URL` to `packages/db/.env` (monorepo) or root `.env` (single-repo) — not to the app's env files
+
+---
+
+## Architecture
+
+### Core Pattern
+
+Every app in the project gets Zod-validated environment variables through `@t3-oss/env`. Variables are validated at startup (or build time for Next.js) — if any are missing or malformed, the app fails immediately with a clear error instead of crashing later at the point of use.
+
+**Next.js apps** use a two-file split:
+- `src/env/client.ts` — client-side variables (`NEXT_PUBLIC_*`) using `@t3-oss/env-nextjs`
+- `src/env/server.ts` — server-side variables using `@t3-oss/env-nextjs` with `experimental__runtimeEnv: process.env`
+
+Both files are imported in `next.config.ts` to trigger build-time validation.
+
+**Backend apps** (Hono, Express, Node) use a single file:
+- `src/env.ts` — all server variables using `@t3-oss/env-core` with `dotenv/config`
+
+### Key Decisions
+
+- **Client/server split for Next.js** (required) — Next.js runs code in both client and server contexts. Client variables must use the `NEXT_PUBLIC_` prefix and be declared in a `client` schema. Server variables must NOT be in the client schema (they'd be exposed to the browser). The two-file split enforces this boundary structurally.
+
+- **`experimental__runtimeEnv: process.env` for server vars** (required) — Server variables in Next.js use `experimental__runtimeEnv` instead of listing each variable in `runtimeEnv`. This avoids the tedious boilerplate of repeating every server variable name twice (once in the schema, once in runtimeEnv).
+
+- **`emptyStringAsUndefined: true`** (required) — Empty string environment variables are treated as undefined. This prevents the common mistake of setting `DATABASE_URL=` in `.env` and having it pass Zod validation as a valid string.
+
+- **Build-time validation via `next.config.ts` import** (required) — Importing the env files at the top of `next.config.ts` ensures validation runs during `next build`. Missing variables fail the build rather than causing runtime errors in production.
+
+- **`@t3-oss/env-core` for backend apps** (required) — Backend apps don't have the Next.js client/server split, so they use the simpler `@t3-oss/env-core` package with `dotenv/config` for `.env` file loading.
+
+- **`z.preprocess` for PORT** (recommended) — Environment variables are always strings. PORT needs to be a number. `z.preprocess` handles the string-to-number conversion cleanly.
+
+- **`.env.example` with documentation** (required) — Every app gets a documented `.env.example` with section headers, comments explaining each variable, and local/production value hints. This is the single source of truth for what environment variables an app needs.
+
+- **Empty `.env.local` created** (required) — An empty `.env.local` file is created during scaffolding so developers have the file ready to fill in. This file is gitignored.
+
+---
+
+## Hard Requirements vs Recommended Defaults
+
+**Hard requirements:**
+- `@t3-oss/env-nextjs` for Next.js apps
+- `@t3-oss/env-core` for backend apps
+- Zod for schema validation
+- Client/server split in Next.js (two files)
+- Build-time validation via `next.config.ts` import
+- `.env.example` for every app
+
+**Recommended defaults — ask during scaffolding:**
+
+| Choice | Recommended | Alternatives |
+|---|---|---|
+| Next.js env location | `src/env/client.ts` + `src/env/server.ts` | `env/client.ts` + `env/server.ts` (no `src/` prefix) |
+| Backend env location | `src/env.ts` | `env.ts` at app root |
+| Include PORT in backend env | Yes | No (if platform handles it) |
+| Create `.env.local` | Yes | No (if using `.env` directly) |
+
+---
+
+## Dependencies
+
+### npm packages
+
+**Next.js apps:**
+| Package | Version | Purpose |
+|---|---|---|
+| `@t3-oss/env-nextjs` | ^0.13 | Environment variable validation for Next.js (client/server split) |
+| `zod` | ^3.24 | Schema validation |
+
+**Backend apps:**
+| Package | Version | Purpose |
+|---|---|---|
+| `@t3-oss/env-core` | ^0.13 | Environment variable validation for Node.js |
+| `zod` | ^3.24 | Schema validation |
+| `dotenv` | ^16.4 | Load `.env` files (backend only — Next.js handles this natively) |
+
+### Environment Variables
+
+| Variable | Where | Description |
+|---|---|---|
+| `NEXT_PUBLIC_FRONTEND_URL` | Next.js client | Frontend URL for redirects, CORS, metadata |
+
+Additional variables are added by feature blueprints (auth, db, etc.).
+
+---
+
+## Monorepo Wiring
+
+### Next.js App (`apps/web/`)
+
+The env files live inside the app directory — no shared package needed. Each Next.js app manages its own env validation.
+
+**File structure:**
+```
+apps/web/
+├── src/env/
+│   ├── client.ts              # Client env schema + validation
+│   └── server.ts              # Server env schema + validation
+├── next.config.ts             # Imports both env files for build-time validation
+├── .env.example               # Documented env template
+└── .env.local                 # Local values (gitignored)
+```
+
+**`next.config.ts` integration:**
+```typescript
+import "./src/env/server";
+import "./src/env/client";
+```
+
+**Consuming env in code:**
+```typescript
+// In server components, API routes, server actions:
+import { serverEnv } from "~/env/server";
+const dbUrl = serverEnv.DATABASE_URL;
+
+// In client components:
+import { clientEnv } from "~/env/client";
+const apiUrl = clientEnv.NEXT_PUBLIC_API_URL;
+```
+
+### Backend App (`apis/server/`)
+
+**File structure:**
+```
+apis/server/
+├── src/
+│   ├── env.ts                 # Server env schema + validation
+│   └── index.ts               # Imports env.ts at top
+├── .env.example               # Documented env template
+└── .env.local                 # Local values (gitignored)
+```
+
+**Entry point integration:**
+```typescript
+// src/index.ts
+import { env } from "./env.js";
+const port = env.PORT;
+```
+
+---
+
+## Single-Repo Adaptation
+
+For standalone applications (Next.js or backend) without a monorepo, the patterns are identical — only file placement differs slightly.
+
+### Path Mapping
+
+| Aspect | Monorepo | Single-Repo |
+|--------|----------|-------------|
+| Next.js env location | `apps/web/src/env/` | `src/env/` |
+| Backend env location | `apis/server/src/env.ts` | `src/env.ts` |
+| `.env.example` location | Per-app (e.g., `apps/web/.env.example`) | Project root `.env.example` |
+| `.env.local` location | Per-app (e.g., `apps/web/.env.local`) | Project root `.env.local` |
+| Import path | `~/env/server` or `~/env/client` | `~/env/server` or `@/env/server` |
+
+### What Stays the Same
+
+All core patterns are project-type-agnostic:
+- `@t3-oss/env-nextjs` for Next.js, `@t3-oss/env-core` for backend
+- Zod schemas for validation
+- Client/server split (two files) for Next.js
+- Build-time validation via `next.config.ts` import
+- `.env.example` documentation pattern
+- `emptyStringAsUndefined: true`
+
+---
+
+## File Manifest
+
+| File | Purpose | Monorepo Target | Single-Repo Target |
+|---|---|---|---|
+| `files/nextjs/env/client.ts` | Next.js client env schema | `apps/web/src/env/client.ts` | `src/env/client.ts` |
+| `files/nextjs/env/server.ts` | Next.js server env schema | `apps/web/src/env/server.ts` | `src/env/server.ts` |
+| `files/nextjs/.env.example` | Documented env template (Next.js) | `apps/web/.env.example` | `.env.example` |
+| `files/nextjs/.env.local` | Empty local env file (Next.js) | `apps/web/.env.local` | `.env.local` |
+| `files/server/env.ts` | Backend env schema (`@t3-oss/env-core`) | `apis/server/src/env.ts` | `src/env.ts` |
+| `files/server/.env.example` | Documented env template (backend) | `apis/server/.env.example` | `.env.example` |
+| `files/server/.env.local` | Empty local env file (backend) | `apis/server/.env.local` | `.env.local` |
+
+---
+
+## Integration Steps
+
+### Phase 1: Next.js App Setup
+
+1. Create `src/env/` directory in the target Next.js app
+2. Copy `env/client.ts` — replace `{{APP_NAME}}` in comments
+3. Copy `env/server.ts` — replace `{{APP_NAME}}` in comments
+4. If an existing `env.ts` file exists at the app root:
+   - Read it to extract any existing variables
+   - Merge them into the appropriate file (client or server) based on the `NEXT_PUBLIC_` prefix
+   - Remove the old `env.ts`
+5. Update `next.config.ts` — add imports at the top:
+   ```typescript
+   import "./src/env/server";
+   import "./src/env/client";
+   ```
+   If existing `import "./env"` is present, replace it with the two new imports.
+6. Copy `.env.example` — replace `{{APP_NAME}}`
+7. Create `.env.local` (empty)
+8. If other blueprints are already installed, pre-populate their env vars into the appropriate schema files
+
+### Phase 2: Backend App Setup (if present)
+
+9. Copy `env.ts` to `src/env.ts` in the backend app — replace `{{APP_NAME}}`
+10. Update the app's entry point (e.g., `src/index.ts`) to import `env.ts`:
+    ```typescript
+    import { env } from "./env.js";
+    ```
+11. Copy `.env.example` — replace `{{APP_NAME}}`
+12. Create `.env.local` (empty)
+
+### Phase 3: Dependency Installation
+
+13. For each Next.js app: ensure `@t3-oss/env-nextjs` and `zod` are in `dependencies`
+14. For each backend app: ensure `@t3-oss/env-core`, `zod`, and `dotenv` are in `dependencies`
+
+### Phase 4: Verification
+
+15. Run `pnpm dev` (or equivalent) — env validation should run without errors
+16. Try removing a required variable from `.env.local` — build should fail with a clear error message
+
+---
+
+## Maintenance Hooks
+
+### Environment Variable Hooks
+
+| When you... | Then do... | Why |
+|---|---|---|
+| Add a new env var in code | Add to `env/client.ts` or `env/server.ts` schema AND `.env.example` AND `.env.local` | Missing from schema = build-time crash; missing from example = teammates can't set up |
+| Add a `NEXT_PUBLIC_*` var | Put it in `env/client.ts` with both `client` schema and `runtimeEnv` entries | Client vars must be explicitly mapped in Next.js |
+| Add a server-only var to Next.js | Put it in `env/server.ts` (uses `experimental__runtimeEnv: process.env`) | Avoids listing every server var twice |
+| Remove an env var | Remove from schema file, `.env.example`, and `.env.local` | Stale vars cause confusion |
+| Add a new app to the monorepo | Create its own `env/` files — don't share env schemas between apps | Each app has different variable requirements |
+| Change a var from optional to required | Update the Zod schema (remove `.optional()`) and ensure `.env.example` has a value | Will break builds for teammates with empty values |
+
+### Condensed Rules for project rules file
+
+```markdown
+### env-t3 maintenance
+- After adding a new env var: add it to the env schema file (client.ts or server.ts), `.env.example`, and `.env.local`
+- NEXT_PUBLIC_* vars go in env/client.ts with explicit runtimeEnv mapping; server vars go in env/server.ts
+- After removing an env var: remove from schema, .env.example, and .env.local
+- Never access process.env directly — always use the typed env objects (clientEnv, serverEnv, or env)
+- Keep .env.example documented with section headers and local/production hints
+```
+
+---
+
+## What's Configurable
+
+- Env file location (`src/env/` vs `env/`)
+- Which apps get env setup (Next.js, backend, or both)
+- Starting variables (pre-populated from other installed blueprints)
+- PORT default value for backend apps
+
+## What's Opinionated
+
+- **T3 Env** — the only supported env validation library (provides the best DX for Next.js client/server split)
+- **Zod** — the only supported schema library (required by T3 Env)
+- **Client/server split** — Next.js apps always get two files, not one combined file
+- **Build-time validation** — env files are always imported in `next.config.ts`
+- **`emptyStringAsUndefined`** — always enabled (prevents empty string foot-guns)
+- **`.env.example` documentation** — always includes section headers and comments
+
+## Project Context Output
+
+Appends to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### env-t3
+blueprint: env-t3
+choices:
+  nextjs_env_location: src/env/
+  backend_env_location: src/env.ts
+apps_configured:
+  - name: web
+    type: nextjs
+    files:
+      - src/env/client.ts
+      - src/env/server.ts
+      - .env.example
+      - .env.local
+  - name: server
+    type: backend
+    files:
+      - src/env.ts
+      - .env.example
+      - .env.local
+packages_added:
+  - "@t3-oss/env-nextjs"
+  - "@t3-oss/env-core"
+  - zod
+  - dotenv
+```
+
+---
+
+## References
+
+- **T3 Env Docs:** https://env.t3.gg/docs/introduction
+- **T3 Env Next.js:** https://env.t3.gg/docs/nextjs
+- **T3 Env Core:** https://env.t3.gg/docs/core
+- **Zod Docs:** https://zod.dev/
+- **Next.js Environment Variables:** https://nextjs.org/docs/app/building-your-application/configuring/environment-variables

package/blueprints/features/env-t3/files/nextjs/.env.example

@@ -0,0 +1,17 @@
+# =============================================================================
+# {{APP_NAME}} — Environment Variables
+# =============================================================================
+# Copy this file to .env.local and fill in the values.
+# Feature blueprints will add their own variables — check their BLUEPRINT.md.
+
+# -----------------------------------------------------------------------------
+# App
+# -----------------------------------------------------------------------------
+
+# Frontend URL (used for redirects, CORS, and metadata)
+# Local: http://localhost:3000 | Production: https://yourdomain.com
+NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000
+
+# CONFIGURE: Feature blueprints add variables here:
+# - /scaffold-auth adds: BETTER_AUTH_URL, BETTER_AUTH_SECRET, GOOGLE_CLIENT_ID, etc.
+# - /scaffold-db adds: DATABASE_URL (in packages/db/.env for monorepos)

package/blueprints/features/env-t3/files/nextjs/env/client.ts

@@ -0,0 +1,13 @@
+import { createEnv } from "@t3-oss/env-nextjs";
+import { z } from "zod";
+
+export const clientEnv = createEnv({
+  client: {
+    NEXT_PUBLIC_FRONTEND_URL: z.string().url(),
+    // CONFIGURE: Feature blueprints add client env vars here
+    // e.g., NEXT_PUBLIC_API_URL: z.string().url(),
+  },
+  runtimeEnv: {
+    NEXT_PUBLIC_FRONTEND_URL: process.env.NEXT_PUBLIC_FRONTEND_URL,
+  },
+});

package/blueprints/features/env-t3/files/nextjs/env/server.ts

@@ -0,0 +1,12 @@
+import { createEnv } from "@t3-oss/env-nextjs";
+import { z } from "zod";
+
+export const serverEnv = createEnv({
+  server: {
+    // CONFIGURE: Feature blueprints add server env vars here
+    // e.g., DATABASE_URL: z.string().url(),
+    // e.g., BETTER_AUTH_SECRET: z.string().min(32),
+  },
+  experimental__runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+});

package/blueprints/features/env-t3/files/server/.env.example

@@ -0,0 +1,14 @@
+# =============================================================================
+# {{APP_NAME}} Server — Environment Variables
+# =============================================================================
+# Copy this file to .env.local and fill in the values.
+
+# -----------------------------------------------------------------------------
+# Server Configuration
+# -----------------------------------------------------------------------------
+
+# Port the server listens on
+# Local: 4000 | Production: Set by hosting platform
+PORT=4000
+
+# CONFIGURE: Add server-specific variables below

package/blueprints/features/env-t3/files/server/env.ts

@@ -0,0 +1,17 @@
+import "dotenv/config";
+import { createEnv } from "@t3-oss/env-core";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    PORT: z.preprocess(
+      (s) => parseInt(String(s), 10) || undefined,
+      z.number().min(1).default(4000),
+    ),
+    // CONFIGURE: Add server env vars here
+    // e.g., DATABASE_URL: z.string().url(),
+    // e.g., REDIS_URL: z.string().min(1),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+});