Kernlift

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 example reviews. 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, requires agent-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:migrations

The 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

WhatWhere
Data accesssrc/server/db/repositories/<key>.repository.ts
Business logicsrc/server/services/<key>.service.ts
Server functions, checking permissions with requireAdminPermissionsrc/server/functions/<key>.ts
Componentssrc/components/<key>/
Pagessrc/routes/{-$locale}/admin/ or src/routes/{-$locale}/app/
Plugin: manifest and contributions such as the admin.nav entrysrc/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.ts and src/i18n/locales/zh/messages.ts, with identical keys;
  • permission rows in src/server/services/super-admin-bootstrap.service.ts and the preset roles in src/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 the validate:all chain.

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": []
}
FieldRule the build enforces
filesEvery glob matches at least one file; no file is claimed by two modules. A leading ! excludes a path
fragmentsEvery listed file has an @module:<key> region; a file a module owns entirely carries no markers
migrationsThe tag exists as a .sql file and a journal entry in both dialects
packagesname@range entries that are in package.json dependencies
validators, scriptsScript names that exist in package.json
tablesExactly the tables the module's files and regions define, in both dialects. Required when the module has migrations
configKeysAdmin config keys the module's own code writes. A trailing . means every key under that prefix
skillPackagesThe 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:build

The 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-specs

registry/dist/ is build output. It is ignored by git and you do not need to keep it.

Verify the module

  • pnpm validate:registry passes: 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-boundary and pnpm validate:migrations pass.
  • pnpm typecheck, pnpm build and pnpm check report nothing new, and pnpm validate:all turns no passing check red.
  • pnpm validate:kernlift-lifecycle passes: 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