create-pyro 0.1.0 → 0.2.0

package/template/compose.yml

@@ -0,0 +1,75 @@
+name: my-pyro-app
+
+services:
+  postgres:
+    image: postgres:18-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:?see .env.example}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?see .env.example}
+      POSTGRES_DB: ${POSTGRES_DB:?see .env.example}
+    volumes:
+      - postgres_data:/var/lib/postgresql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  migrator:
+    build:
+      context: .
+      dockerfile: packages/db/Dockerfile
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: "no"
+
+  api:
+    build:
+      context: .
+      dockerfile: apps/api/Dockerfile
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+      API_PORT: 3002
+      BETTER_AUTH_URL: ${PUBLIC_ORIGIN:-http://localhost}
+      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET:?see .env.example}
+      CORS_ORIGIN: ${PUBLIC_ORIGIN:-http://localhost}
+    depends_on:
+      migrator:
+        condition: service_completed_successfully
+    restart: unless-stopped
+
+  web:
+    build:
+      context: .
+      dockerfile: apps/web/Dockerfile
+    environment:
+      NODE_ENV: production
+      PORT: 3000
+      PUBLIC_API_URL: ${PUBLIC_ORIGIN:-http://localhost}
+      INTERNAL_API_URL: http://api:3002
+    depends_on:
+      api:
+        condition: service_healthy
+    restart: unless-stopped
+
+  nginx:
+    image: nginx:1.30-alpine
+    ports:
+      - "80:80"
+    volumes:
+      - ./infra/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
+    depends_on:
+      web:
+        condition: service_healthy
+      api:
+        condition: service_healthy
+    restart: unless-stopped
+
+volumes:
+  postgres_data:

package/template/gitignore

@@ -1,2 +1,33 @@
-# dependencies
+# deps
 node_modules/
+.pnpm-store/
+
+# output
+dist/
+
+# react router
+.react-router/
+
+# env
+.env*
+!.env.example
+
+# logs
+logs/
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# editor
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+
+# turbo
+.turbo
+
+# misc
+.DS_Store
+Thumbs.db
+*.local
+*.tsbuildinfo

package/template/infra/nginx/default.conf

@@ -0,0 +1,33 @@
+server {
+    listen 80 default_server;
+    server_name _;
+
+    client_max_body_size 10m;
+
+    # Docker's embedded DNS. Resolving per request (via the variables below)
+    # lets nginx start before the upstreams and survive their restarts.
+    resolver 127.0.0.11 valid=10s ipv6=off;
+
+    set $api_upstream http://api:3002;
+    set $web_upstream http://web:3000;
+
+    location /api/ {
+        proxy_pass $api_upstream;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location / {
+        proxy_pass $web_upstream;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}

package/template/package.json

@@ -2,5 +2,27 @@
   "name": "my-pyro-app",
   "private": true,
   "version": "0.1.0",
-  "type": "module"
+  "type": "module",
+  "packageManager": "pnpm@12.15.0",
+  "scripts": {
+    "dev": "turbo dev",
+    "build": "turbo build",
+    "start": "turbo start",
+    "lint": "biome check --write",
+    "lint:ci": "biome ci",
+    "typecheck": "turbo typecheck",
+    "test": "turbo test",
+    "db:generate": "turbo build --filter=./packages/config --output-logs=errors-only && pnpm -F db generate",
+    "db:migrate": "turbo build --filter=./packages/config --output-logs=errors-only && pnpm -F db migrate",
+    "db:push": "turbo build --filter=./packages/config --output-logs=errors-only && pnpm -F db push",
+    "db:studio": "turbo build --filter=./packages/config --output-logs=errors-only && pnpm -F db studio"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.3",
+    "turbo": "^2.11.10"
+  },
+  "engines": {
+    "node": ">=24",
+    "pnpm": ">=12"
+  }
 }

package/template/packages/config/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@repo/config",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch --no-clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts"
+}

package/template/packages/config/src/index.test.ts

@@ -0,0 +1,100 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+beforeEach(() => {
+  vi.resetModules();
+  vi.unstubAllEnvs();
+});
+
+const DB_URL = "postgresql://app:password@localhost:15432/app";
+const SECRET = "a".repeat(32);
+
+describe("laziness", () => {
+  it("importing the module never throws, even with an empty environment", async () => {
+    await expect(import("./index")).resolves.toBeDefined();
+  });
+});
+
+describe("dbEnv", () => {
+  it("reads DATABASE_URL", async () => {
+    vi.stubEnv("DATABASE_URL", DB_URL);
+    const { dbEnv } = await import("./index");
+    expect(dbEnv.DATABASE_URL).toBe(DB_URL);
+  });
+
+  it("does not require variables from other scopes", async () => {
+    vi.stubEnv("DATABASE_URL", DB_URL);
+    vi.stubEnv("BETTER_AUTH_SECRET", "");
+    vi.stubEnv("CORS_ORIGIN", "");
+    const { dbEnv } = await import("./index");
+    expect(() => dbEnv.DATABASE_URL).not.toThrow();
+  });
+
+  it("explains an absent variable rather than reporting a type error", async () => {
+    vi.stubEnv("DATABASE_URL", undefined);
+    const { dbEnv } = await import("./index");
+    expect(() => dbEnv.DATABASE_URL).toThrow(/DATABASE_URL: required/);
+    expect(() => dbEnv.DATABASE_URL).not.toThrow(/received undefined/);
+  });
+});
+
+describe("authEnv", () => {
+  it("reports every problem in the scope at once", async () => {
+    vi.stubEnv("BETTER_AUTH_URL", "not-a-url");
+    vi.stubEnv("BETTER_AUTH_SECRET", "too-short");
+    const { authEnv } = await import("./index");
+    let message = "";
+    try {
+      void authEnv.BETTER_AUTH_URL;
+    } catch (err) {
+      message = err instanceof Error ? err.message : "";
+    }
+    expect(message).toContain("BETTER_AUTH_URL");
+    expect(message).toContain("BETTER_AUTH_SECRET");
+  });
+
+  it("accepts a valid scope", async () => {
+    vi.stubEnv("BETTER_AUTH_URL", "http://localhost:3002/");
+    vi.stubEnv("BETTER_AUTH_SECRET", SECRET);
+    const { authEnv } = await import("./index");
+    expect(authEnv.BETTER_AUTH_URL).toBe("http://localhost:3002");
+  });
+});
+
+describe("apiEnv", () => {
+  it("applies defaults for the port and NODE_ENV", async () => {
+    vi.stubEnv("CORS_ORIGIN", "http://localhost:3000");
+    vi.stubEnv("NODE_ENV", undefined);
+    vi.stubEnv("API_PORT", undefined);
+    const { apiEnv } = await import("./index");
+    expect(apiEnv.API_PORT).toBe(3002);
+    expect(apiEnv.NODE_ENV).toBe("development");
+  });
+
+  it("coerces a port from a string", async () => {
+    vi.stubEnv("CORS_ORIGIN", "http://localhost:3000");
+    vi.stubEnv("API_PORT", "4000");
+    const { apiEnv } = await import("./index");
+    expect(apiEnv.API_PORT).toBe(4000);
+  });
+
+  it("rejects a CORS_ORIGIN that is not an absolute URL", async () => {
+    vi.stubEnv("CORS_ORIGIN", "localhost:3000");
+    const { apiEnv } = await import("./index");
+    expect(() => apiEnv.CORS_ORIGIN).toThrow(/CORS_ORIGIN/);
+  });
+});
+
+describe("webEnv", () => {
+  it("rejects a PUBLIC_API_URL with a trailing /api", async () => {
+    vi.stubEnv("PUBLIC_API_URL", "http://localhost/api");
+    const { webEnv } = await import("./index");
+    expect(() => webEnv.PUBLIC_API_URL).toThrow(/PUBLIC_API_URL/);
+  });
+
+  it("defaults INTERNAL_API_URL for the non-Docker dev loop", async () => {
+    vi.stubEnv("PUBLIC_API_URL", "http://localhost:3002");
+    vi.stubEnv("INTERNAL_API_URL", undefined);
+    const { webEnv } = await import("./index");
+    expect(webEnv.INTERNAL_API_URL).toBe("http://localhost:3002");
+  });
+});

package/template/packages/config/src/index.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+
+const nodeEnv = z
+  .enum(["development", "production", "test"])
+  .default("development");
+
+const required = (hint: string) =>
+  z.string(`required — ${hint}`).min(1, `required — ${hint}`);
+
+const port = (fallback: number) =>
+  z.coerce.number().int().min(1).max(65535).default(fallback);
+
+const origin = (label: string) =>
+  required(`${label}, as an absolute http(s) URL`)
+    .refine((value) => {
+      try {
+        const { protocol } = new URL(value);
+        return protocol === "http:" || protocol === "https:";
+      } catch {
+        return false;
+      }
+    }, `${label} — must be an absolute http(s) URL, e.g. http://localhost:3000`)
+    .refine(
+      (value) => !/\/api\/?$/.test(value),
+      `${label} — must be an origin only; drop the trailing "/api" (call sites append their own /api/... path)`,
+    )
+    .transform((value) => value.replace(/\/+$/, ""));
+
+const dbSchema = z.object({
+  DATABASE_URL: required("e.g. postgresql://app:password@localhost:15432/app"),
+});
+
+const authSchema = z.object({
+  BETTER_AUTH_URL: origin("origin of the API"),
+  BETTER_AUTH_SECRET: required("generate with `openssl rand -base64 32`").min(
+    32,
+    "must be at least 32 chars — generate with `openssl rand -base64 32`",
+  ),
+});
+
+const apiSchema = z.object({
+  NODE_ENV: nodeEnv,
+  API_PORT: port(3002),
+  CORS_ORIGIN: origin("origin of the web app"),
+});
+
+const webSchema = z.object({
+  NODE_ENV: nodeEnv,
+  PUBLIC_API_URL: origin("public origin of the API"),
+  INTERNAL_API_URL: origin("internal origin of the API").default(
+    "http://localhost:3002",
+  ),
+});
+
+function formatIssues(scope: string, error: z.ZodError): string {
+  const lines = error.issues.map((issue) => {
+    const key = issue.path.join(".") || "(root)";
+    return `  ${key}: ${issue.message}`;
+  });
+  return `Invalid environment for "${scope}":\n${lines.join("\n")}\n\nSee .env.example at the repo root.`;
+}
+
+/**
+ * Validates `process.env` against `schema` on first property access, not on
+ * import, so a process only needs the variables of the scopes it reads.
+ */
+function lazyEnv<T extends z.ZodType<object>>(
+  scope: string,
+  schema: T,
+): z.infer<T> {
+  let cached: z.infer<T> | undefined;
+
+  const load = (): z.infer<T> => {
+    if (cached) return cached;
+    const parsed = schema.safeParse(process.env);
+    if (!parsed.success) throw new Error(formatIssues(scope, parsed.error));
+    cached = parsed.data;
+    return cached;
+  };
+
+  return new Proxy({} as z.infer<T>, {
+    get: (_target, prop) => load()[prop as keyof z.infer<T>],
+    has: (_target, prop) => prop in load(),
+    ownKeys: () => Reflect.ownKeys(load()),
+    getOwnPropertyDescriptor: (_target, prop) => ({
+      ...Object.getOwnPropertyDescriptor(load(), prop),
+      configurable: true,
+    }),
+  });
+}
+
+export const dbEnv = lazyEnv("db", dbSchema);
+export const authEnv = lazyEnv("auth", authSchema);
+export const apiEnv = lazyEnv("api", apiSchema);
+export const webEnv = lazyEnv("web", webSchema);
+
+export type DbEnv = z.infer<typeof dbSchema>;
+export type AuthEnv = z.infer<typeof authSchema>;
+export type ApiEnv = z.infer<typeof apiSchema>;
+export type WebEnv = z.infer<typeof webSchema>;

package/template/packages/config/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "noEmit": false
+  },
+  "exclude": ["src/**/*.test.ts"]
+}

package/template/packages/config/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/template/packages/config/tsdown.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  tsconfig: "tsconfig.build.json",
+  entry: ["src/index.ts"],
+  format: ["esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  treeshake: true,
+  target: false,
+});

package/template/packages/db/Dockerfile

@@ -0,0 +1,22 @@
+# One-shot migrator: applies packages/db/drizzle against DATABASE_URL, then exits.
+FROM node:24-alpine
+WORKDIR /app
+
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml tsconfig.json ./
+COPY apps/api/package.json ./apps/api/
+COPY apps/web/package.json ./apps/web/
+COPY packages/config/package.json ./packages/config/
+COPY packages/db/package.json ./packages/db/
+COPY packages/shared/package.json ./packages/shared/
+
+RUN corepack enable && pnpm install --frozen-lockfile --filter @repo/db...
+
+COPY packages/config ./packages/config
+COPY packages/db ./packages/db
+
+RUN pnpm --filter @repo/config build
+
+USER node
+WORKDIR /app/packages/db
+
+CMD ["node_modules/.bin/drizzle-kit", "migrate", "--config", "drizzle.config.ts"]

package/template/packages/db/drizzle/0000_init.sql

@@ -0,0 +1,53 @@
+CREATE TABLE "accounts" (
+	"id" text PRIMARY KEY NOT NULL,
+	"account_id" text NOT NULL,
+	"provider_id" text NOT NULL,
+	"user_id" text NOT NULL,
+	"access_token" text,
+	"refresh_token" text,
+	"id_token" text,
+	"access_token_expires_at" timestamp,
+	"refresh_token_expires_at" timestamp,
+	"scope" text,
+	"password" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "sessions" (
+	"id" text PRIMARY KEY NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"token" text NOT NULL,
+	"ip_address" text,
+	"user_agent" text,
+	"user_id" text NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "sessions_token_unique" UNIQUE("token")
+);
+--> statement-breakpoint
+CREATE TABLE "users" (
+	"id" text PRIMARY KEY NOT NULL,
+	"name" text NOT NULL,
+	"email" text NOT NULL,
+	"email_verified" boolean DEFAULT false NOT NULL,
+	"image" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "users_email_unique" UNIQUE("email")
+);
+--> statement-breakpoint
+CREATE TABLE "verifications" (
+	"id" text PRIMARY KEY NOT NULL,
+	"identifier" text NOT NULL,
+	"value" text NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "accounts" ADD CONSTRAINT "accounts_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "sessions" ADD CONSTRAINT "sessions_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "accounts_user_id_idx" ON "accounts" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "sessions_user_id_idx" ON "sessions" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "verifications_identifier_idx" ON "verifications" USING btree ("identifier");