Build a module
Add a feature to the repository as a module: code, schema and migrations for both dialects, region markers, a manifest and a validator.
A module is a feature whose boundary the repository records exactly: its files, its regions in shared files, its tables and its settings. Keeping a feature of your own in a module keeps it apart from upstream code, so merges stay small, and lets pnpm validate:registry prove that the foundation still compiles without it. This guide adds one end to end. The shipped affiliate module (modules/affiliate/module.json) is a complete example to read alongside it.
If you use a coding agent, the new-module skill walks through the same steps. See Use coding-agent skills.
Before you begin
- A clone of the repository that passes
pnpm validate:registry. Record which validators pass before you start, so you can tell afterwards that you turned none red. - A kebab-case key, written
<key>below, for examplereviews. It names the manifest directory and the markers. - The tables the module owns, the pages it adds and the permission keys it needs.
- The keys of any modules it requires.
image-agent, for example, requiresagent-starter.
Add the module
Propose the change
openspec-cn new change "<key>"
openspec-cn validate "<key>"Fill in proposal.md, design.md, specs/<key>/spec.md and tasks.md under openspec/changes/<key>/ before you validate.
Add the tables and a migration for each dialect
Define the tables in both src/server/db/schema/sqlite.ts and src/server/db/schema/postgres.ts, with the same table names. Then generate one migration per dialect:
pnpm db:generate:sqlite --name my-change
pnpm db:generate:postgres --name my-change
pnpm validate:migrationsThe Postgres run needs a DATABASE_URL to be set, but does not connect to a database. Both dialects must end up with the same migration tag, such as 0018_<key>, in drizzle/migrations/sqlite and drizzle/migrations/postgres.
Write the code
| What | Where |
|---|---|
| Data access | src/server/db/repositories/<key>.repository.ts |
| Business logic | src/server/services/<key>.service.ts |
Server functions, checking permissions with requireAdminPermission | src/server/functions/<key>.ts |
| Components | src/components/<key>/ |
| Pages | src/routes/{-$locale}/admin/ or src/routes/{-$locale}/app/ |
Plugin: manifest and contributions such as the admin.nav entry | src/plugins/<key>/manifest.ts, src/plugins/<key>/plugin.ts |
All database access goes through the repository. Business code does not reference a SQL dialect. The /admin and /app layouts already guard their route trees, so a new page needs no guard of its own. What a plugin can contribute is in Plugins.
Wire it into the shared files
A module also needs a few lines in files the foundation owns:
- the plugin import and list entry in
src/plugins/installed.ts; - copy in
src/i18n/locales/en/messages.tsandsrc/i18n/locales/zh/messages.ts, with identical keys; - permission rows in
src/server/services/super-admin-bootstrap.service.tsand the preset roles insrc/server/db/repositories/users-rbac.repository.ts.
Wrap each of those slices, and the tables from step 2, in marker lines:
// @module:<key>
import { reviewsPlugin } from "./reviews/plugin";
// @end-module:<key>The comment syntax follows the file: //, /* */, <!-- -->, -- or #, and {/* @module:<key> */} between JSX elements. Regions cannot nest, and the foundation must compile with every region removed. In src/plugins/installed.ts keep the imports in sorted order, so that organising imports never moves a line out of its region.
Write the validator
Create scripts/validate/<key>.ts. Assert behaviour and wiring, not that files exist. Call the repository with fixtures whose names start with validate-, check the results, then clean the fixtures up. Then add to package.json:
- a script
"validate:<key>": "tsx scripts/validate/<key>.ts"; - a
pnpm validate:<key>segment in thevalidate:allchain.
Write the manifest
Create modules/<key>/module.json. The directory name must equal key.
{
"key": "reviews",
"kind": "module",
"version": "0.1.0",
"requires": [],
"files": [
"src/plugins/reviews/**",
"src/components/reviews/**",
"src/routes/{-$locale}/admin/reviews.tsx",
"src/server/services/reviews.service.ts",
"src/server/db/repositories/reviews.repository.ts",
"src/server/functions/reviews.ts",
"scripts/validate/reviews.ts"
],
"fragments": [
"src/plugins/installed.ts",
"src/server/db/schema/sqlite.ts",
"src/server/db/schema/postgres.ts",
"src/i18n/locales/en/messages.ts",
"src/i18n/locales/zh/messages.ts",
"src/server/services/super-admin-bootstrap.service.ts",
"src/server/db/repositories/users-rbac.repository.ts"
],
"migrations": ["0018_reviews"],
"packages": [],
"validators": ["validate:reviews"],
"i18nNamespaces": ["reviewsCopy"],
"admin": { "routes": ["/admin/reviews"], "configPages": [] },
"screenshots": [],
"docs": [],
"tables": ["reviews"],
"configKeys": [],
"skillPackages": []
}| Field | Rule the build enforces |
|---|---|
files | Every glob matches at least one file; no file is claimed by two modules. A leading ! excludes a path |
fragments | Every listed file has an @module:<key> region; a file a module owns entirely carries no markers |
migrations | The tag exists as a .sql file and a journal entry in both dialects |
packages | name@range entries that are in package.json dependencies |
validators, scripts | Script names that exist in package.json |
tables | Exactly the tables the module's files and regions define, in both dialects. Required when the module has migrations |
configKeys | Admin config keys the module's own code writes. A trailing . means every key under that prefix |
skillPackages | The Skill package ids the module's own code publishes, one per Skill directory it ships |
The remaining fields are descriptive. key equals the directory name and version is the module's own version. kind is module for a feature and template for an item that brings a runtime of its own, as agent-starter does. requires lists modules this one depends on. i18nNamespaces names the dictionary namespaces it owns, and admin, screenshots and docs record its console pages and material.
tables, configKeys and skillPackages say what data the module owns, so the build checks them against the code.
Check the manifest against the code
pnpm registry:buildThe build slices the checkout by manifest and writes registry/dist/: index.json, one <key>@<version>.json per item, and .files.<n>.json pages for large items. It prints a line per item with its file, fragment and migration counts. A manifest that breaks one of the rules above stops the build with a message naming the module and the problem.
Archive the change
openspec-cn archive "<key>" -y --skip-specsregistry/dist/ is build output. It is ignored by git and you do not need to keep it.
Verify the module
pnpm validate:registrypasses: the foundation plus every module reproduces the checkout byte for byte, and the foundation type-checks without any module.pnpm validate:<key>,pnpm validate:plugins,pnpm validate:app-i18n,pnpm validate:route-i18n,pnpm validate:auth-boundaryandpnpm validate:migrationspass.pnpm typecheck,pnpm buildandpnpm checkreport nothing new, andpnpm validate:allturns no passing check red.pnpm validate:kernlift-lifecyclepasses: it applies and removes the built items in a scratch project, including the data purge.
Troubleshooting
"has migrations but declares no tables in module.json"
List every table the module creates in tables.
"module.json tables […] differ from the sqlite tables its files define […]"
tables must match the sqliteTable(...) and pgTable(...) names inside the module's own files and marked regions. Either a table definition sits outside an @module region, or the list is out of date.
"no file matches …"
A glob in files matches nothing. Fix the path or remove the entry.
… has no @module:<key> region
A file listed in fragments carries no region for the module. Add the markers, or remove the file from fragments.
pnpm validate:registry fails to type-check the foundation
A foundation file imports something the module owns. Move that import inside an @module region, or have the foundation reach the feature through a plugin slot.
Next steps
Templates and derived products
How a module differs from a template inside the repository, what the business templates are, and how a product of your own is built on the foundation by adding one plugin.
Background jobs
How the web app runs its own periodic work once a minute on every platform, why one lock row is enough, and how /setup detects when it stopped.