@nocobase/app-skills 0.1.0-beta.27 → 0.1.0-beta.29
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/skills/nocobase-app-development/SKILL.md +1 -1
- package/skills/nocobase-app-development/references/cli.md +3 -2
- package/skills/nocobase-app-development/references/frontend/frontend-dev.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/example/copy.md +4 -4
- package/skills/nocobase-app-development/references/frontend/references/i18n.md +19 -12
- package/skills/nocobase-app-development/references/frontend/references/page.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/theme.md +8 -8
- package/skills/nocobase-app-development/references/migrations.md +15 -1
- package/skills/nocobase-app-upgrade/references/edge-cases.md +5 -1
package/package.json
CHANGED
|
@@ -173,7 +173,7 @@ These cause real damage and appear in every reference:
|
|
|
173
173
|
|
|
174
174
|
- **Every server route owns its own authentication and authorization.** Mounting under `/api` authenticates nothing.
|
|
175
175
|
- **Every `/api` route follows [HTTP API design](references/http-api.md).** camelCase paths, `{ data }` on success, `ApiError` on failure, input validated through `apiValidator()`, and a `describeRoute()` declaration for the API document. Never hand-write an error body.
|
|
176
|
-
- **A migration is immutable history and self-contained.** Never import an evolving definition into one. Never edit one whose branch is merged.
|
|
176
|
+
- **A migration is immutable history and self-contained.** Never import an evolving definition into one. Never edit one whose branch is merged, not even to reformat it: change the schema incrementally with a new migration. See [migrations change incrementally](references/migrations.md#migrations-change-incrementally).
|
|
177
177
|
- **Every user-visible string goes through a translation key**, the English built into shadcn/ui primitives included.
|
|
178
178
|
- **Let the owning page supply `PageContainer`.** One per page; inline child pages and tabs use the parent's, covering child pages add their own, overlays use their own container. See [section 2 of pages and routes](references/frontend/references/page.md#2-the-page-component).
|
|
179
179
|
- **Visual consistency is application-wide.** Restyling only your part is a defect. Change the design tokens if a change is needed.
|
|
@@ -34,12 +34,13 @@ Write `pnpm nocobase`, not a bare `nocobase`: a machine may have an unrelated gl
|
|
|
34
34
|
| Refresh `.agents/skills/` after an install or upgrade | `pnpm nocobase skills sync` |
|
|
35
35
|
| Build for another platform, or re-check an existing `dist/` | `pnpm build --target <platform>`; `pnpm nocobase dist retarget`, `dist check` |
|
|
36
36
|
| Give the application a command line of its own, for people and agents | declare `nocobase.cli` in `package.json`, then `pnpm nocobase cli link`; see below |
|
|
37
|
-
| Pack that CLI, or the agent runner, for the application to serve | `pnpm nocobase cli build`, `pnpm nocobase cli build --runner`
|
|
37
|
+
| Pack that CLI, or the agent runner, for the application to serve | `pnpm nocobase cli build`, `pnpm nocobase cli build --runner`, `--universal` |
|
|
38
38
|
|
|
39
39
|
Every command listed takes `--connection <name>` or `--all` where connections apply; without either it acts on the default connection.
|
|
40
40
|
|
|
41
41
|
## Conventions an agent relies on
|
|
42
42
|
|
|
43
|
+
- **Verify the browser-facing origin before handing over a running application.** Set `app.publicOrigin` to the protocol, host and port the user actually opens, without the application's base path. On a remote development machine, inspect its LAN address or use the established domain instead of assuming `localhost`. An explicit `APP_PUBLIC_ORIGIN` overrides the file, including values in `.env` and `.env.local`; `pnpm dev` must not supply a fallback that overrides the configured origin. Verify an authentication request with the intended browser Origin as well as the page and health endpoint: those two GET requests alone cannot reveal a rejected login origin. `403 INVALID_ORIGIN` means the access address is not trusted; correct the origin configuration rather than disabling origin checks or trusting every host.
|
|
43
44
|
- **`--json`** prints one JSON document on stdout, success or failure, the same shape for every command: `{ schemaVersion, ok, command, status, result | error, warnings }`. `status` is `success`, `success-noop` (nothing needed changing: a dry run, or a run that found nothing to do), `partial-success` or `failure`. Read `result` on success; on failure read `error.code`, `error.suggestions` — each a `message` and, where the next step is a command, a `run` with its `command` and `args`, which names `node <dist>/cli/index.js` rather than `pnpm nocobase` in a built `dist/` — and `error.details`. Read `warnings` too, and check the exit code rather than parsing text. `NOCOBASE_CONTENT_TYPE=json` turns `--json` on for every command in a session. What the application logs while a command runs, and a command's progress, go to stderr, also under `--json`. When a command fails for a reason its message does not explain, rerun it with `NOCOBASE_CLI_DEBUG=1` to print the error behind it, redacted, on stderr; do not paste that output anywhere public without reading it.
|
|
44
45
|
- **Invalid usage** — a flag or argument the command rejects, or a command that does not exist — fails with `error.code` `INVALID_USAGE`, and its suggestions name the flag or command that was probably meant. Check that suggestion against the task before running it. The message names flags, arguments and allowed values but never repeats a value that was typed, since a mistyped line can carry a secret; compare it with the line you ran.
|
|
45
46
|
- **Exit codes** are `0` for success, `1` for a runtime failure and `2` for invalid usage. Keep a non-zero exit visible in your report; do not rerun until it passes by changing flags.
|
|
@@ -58,7 +59,7 @@ An external connection's metadata — titles, descriptions and relations its sch
|
|
|
58
59
|
|
|
59
60
|
## A command line of the application's own
|
|
60
61
|
|
|
61
|
-
Besides `pnpm nocobase`, an application may give the people and agents who use it a CLI of its own, such as `acme`: `@nocobase/app-cli-client` under the application's name, which signs in to the running application and runs the business commands its API publishes (`GET /api/cli/manifest`). No template declares one. To add it, put `"nocobase": { "cli": { "bin": "<command>", "displayName": "<Name>" } }` in `package.json` (the fields are in `@nocobase/app-cli`'s README: the state directory, the environment prefix, the device sign-in client id, the Skill directories it ships to runners, …) and add `@nocobase/app-cli-client` to `devDependencies`. `pnpm nocobase cli link` makes it a command in `node_modules/.bin`; `pnpm nocobase cli build` packs it into standalone tarballs in `storage/runners/dist`, which the agents plugin serves to its install script and to runners, and `cli build --runner` packs the runner (`nocobase-runner`, from `@nocobase/agent-runner`) beside it. In production a CI job builds them and mounts them into that storage; do not commit them or bake them into an image.
|
|
62
|
+
Besides `pnpm nocobase`, an application may give the people and agents who use it a CLI of its own, such as `acme`: `@nocobase/app-cli-client` under the application's name, which signs in to the running application and runs the business commands its API publishes (`GET /api/cli/manifest`). No template declares one. To add it, put `"nocobase": { "cli": { "bin": "<command>", "displayName": "<Name>" } }` in `package.json` (the fields are in `@nocobase/app-cli`'s README: the state directory, the environment prefix, the device sign-in client id, the Skill directories it ships to runners, …) and add `@nocobase/app-cli-client` to `devDependencies`. `pnpm nocobase cli link` makes it a command in `node_modules/.bin`; `pnpm nocobase cli build` packs it into standalone tarballs that bundle Node.js, one per platform (`--targets`), in `storage/runners/dist`, which the agents plugin serves to its install script and to runners, and `cli build --runner` packs the runner (`nocobase-runner`, from `@nocobase/agent-runner`) beside it. `--universal` packs one more tarball, `<product>-v<version>-universal.tar.gz`, which carries no Node.js and runs on the machine's own Node.js 24 or newer; alone, without `--targets`, it packs only that one and downloads no Node. It is served to every platform without a tarball of its own, and the install script checks for Node.js 24 before installing it. An application can also serve no tarball at all and name the exact npm versions of its CLI package and `@nocobase/agent-runner` instead (`agents.dist.npm`), which machines install with their own Node.js 24 and npm; the agents plugin's Skill covers both. In production a CI job builds them and mounts them into that storage; do not commit them or bake them into an image.
|
|
62
63
|
|
|
63
64
|
## The application's own commands
|
|
64
65
|
|
|
@@ -16,7 +16,7 @@ All code examples use the example "projects" domain. The topic references hold t
|
|
|
16
16
|
| `client/pages/<feature>/` | Pages: `index.tsx` is the entry; child route pages go in the same folder, following their paths (a child page with child routes of its own gets a folder); the page's own components and types also go here |
|
|
17
17
|
| `client/components/` | Components shared across the whole application |
|
|
18
18
|
| `client/components/ui/` | shadcn primitives; add a missing one with the CLI ([`references/shadcn.md`](references/shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest)); never hand-write one, and change one only as that page allows |
|
|
19
|
-
| `client/locales/` | Copy: `en-US.ts`, `zh-CN.ts`
|
|
19
|
+
| `client/locales/` | Copy: `en-US.ts`, `zh-CN.ts`, each spreading the template's own copy from `system/`, which a template upgrade replaces |
|
|
20
20
|
| `tests/` | Tests; never beside the source |
|
|
21
21
|
|
|
22
22
|
Where shared logic goes: write it in the component first. When the same logic would be copied unchanged into a second place, move it into one hook: inside one feature, a file in the feature folder (`client/pages/projects/use-project.ts`); across features, `client/hooks/` (`use-url-search.ts`). Loaders that react differently to their result, such as the detail drawer refreshing the list on a 404 while the edit dialog notifies the drawer, stay in their components, as the worked example's do. Components follow the same rule and move to `client/components/`.
|
|
@@ -7,9 +7,9 @@ Rules: [`i18n.md`](../i18n.md). Every key the handbook's examples pass to `t()`
|
|
|
7
7
|
```ts
|
|
8
8
|
// client/locales/en-US.ts (the groups the handbook's examples add; merge them into the existing file)
|
|
9
9
|
const enUS = {
|
|
10
|
-
|
|
10
|
+
...systemEnUS,
|
|
11
11
|
navigation: {
|
|
12
|
-
|
|
12
|
+
...systemEnUS.navigation,
|
|
13
13
|
projects: 'Projects',
|
|
14
14
|
projectDashboard: 'Project dashboard',
|
|
15
15
|
projectManagement: 'Project management',
|
|
@@ -234,9 +234,9 @@ const enUS = {
|
|
|
234
234
|
```ts
|
|
235
235
|
// client/locales/zh-CN.ts (the same groups; the AppResource type checks the structure)
|
|
236
236
|
const zhCN: AppResource = {
|
|
237
|
-
|
|
237
|
+
...systemZhCN,
|
|
238
238
|
navigation: {
|
|
239
|
-
|
|
239
|
+
...systemZhCN.navigation,
|
|
240
240
|
projects: '项目',
|
|
241
241
|
projectDashboard: '项目仪表盘',
|
|
242
242
|
projectManagement: '项目管理',
|
|
@@ -6,14 +6,18 @@ For the wording itself (which verb a button uses, how to write empty states and
|
|
|
6
6
|
|
|
7
7
|
## Where copy lives
|
|
8
8
|
|
|
9
|
-
| File
|
|
10
|
-
|
|
|
11
|
-
| `client/locales/en-US.ts` | English
|
|
12
|
-
| `client/locales/zh-CN.ts` | Chinese; typed as `
|
|
13
|
-
| `client/locales/
|
|
9
|
+
| File | Purpose |
|
|
10
|
+
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| `client/locales/system/en-US.ts` | The template's own English copy: the shell, the sign-in pages under `auth.*`, shared components and the homepage. Exports the type `SystemResource` |
|
|
12
|
+
| `client/locales/system/zh-CN.ts` | The template's own Chinese copy; typed as `SystemResource` |
|
|
13
|
+
| `client/locales/en-US.ts` | English: spreads `system/en-US.ts`, then adds the application's own groups; defines the structure of all the copy and exports the type `AppResource` |
|
|
14
|
+
| `client/locales/zh-CN.ts` | Chinese: spreads `system/zh-CN.ts`, then adds the same groups; typed as `AppResource`, so its structure must match the English |
|
|
15
|
+
| `client/locales/index.ts` | One dynamic `import()` per language, so the browser downloads only the language being shown |
|
|
14
16
|
|
|
15
17
|
Rules:
|
|
16
18
|
|
|
19
|
+
- Write the application's copy in `client/locales/en-US.ts` and `zh-CN.ts`, never in `client/locales/system/`. The system files belong to the template, and a template upgrade replaces them; keeping the two apart is what lets it do so without touching the application's copy.
|
|
20
|
+
- A group the application writes replaces the system group of the same name rather than merging with it. To add a key to a shared group such as `navigation` or `appearance`, spread the system group first: `navigation: { ...systemEnUS.navigation, projects: 'Projects' }`, and the same with `systemZhCN` in `zh-CN.ts`. Rewording a system key works the same way: write the key after the spread.
|
|
17
21
|
- Each new feature gets its own group (`projects: { … }`), which holds all of the feature's copy.
|
|
18
22
|
- Add menu titles to the existing `navigation` group (`navigation.projects`), and write `navigation: { title: 'navigation.projects' }` in the route (see [`page.md`](page.md)).
|
|
19
23
|
- Add the key to `en-US.ts` first, then add the same key to `zh-CN.ts`. A key missing from `zh-CN.ts` or extra in it (including a misspelled one) fails type checking.
|
|
@@ -30,7 +34,7 @@ Rules:
|
|
|
30
34
|
|
|
31
35
|
In the file, `status.*` are flat dotted keys (`'status.loading': 'Loading'`); you call them the same way as nested keys.
|
|
32
36
|
|
|
33
|
-
The handbook's examples also use five shared keys the template does not have. Before using one, search `en-US.ts`; if it is missing, add it to both locale files (the `actions` keys to the nested `actions` group, the `status` key as a flat key beside the other `status.*` keys), or the screen shows the key name:
|
|
37
|
+
The handbook's examples also use five shared keys the template does not have. Before using one, search `en-US.ts` and `system/en-US.ts`; if it is missing, add it to both locale files (the `actions` keys to the nested `actions` group, the `status` key as a flat key beside the other `status.*` keys), or the screen shows the key name:
|
|
34
38
|
|
|
35
39
|
| Key | English | Chinese | Used by |
|
|
36
40
|
| ---------------------------------------------------------------- | -------------------------------------------------- | ------------------------------ | ---------------------------------------- |
|
|
@@ -47,7 +51,7 @@ The groups `actions`, `status`, `navigation`, `dataTable` and `datePicker` are u
|
|
|
47
51
|
|
|
48
52
|
Text with an object ("New project", 'Delete project "{{name}}"?'), success messages and error copy always go in the feature group (`projects.create.action`, `projects.error.notFound`).
|
|
49
53
|
|
|
50
|
-
Before adding a key, search `en-US.ts`; if a key with the same meaning already exists, reuse it. Do not change the wording of an existing shared key for one feature: that changes every place that uses it. If you need different wording, add a new key in the feature group.
|
|
54
|
+
Before adding a key, search `en-US.ts` and `system/en-US.ts`; if a key with the same meaning already exists, reuse it. Do not change the wording of an existing shared key for one feature: that changes every place that uses it. If you need different wording, add a new key in the feature group.
|
|
51
55
|
|
|
52
56
|
## Example: the projects group (excerpt)
|
|
53
57
|
|
|
@@ -57,10 +61,12 @@ The shape of a feature group in both locale files. The complete group every exam
|
|
|
57
61
|
// client/locales/en-US.ts (excerpt)
|
|
58
62
|
import type { LocaleResource } from '@nocobase/i18n';
|
|
59
63
|
|
|
64
|
+
import systemEnUS from './system/en-US.js';
|
|
65
|
+
|
|
60
66
|
const enUS = {
|
|
61
|
-
|
|
67
|
+
...systemEnUS,
|
|
62
68
|
navigation: {
|
|
63
|
-
|
|
69
|
+
...systemEnUS.navigation,
|
|
64
70
|
projects: 'Projects',
|
|
65
71
|
},
|
|
66
72
|
projects: {
|
|
@@ -92,11 +98,12 @@ export default enUS;
|
|
|
92
98
|
```ts
|
|
93
99
|
// client/locales/zh-CN.ts (excerpt)
|
|
94
100
|
import type { AppResource } from './en-US.js';
|
|
101
|
+
import systemZhCN from './system/zh-CN.js';
|
|
95
102
|
|
|
96
103
|
const zhCN: AppResource = {
|
|
97
|
-
|
|
104
|
+
...systemZhCN,
|
|
98
105
|
navigation: {
|
|
99
|
-
|
|
106
|
+
...systemZhCN.navigation,
|
|
100
107
|
projects: '项目',
|
|
101
108
|
},
|
|
102
109
|
projects: {
|
|
@@ -338,7 +345,7 @@ Which languages the application offers, how the default language is chosen (`i18
|
|
|
338
345
|
|
|
339
346
|
To add a language (Japanese as the example):
|
|
340
347
|
|
|
341
|
-
1. Copy `client/locales/zh-CN.ts` to `ja-JP.ts`, rename the
|
|
348
|
+
1. Copy `client/locales/system/zh-CN.ts` to `system/ja-JP.ts` and `client/locales/zh-CN.ts` to `ja-JP.ts`, rename the variables, point the new file's spread at `./system/ja-JP.js`, and translate every value. Keep the `AppResource` type, so an untranslated key is reported as an error. If you really need to translate in batches, you can type it as `PartialLocaleResource<typeof enUS>` for now (import `PartialLocaleResource` from `@nocobase/i18n`, and `enUS` with `import type enUS from './en-US.js'`); missing keys fall back at runtime.
|
|
342
349
|
2. Add a loader entry to `client/locales/index.ts`:
|
|
343
350
|
|
|
344
351
|
```ts
|
|
@@ -268,7 +268,7 @@ Write `navigation` on the route. The application sidebar reads its menu entries
|
|
|
268
268
|
| `icon` | Optional. An icon component that accepts `className`; use `lucide-react` icons directly. Give the entries of one group icons together or not at all — the collapsed icon-mode sidebar shows the label of an entry that has no icon, so a mixed group reads as inconsistent — and do not repeat a group's own icon on its first child |
|
|
269
269
|
| `order` | Optional. Lower numbers come first among siblings; defaults to 0. Equal values keep registration order |
|
|
270
270
|
|
|
271
|
-
- Add the translations to the
|
|
271
|
+
- Add the translations to the `navigation` group in `client/locales/en-US.ts` and `zh-CN.ts`, after spreading the system group, for example `navigation: { ...systemEnUS.navigation, projects: 'Projects' }` and `navigation: { ...systemZhCN.navigation, projects: '项目' }` ([`i18n.md`](i18n.md)).
|
|
272
272
|
- Pages that should not appear in the menu (details, tab content and so on) have no `navigation`. When such a page is open, the menu highlights the nearest ancestor that has a menu entry.
|
|
273
273
|
- **A path with a parameter (`:projectId`) cannot have `navigation`**; registration raises an error, because a menu entry must point to a fixed URL (wildcards are rejected on every route, [section 1](#1-declare-the-route)).
|
|
274
274
|
- Navigation group: write only `name`, `navigation` and `children`, without `componentLoader`. For groups and clickable parents, see [`child-routes.md`](child-routes.md).
|
|
@@ -340,15 +340,15 @@ The steps below add a preset with the id `forest`.
|
|
|
340
340
|
|
|
341
341
|
`ThemePresetId` is derived from the array, so the new id is accepted wherever a preset id is typed. `defaultThemePreset` does not decide the fallback, and no template code reads it; keep it equal to the first entry.
|
|
342
342
|
|
|
343
|
-
5. **Add the label** to `appearance.themes` in every locale file. `zh-CN.ts` is typed from `en-US.ts`, so the two must have the same keys or the type check fails; a label missing from both fails `tests/logic/app-locale-coverage.test.ts`, which reads the registry's `labelKey` (without the label the popover would show the capitalized id). Give each preset a distinct label: it is the accessible name of the preset's radio option. Translation rules are in [`i18n.md`](i18n.md).
|
|
343
|
+
5. **Add the label** to `appearance.themes` in every application locale file, spreading the system group as [`i18n.md`](i18n.md) describes; removing or renaming a template preset rewords its key after the spread rather than editing `client/locales/system/`. `zh-CN.ts` is typed from `en-US.ts`, so the two must have the same keys or the type check fails; a label missing from both fails `tests/logic/app-locale-coverage.test.ts`, which reads the registry's `labelKey` (without the label the popover would show the capitalized id). Give each preset a distinct label: it is the accessible name of the preset's radio option. Translation rules are in [`i18n.md`](i18n.md).
|
|
344
344
|
|
|
345
345
|
```ts
|
|
346
346
|
// client/locales/en-US.ts
|
|
347
|
-
const
|
|
348
|
-
|
|
347
|
+
const enUS = {
|
|
348
|
+
...systemEnUS,
|
|
349
349
|
appearance: {
|
|
350
|
-
|
|
351
|
-
themes: {
|
|
350
|
+
...systemEnUS.appearance,
|
|
351
|
+
themes: { ...systemEnUS.appearance.themes, forest: 'Forest' },
|
|
352
352
|
},
|
|
353
353
|
// …
|
|
354
354
|
};
|
|
@@ -357,10 +357,10 @@ The steps below add a preset with the id `forest`.
|
|
|
357
357
|
```ts
|
|
358
358
|
// client/locales/zh-CN.ts
|
|
359
359
|
const zhCN: AppResource = {
|
|
360
|
-
|
|
360
|
+
...systemZhCN,
|
|
361
361
|
appearance: {
|
|
362
|
-
|
|
363
|
-
themes: {
|
|
362
|
+
...systemZhCN.appearance,
|
|
363
|
+
themes: { ...systemZhCN.appearance.themes, forest: '森林' },
|
|
364
364
|
},
|
|
365
365
|
// …
|
|
366
366
|
};
|
|
@@ -51,7 +51,7 @@ While the branch is unmerged, re-run it:
|
|
|
51
51
|
pnpm nocobase db redo
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
-
Once the branch is merged, do not edit it at all: write a new migration for the correction.
|
|
54
|
+
Once the branch is merged, do not edit it at all: write a new migration for the correction, as the next section describes.
|
|
55
55
|
|
|
56
56
|
Two things are never the answer here. `pnpm nocobase db repair` only rewrites the recorded checksum, so it makes an un-applied change look applied — the schema stays wrong and nothing says so. Editing `__nocobase_migrations`, `__nocobase_collection_metadata` or a physical table by hand splits the two records of what exists: dropping a table without its metadata record leaves the Collection unresolvable, and the next run fails with `Metadata Collection "…" maps to missing physical table "…"` before it reaches your migration.
|
|
57
57
|
|
|
@@ -66,6 +66,20 @@ Each internal table has a command that maintains it, and none of them should be
|
|
|
66
66
|
| `__nocobase_collection_metadata` | The Collection metadata behind each table | Migrations, through `builder`; `collections doctor` |
|
|
67
67
|
| `__nocobase_migration_lock`, `__nocobase_seed_lock` | The run in progress | The run itself, and `db unlock` |
|
|
68
68
|
|
|
69
|
+
## Migrations change incrementally
|
|
70
|
+
|
|
71
|
+
A migration that has been merged is history. Every installation that already ran it recorded it as executed and will never run it again, so editing it splits installations in two: those that ran the old version keep the schema it produced, and fresh ones get the schema the new version produces. Nothing reconciles the two, and the only symptom is a checksum warning that `pnpm nocobase db repair` silences without changing the schema.
|
|
72
|
+
|
|
73
|
+
So every schema change after a merge is a new migration, including a fix to a migration that turned out wrong:
|
|
74
|
+
|
|
75
|
+
- Leave the merged file untouched: not its operations, its `down`, its name, its filename, its formatting or its comments. Even a reformat changes the checksum every installation recorded and warns each of them.
|
|
76
|
+
- Name the new migration so it sorts after the one it corrects. Migrations run in name order across the application and every plugin.
|
|
77
|
+
- Write it to take an installation from what the earlier migrations left behind to the target, so it holds both on an installation that ran the earlier migrations long ago and on a fresh one that runs everything in order.
|
|
78
|
+
- Spell out the change explicitly with `builder.alterCollection`, field, index or constraint operations, and move existing rows with set-based `query` statements where the change needs it.
|
|
79
|
+
- Test the upgrade path with `describeMigration()`: it applies the earlier migrations first, then this one.
|
|
80
|
+
|
|
81
|
+
Check `git log -- <file>` when unsure whether a migration is merged. The same rule holds for migrations a plugin ships: a released plugin's migrations reach every application that installs it, so a plugin corrects one the same way.
|
|
82
|
+
|
|
69
83
|
## When a run is killed while it holds the lock
|
|
70
84
|
|
|
71
85
|
Migrations and seeds each run inside a lock, so two runs cannot apply the same history at once. A run holds its lock only while it keeps a heartbeat current: if it is killed — SIGKILL, a stopped container, a lost machine — the row stays behind but stops being refreshed, and the next run takes it over after 30 seconds and continues. Nothing has to be cleaned up by hand, and the takeover is logged, because it means a previous run did not shut down cleanly.
|
|
@@ -135,6 +135,10 @@ An application without an external connection only needs step 4.
|
|
|
135
135
|
|
|
136
136
|
A release whose Default or Examples template has `testDir: './tests/playwright'` in `playwright.config.ts` keeps Playwright tests in `tests/playwright/`; earlier releases kept them in `e2e/`. Move the application's own files from `e2e/` to `tests/playwright/` with `git mv`, then take the template's `playwright.config.ts`, add `exclude: ['tests/playwright/**']` to the `test` section of `vitest.config.ts` so Vitest does not run them, and replace `e2e/**/*.ts` with `tests/playwright/**/*.ts` in `tsconfig.node.json`. Update any `globalSetup` path or script that names `e2e/`. Earlier templates shipped no tests in `e2e/`, so everything there belongs to the application. Run `pnpm exec vitest run` and `pnpm test:e2e` afterward to confirm each runner picks up only its own files.
|
|
137
137
|
|
|
138
|
+
### The template's copy moved to `client/locales/system/`
|
|
139
|
+
|
|
140
|
+
A release whose template has `client/locales/system/en-US.ts` keeps the template's own copy there — the shell, the sign-in pages, shared components and the homepage — and `client/locales/en-US.ts` and `zh-CN.ts` spread it before the application's own groups. Earlier releases kept everything in one file per language. Take the template's `client/locales/system/` as it is, then reduce each application locale file to `...systemEnUS` (or `...systemZhCN`) followed by the groups the application added itself: compare each group with the template's previous locale file, drop the ones the application never changed, and keep a reworded template key after the spread. A shared group the application extended, such as `navigation`, becomes `navigation: { ...systemEnUS.navigation, <the application's entries> }`. Run `pnpm exec tsc -p tsconfig.json --noEmit` and `tests/logic/app-locale-coverage.test.ts` afterward. From then on, an upgrade replaces `client/locales/system/` and leaves the application's locale files alone.
|
|
141
|
+
|
|
138
142
|
## Where the user's code lives
|
|
139
143
|
|
|
140
144
|
```text
|
|
@@ -143,7 +147,7 @@ Rarely touched by the template — a change landing here deserves a careful read
|
|
|
143
147
|
server/routes/ server/providers/ database/ cli/commands/ tests/
|
|
144
148
|
|
|
145
149
|
Template structure — where most of the delta lands
|
|
146
|
-
client/routing/ client/layouts/ client/theme/
|
|
150
|
+
client/routing/ client/layouts/ client/theme/ client/locales/system/
|
|
147
151
|
client/app.ts client/runtime.ts client/startup.tsx server/*.ts
|
|
148
152
|
vite.config.ts vitest.config.ts eslint.config.js
|
|
149
153
|
tsconfig*.json index.html components.json
|