Boilerplate templates for Constructive applications.
- nextjs/constructive-app — Next.js frontend boilerplate with auth, org management, and GraphQL SDK integration
- nextjs/app — composed CRUD app template: a thin Next.js shell over shared layers, with screens generated from the database's
_meta(see below)
This template isn't copied as-is. scripts/compose.ts assembles it from framework-generic layers plus a thin framework shell, installs the UI from the blocks registry, and the generator writes the resource screens from the database's _meta. A TanStack Start shell would add tanstack/app and an emitter next to the Next.js ones; the shared layers stay as they are.
shared/
gen/ _meta + AppSpec → resource IR → files (pure TS, Node type stripping)
app-spec.schema.json AppSpec v1 (JSON Schema 2020-12)
meta-ir.ts _meta → resources: system fields, relations, enums, junctions
app-spec.ts AppSpec overlay: labels, nav, columns, dashboard
emitter.ts emitter interface + generated-file ownership
emitters/nextjs.ts resource configs, registry, routes, dashboard, app config
cli.ts gen:resources
app/ framework-agnostic app glue, copied into src/
lib/auth token storage (desktop contract), session, auth operations
lib/graphql ORM client with the session token, SDK hook configuration, fetchAll
(reads past the API's 1000-row page cap by cursor), errors (what a
failure means: unavailable database, outdated app, signed out)
lib/resources ormSource: resource-kit data source over a generated ORM model
lib/runtime endpoints from env
nextjs/app/ Next.js App Router shell + template.json
scripts/compose.ts template.json → standalone app directory
pnpm install # repository root: TypeScript for the checks below
node --experimental-strip-types scripts/compose.ts --template nextjs/app --out /tmp/app
# against a local blocks registry:
node --experimental-strip-types scripts/compose.ts --template nextjs/app --out /tmp/app \
--registry-url 'http://127.0.0.1:4005/r/{name}.json'It copies the layers (shared/app → src/, the shell → the root, shared/gen → scripts/gen/), taking only the files git tracks or would track, so ignored files such as .env.local never ship. It writes components.json, runs shadcn add for the template's blocks with a pinned CLI, puts back the template's own dependency pins, runs pnpm install, and writes .constructive/compose.json (templateSha, registryUrl, registryIndexHash, registryContentHash, blocks, composedAt).
registryContentHash covers the content of every installed registry item, including transitive dependencies, so it changes whenever kit code does. Key snapshots by it together with templateSha. The app is composed in a sibling directory and moved into place only when every step passed. Step timings go to stderr and a JSON summary to stdout. --no-install writes the lockfile without node_modules; --force replaces a non-empty output directory.
The composed app type-checks and builds with no tables and before codegen: src/graphql/sdk/{app,auth} ship as stubs that pnpm codegen replaces.
In the composed app, after codegen:
pnpm gen:resources --meta meta.json [--spec app-spec.json]It prints a JSON summary (resources: [{ name, route, table, tableName, model, nav }], files: { written, unchanged, skipped, modified, removed }, hints, junctions, skippedTables, specGaps, warnings). specGaps lists every name the AppSpec uses that _meta doesn't have ({ path, name, message }: entities, their fields and belongs-to keys, extend columns, links, and ui names), so a non-empty list means the spec and the live database disagree. Each gap is in warnings too. Every generated file starts with // @generated by gen:resources — delete this line to take ownership (body sha256:…); the generator rewrites a file only while that line is there and the body still matches its hash. A file edited below an intact header is left alone and listed under modified, and so is one whose header lost its hash, unless its body is still what the last run wrote (by the hash in .constructive/gen-state.json); then it is rewritten with the hash back on. After a change it also deletes the route types Next derived (.next/types, .next/dev/types), so a type-check never sees a removed page. nextjs/app/AGENTS.md is the guide for a coding agent working inside a composed app.
Running it again after the database changed is the follow-up path. New tables get their config, pages and sidebar entry; new columns show up in the configs that are still generated; untouched files of tables that are gone are deleted, and only those: a file the last run didn't emit, such as a copy of a generated page that kept its header, stays. .constructive/gen-state.json records the hash of every file the last run emitted and the fields of every resource, so a run can tell when a file the app owns or edited misses something new. Each such file gets one entry in hints ({ path, state: 'owned' | 'modified', message }), on the run that brings the change, e.g. src/app/(app)/page.tsx is yours; add the new resource donations to it by hand if needed. A curated-blueprint AppSpec describes its additions in backend.extend (entities, plus fields and belongsTo by existing table, and links), with the same shapes as a custom backend.
What decides a field, highest first: the AppSpec's ui.resources.<table>.fields.<field> hints (label, description, options, hidden, input, required, default, where "$currentUserId" fills the signed-in user's id on create), then _meta fields when the endpoint serves them (allowedValues, isRequiredOnCreate, isWritableOnCreate/isWritableOnUpdate, and isJunction: false, which rules a junction out), then the generator's own rules (system fields, foreign keys, enums, junctions). A junction is a table with two foreign keys to two different tables and no other field but system fields; one with a value of its own, such as a grade on an enrollment, gets its own pages even when _meta calls it a junction. An ownerId or entityId is a system field, hidden and filled with the signed-in user's id on create, when it is the scope's key column, points at the users table, or points at no table _meta shows; one that points at an app table (pets.owner_id → owners) is an ordinary belongs-to. Form help text comes only from a description hint; column comments in _meta are schema notes and never reach the UI.
The app is a static export (output: 'export', trailingSlash: true): pnpm build writes out/, the single-page app the desktop's Deploy publishes. So no generated route has a dynamic segment: a list is src/app/(app)/<resource>/page.tsx and a record is src/app/(app)/<resource>/view/page.tsx, at /<resource>/view/?id=<id>. A run over an app generated before this removes the old [id] record pages it wrote.
Generated lists and detail pages follow the write operations exposed by _meta. An append-only table offers create when its API supports it, and a table with no write operations still has a list and detail view. For row titles and relation labels, the generator prefers a name, title, or display name. If a person has separate given and family name columns, it displays them together before falling back to email. An explicit titleField in the AppSpec controls row titles. When it names one half of a person's name, related fields still display both halves.
Create forms start required, writable date and timestamp fields at the current local day or time when the database and AppSpec supply no default. The value is set when the form opens and can be edited before saving. A literal default in the AppSpec, on an entity field or as a ui hint, starts the create form on that value (createDefault: { value }), so a select whose column defaults to Medium shows Medium rather than None.
The values a column allows are the exception, because the live database enforces them. When _meta lists them (allowedValues, else enumValues), they beat an entity field's enum (the same set keeps the spec's order; a different one warns), and options hints keep only the allowed values, in the hint's order, with a warning for the rest. When the endpoint serves allowedValues and the column has none, a spec enum is ignored with a warning, while options hints still apply. An endpoint that doesn't serve allowedValues keeps the spec's values.
pnpm test # generator, ormSource, token storage and compose tests (node:test)
pnpm typecheck # generator and scripts.github/workflows/app-template.yml builds the blocks registry at a pinned blocks commit (BLOCKS_REF) and serves it locally, composes nextjs/app against it, type-checks and builds it with the stub SDK, then generates the SDK and resources from each committed fixture and type-checks again. The fixtures under shared/gen/__tests__/__fixtures__/ are real databases from the local stack (a custom food-bank app and the curated agent blueprint): _meta, an AppSpec, and the SDL of the auth and app planes, so codegen runs offline.
# 1. Start Postgres
docker compose up -d
# 2. Install dependencies
pnpm install
# 3. Setup database
eval "$(pgpm env)"
createdb myapp
pgpm admin-users bootstrap --database myapp --yes
pgpm admin-users add --database myapp --test --yes
pgpm deploy --package myapp-service --database myapp --yes
pgpm deploy --package myapp --database myapp --yes
pgpm deploy --package dev-local --database myapp --yes
pgpm deploy --package myapp-test-seed --database myapp --yes
# 4. Start GraphQL server
PGDATABASE=myapp cnc server --port 3000 --origin "*"
# 5. Codegen
pnpm run codegen
# 6. Start the app
cd nextjs/constructive-app && pnpm run devAI agents: The
src/graphql/sdk/directory innextjs/constructive-appis auto-generated by@constructive-io/graphql-codegen. Never edit it manually — fix the upstream config and re-runpnpm codegen.
In constructive-db repo:
docker-compose up -d
eval "$(pgpm env)"
createdb constructive
pgpm admin-users bootstrap --yes
pgpm admin-users add --test --yes
pgpm deploy --yes --database constructive --package constructive-localIn constructive repo:
pnpm install
PGDATABASE=constructive pnpm devIn constructive-app package:
pnpm install
eval "$(pgpm env)"
pnpm run create-db
pnpm run provision
pnpm run codegen
pnpm run seed
pnpm run dev