Scaffold a Civitai App

Stands up a new apps/<name> on the shared @civitai/* packages, adding only the packages the app actually needs. Each app cherry-picks; there is no base bundle.

Source of truth (read these, don't restate them from memory — they may have changed):

docs/packages/new-app-integration.md — the bootstrap + data-layer procedure
docs/auth/spoke-integration-guide.md — auth depth
packages/civitai-*/README.md — per-package reference (exports, env, gotchas)
apps/moderator — the canonical worked example (SvelteKit). Mirror it.

When to use

A new monorepo app: a moderator/admin tool, a *.civitai.com spoke, an internal dashboard. Not for adding a feature to an existing app.

Workflow (interactive after gathering)

1. Gather inputs

Ask only what can't be inferred:

App name → apps/<name>, package name @civitai/<name>-app.
Framework → SvelteKit (default, adapter-node) or Next.js. Mirror apps/moderator (SvelteKit) or the old Next shape.
Packages to include (cherry-pick) — see the recipe table in §3. Infer from the app's purpose, then confirm. Default for a gated data app: @civitai/auth, @civitai/db, @civitai/db-schema, @civitai/brand.
Auth policy → the require predicate (e.g. (u) => u.isModerator === true) and what happens to an authenticated-but-unauthorized user (403, or redirect to https://civitai.com).

2. Scaffold the base (framework files)

Copy the shape of apps/moderator — read those files and adapt names. Base files (no packages yet): package.json ("type": "module", vite/svelte-kit scripts), svelte.config.js (adapter-node), vite.config.ts (process.env shim + empty ssr.noExternal to fill in §3), tsconfig.json, postcss.config.cjs (module.exports = {}), .gitignore, src/app.html, src/app.d.ts, src/global.css, src/routes/+layout.svelte, a landing +page.svelte.

Key bootstrap rules (full detail in the integration guide §3–4):

Transpile: packages ship raw TS → add every picked package to Vite ssr.noExternal (or Next transpilePackages), plus workspace peers (@civitai/db ⇒ also @civitai/db-schema).
process.env shim (Vite only): loadEnv(mode, process.cwd(), '') → process.env[k] ??= …, because the packages read process.env directly and SvelteKit doesn't populate it.

3. Add each picked package (the recipe)

For each package the user picked, apply its row: add the dep(s), add to the transpile list, add the env vars (to both .env and .env.example), and create the shim under src/lib/server/.

Package	Deps to add	Transpile list adds	Env (→ .env & .env.example)	Shim
`@civitai/auth`	`@civitai/auth`	`@civitai/auth`	`AUTH_JWT_ISSUER`, `AUTH_JWKS_URI`, `AUTH_INTERNAL_TOKEN`	`lib/server/auth.ts` (`createSpokeGuard`) + `hooks.server.ts`
`@civitai/db` (Kysely)	`@civitai/db`, `@civitai/db-schema`	both	(none — explicit conn strings) `DATABASE_URL`, `DATABASE_REPLICA_URL`	`lib/server/db.ts` (`createKyselyClients`)
`@civitai/db` (Prisma)	`@civitai/db`, `@civitai/db-schema`	both	`DATABASE_URL`, `DATABASE_REPLICA_URL`, `NOTIFICATION_DB_URL`, `NOTIFICATION_DB_REPLICA_URL`	`lib/server/db.ts` (`createPrismaClients`)
`@civitai/redis`	`@civitai/redis`	`@civitai/redis`	`REDIS_URL` and `REDIS_SYS_URL` (both!)	`lib/server/redis.ts` (`createRedisClients`)
`@civitai/clickhouse`	`@civitai/clickhouse`	`@civitai/clickhouse`	`CLICKHOUSE_HOST`, `CLICKHOUSE_USERNAME`, `CLICKHOUSE_PASSWORD`	`lib/server/clickhouse.ts` (`createClickhouseClient`)
`@civitai/email`	`@civitai/email`	`@civitai/email`	`EMAIL_HOST`, `EMAIL_PORT`, `EMAIL_USER`, `EMAIL_PASS`, `EMAIL_FROM` (all optional)	`lib/server/email.ts` (re-export `sendEmail`)
`@civitai/axiom`	`@civitai/axiom`	`@civitai/axiom`	`AXIOM_TOKEN`, `AXIOM_ORG_ID`, `AXIOM_DATASTREAM` (all optional)	`lib/server/logger.ts` (`createAxiomLogger`)
`@civitai/telemetry`	`@civitai/telemetry`	`@civitai/telemetry`	(none)	`lib/server/metrics.ts` + a `/metrics` route
`@civitai/brand`	`@civitai/brand`	`@civitai/brand`	(none)	`routes/favicon.svg/+server.ts` (`buildFaviconSvg`)
`@civitai/db-schema`	(peer of db; rarely alone)	`@civitai/db-schema`	(none)	import `DB` / enums directly

Shim snippets live in the package READMEs and the integration guide — read and adapt, don't invent.

Do not add transitive deps (pg, kysely, jose) — they resolve through the workspace packages. Add them only if the app imports them directly (e.g. import { sql } from 'kysely').

4. Critical per-package gotchas (call these out)

Redis: both URLs or neither. Setting only REDIS_URL (e.g. just for the auth session cache) without REDIS_SYS_URL makes loadRedisEnv throw — caught as fail-open, so the cache is silently lost.
db: pick the right entry. @civitai/db/kysely is env-free and Prisma-free (use for light apps); the @civitai/db Prisma entry requires the full 4-var DB env set.
db SSL: pass sslNoVerify: true to createKyselyClients for the cnpg pooler's self-signed cert.
auth needs redis only for revocation: the guard fails open to a hub fetch without redis. Only pull @civitai/redis into an auth-only app if you want real-time revocation (isRevoked) or the cache.

5. Verify (always, both commands)

pnpm install
pnpm --filter @civitai/<name>-app run typecheck
pnpm --filter @civitai/<name>-app run build

Both must pass. Then trim-check every dependency you're unsure about: remove it, reinstall, re-run typecheck and build — typecheck can pass on transitive types while runtime still needs the dep (or vice-versa). Report the final dependency list and which packages were wired.

6. Hand off

Surface: the package list chosen, env vars the user must fill in .env (real secrets come from the main app's repo-root .env), and the run command (/dev-server skill). Don't run release/install of secrets without asking.

scaffold-civitai-app