@nocobase/app-skills 0.1.0-beta.26 → 0.1.0-beta.28

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.
Files changed (40) hide show
  1. package/package.json +2 -2
  2. package/skills/nocobase-app-development/SKILL.md +25 -31
  3. package/skills/nocobase-app-development/references/authorization.md +1 -1
  4. package/skills/nocobase-app-development/references/cli.md +26 -27
  5. package/skills/nocobase-app-development/references/frontend/frontend-dev.md +3 -3
  6. package/skills/nocobase-app-development/references/frontend/references/api.md +1 -1
  7. package/skills/nocobase-app-development/references/frontend/references/child-routes.md +7 -8
  8. package/skills/nocobase-app-development/references/frontend/references/example/copy.md +4 -4
  9. package/skills/nocobase-app-development/references/frontend/references/example/settings-page.md +2 -2
  10. package/skills/nocobase-app-development/references/frontend/references/form.md +1 -1
  11. package/skills/nocobase-app-development/references/frontend/references/i18n.md +19 -12
  12. package/skills/nocobase-app-development/references/frontend/references/page.md +64 -126
  13. package/skills/nocobase-app-development/references/frontend/references/shadcn.md +1 -1
  14. package/skills/nocobase-app-development/references/frontend/references/shell.md +12 -14
  15. package/skills/nocobase-app-development/references/frontend/references/testing.md +1 -1
  16. package/skills/nocobase-app-development/references/frontend/references/theme.md +9 -9
  17. package/skills/nocobase-app-development/references/frontend/references/ui-library.md +1 -1
  18. package/skills/nocobase-app-development/references/frontend/scripts/capture.md +1 -1
  19. package/skills/nocobase-app-development/references/frontend/shadcn/SKILL.md +1 -1
  20. package/skills/nocobase-app-development/references/frontend/shadcn/agents/openai.yml +4 -4
  21. package/skills/nocobase-app-development/references/frontend/shadcn/cli.md +7 -7
  22. package/skills/nocobase-app-development/references/frontend/shadcn/customization.md +11 -11
  23. package/skills/nocobase-app-development/references/frontend/shadcn/rules/base-vs-radix.md +18 -14
  24. package/skills/nocobase-app-development/references/frontend/shadcn/rules/chat.md +16 -16
  25. package/skills/nocobase-app-development/references/frontend/shadcn/rules/composition.md +45 -43
  26. package/skills/nocobase-app-development/references/frontend/shadcn/rules/forms.md +38 -32
  27. package/skills/nocobase-app-development/references/frontend/shadcn/rules/icons.md +8 -8
  28. package/skills/nocobase-app-development/references/frontend/shadcn/rules/styling.md +12 -11
  29. package/skills/nocobase-app-development/references/http-api.md +11 -11
  30. package/skills/nocobase-app-development/references/lifecycle.md +428 -0
  31. package/skills/nocobase-app-development/references/migrations.md +15 -1
  32. package/skills/nocobase-app-development/references/organization/settings-page.md +6 -4
  33. package/skills/nocobase-app-development/references/organization.md +3 -3
  34. package/skills/nocobase-app-development/references/services-and-jobs.md +1 -1
  35. package/skills/nocobase-app-development/references/template-variants.md +0 -6
  36. package/skills/nocobase-app-development/references/testing.md +1 -2
  37. package/skills/nocobase-app-upgrade/SKILL.md +4 -2
  38. package/skills/nocobase-app-upgrade/references/edge-cases.md +19 -17
  39. package/skills/nocobase-app-upgrade/references/theme-upgrade.md +43 -0
  40. package/skills/nocobase-deployment/SKILL.md +17 -35
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.26",
3
+ "version": "0.1.0-beta.28",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -18,7 +18,7 @@
18
18
  "devDependencies": {
19
19
  "@playwright/test": "^1.62.1",
20
20
  "prettier": "^3.9.6",
21
- "@nocobase/dev-config": "0.1.0-beta.20"
21
+ "@nocobase/dev-config": "0.1.0-beta.21"
22
22
  },
23
23
  "peerDependencies": {
24
24
  "@playwright/test": "^1.62.1",
@@ -43,7 +43,6 @@ NocoBase packages may publish Skills under `.agents/skills/`. Current applicatio
43
43
 
44
44
  | The requirement sounds like | Read the Skill for |
45
45
  | --------------------------------------------------------- | ------------------------------------- |
46
- | Approvals, multi-step processes, "when X happens then Y" | `@nocobase/app-plugin-workflow` |
47
46
  | Email, IM, or in-app messages | `@nocobase/app-plugin-notification` |
48
47
  | Roles, permissions, per-user or per-record access | `@nocobase/app-plugin-authorization` |
49
48
  | Sign-in, registration, sessions | `@nocobase/app-plugin-authentication` |
@@ -52,11 +51,9 @@ NocoBase packages may publish Skills under `.agents/skills/`. Current applicatio
52
51
  | User administration and application-owned role assignment | `@nocobase/app-plugin-users` |
53
52
  | Reading or writing data, schema changes, migrations | `@nocobase/db` |
54
53
 
55
- The Workflow plugin is disabled by default in the official application templates. Its presence in `dependencies` or synchronized Skills does not enable it; verify registration in Client, Server, and CLI before using it.
56
-
57
54
  Read the relevant Skill before writing the feature, but treat this table as a map rather than an installed-package list. Implementing a permission system, a notification sender, or a scheduler by hand when a registered plugin provides one is the most expensive mistake available here.
58
55
 
59
- For a workflow that pauses for an external decision, use the workflow plugin's `wait` node and its App-facing Skill. Persist the `runId` alongside the application's business identity and share the wait node's stable `nodeKey` with the authorized resumer; submit a stable event id through `workflowService.getInstructionApi('wait').resume()`. Keep early events for retry when the node is not ready, and keep authentication, authorization, and business side-effect idempotency in the application.
56
+ When the stages of a business record are fixed by developers rather than drawn by administrators — an expense report, a ticket, a contract, an order — build it with `@nocobase/lifecycle` as [record lifecycles](references/lifecycle.md) describes: the state stays in the record's own field and changes only through declared transitions.
60
57
 
61
58
  For notification configuration or sending, follow the notification plugin Skill: `notification.channels` maps each name to one flat Provider configuration, and `send({ idempotencyKey, messages })` supplies a complete message per Channel. Use native addresses; email and in-app arrays create independent deliveries, while Webhooks forbid `to`.
62
59
 
@@ -74,7 +71,7 @@ The running application describes every `/api` endpoint it serves — its own ro
74
71
  curl -H "x-api-key: <key>" http://127.0.0.1:13000/main/api/swagger
75
72
  ```
76
73
 
77
- Replace `/main` with the application's `APP_BASE_PATH`. Swagger UI for people is at `<APP_BASE_PATH>/api/swagger/docs`. Reading either needs a signed-in session or an API key, which a user creates at `<APP_BASE_PATH>/settings/api-keys`; without one the routes answer `401`, and an application with no access check registered, such as one without the authentication plugin, answers `404`. Ask the user for a key rather than creating one yourself. [HTTP API design](references/http-api.md#api-documentation) explains how to read the document and how a new route declares itself in it.
74
+ Replace `/main` with the application's `APP_BASE_PATH`. Swagger UI for people is at `<APP_BASE_PATH>/api/swagger/docs`. Reading either needs a signed-in session or an API key, which a signed-in user creates with `POST <APP_BASE_PATH>/api/apiKeys`; without one the routes answer `401`, and an application with no access check registered, such as one without the authentication plugin, answers `404`. Ask the user for a key rather than creating one yourself. [HTTP API design](references/http-api.md#api-documentation) explains how to read the document and how a new route declares itself in it.
78
75
 
79
76
  ## Removing a direct NocoBase package
80
77
 
@@ -94,22 +91,23 @@ The handbook's "Look up by task" table routes each frontend task to the sections
94
91
 
95
92
  Read the page for the task in front of you. Do not read all of them.
96
93
 
97
- | Task | Read |
98
- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
99
- | Anything under `client/`: pages, routes, components, styling, forms, API calls, copy, frontend tests | [frontend workflow](references/frontend/ui-workflow.md), which routes to the [frontend handbook](references/frontend/frontend-dev.md), the theme reference or the worked example |
100
- | Add an API endpoint, a webhook, or a callback; authenticate and authorize it | [server routes](references/server-routes.md) |
101
- | Name an endpoint, shape its response or errors, validate its input, paginate a list, document it in the API document | [HTTP API design](references/http-api.md) |
102
- | Query or write data, resolve the database, work with transactions | [database and data access](references/database-and-data.md) |
103
- | Create a table, alter a column, add an index, write required initial data | [migrations and seeds](references/migrations.md) |
104
- | Switch the database, register a dialect, add a second connection | [database connections](references/database-connections.md) |
105
- | Translate server-produced text, add a language, set the default language | [internationalization](references/i18n.md) |
106
- | Departments, positions or another organisation dimension that permission sets are assigned to | [organisation dimension](references/organization.md) |
107
- | Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md) |
108
- | Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md) |
109
- | Write server and migration tests, choose a test layer, verify before finishing | [testing and verification](references/testing.md) |
110
- | Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
111
- | Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
112
- | Understand behavior inherited from an official application template | [template variants](references/template-variants.md) |
94
+ | Task | Read |
95
+ | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
96
+ | Anything under `client/`: pages, routes, components, styling, forms, API calls, copy, frontend tests | [frontend workflow](references/frontend/ui-workflow.md), which routes to the [frontend handbook](references/frontend/frontend-dev.md), the theme reference or the worked example |
97
+ | Add an API endpoint, a webhook, or a callback; authenticate and authorize it | [server routes](references/server-routes.md) |
98
+ | Name an endpoint, shape its response or errors, validate its input, paginate a list, document it in the API document | [HTTP API design](references/http-api.md) |
99
+ | Query or write data, resolve the database, work with transactions | [database and data access](references/database-and-data.md) |
100
+ | Create a table, alter a column, add an index, write required initial data | [migrations and seeds](references/migrations.md) |
101
+ | Switch the database, register a dialect, add a second connection | [database connections](references/database-connections.md) |
102
+ | Translate server-produced text, add a language, set the default language | [internationalization](references/i18n.md) |
103
+ | Departments, positions or another organisation dimension that permission sets are assigned to | [organisation dimension](references/organization.md) |
104
+ | Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md) |
105
+ | Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md) |
106
+ | A record that moves through stages defined in code: approvals, tickets, orders, timeouts, effects after a state change | [record lifecycles](references/lifecycle.md) |
107
+ | Write server and migration tests, choose a test layer, verify before finishing | [testing and verification](references/testing.md) |
108
+ | Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
109
+ | Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
110
+ | Understand behavior inherited from an official application template | [template variants](references/template-variants.md) |
113
111
 
114
112
  A feature with a page and an API usually needs migrations, server routes, and a frontend change that follows the frontend workflow.
115
113
 
@@ -141,7 +139,7 @@ Everything else — `client/routing/`, `client/layouts/`, `client/theme/`, the s
141
139
 
142
140
  When the built-in mechanism genuinely cannot express the requirement, changing that structure is a legitimate answer. Comment what you changed and why the built-in path did not fit, and update the application's `AGENTS.md` in the same change so it still describes the real application. The synchronized NocoBase Skills are package-owned; propose a change to their source package when the shared framework guidance itself is wrong.
143
141
 
144
- When you do change the shell (`client/layouts/`, `client/routing/`), keep the behaviors listed in [customizing the shell](references/frontend/references/shell.md#1-behaviors-to-keep): the Settings header entry, dev pages inside the App shell, the language submenu, navigation group state, permission refresh and sign-out handling.
142
+ When you do change the shell (`client/layouts/`, `client/routing/`), keep the behaviors listed in [customizing the shell](references/frontend/references/shell.md#1-behaviors-to-keep): a single App shell with no settings area, the language submenu, navigation group state, permission refresh and sign-out handling.
145
143
 
146
144
  ## Ownership
147
145
 
@@ -175,7 +173,7 @@ These cause real damage and appear in every reference:
175
173
 
176
174
  - **Every server route owns its own authentication and authorization.** Mounting under `/api` authenticates nothing.
177
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.
178
- - **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).
179
177
  - **Every user-visible string goes through a translation key**, the English built into shadcn/ui primitives included.
180
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).
181
179
  - **Visual consistency is application-wide.** Restyling only your part is a defect. Change the design tokens if a change is needed.
@@ -215,18 +213,14 @@ After adding or removing a language in `client/locales/` or `server/locales/`, r
215
213
 
216
214
  Application startup defaults belong in `config.yml`: `i18n.defaultLocale` for the language, and `client.app.defaultColorScheme` and `client.app.defaultTheme` for appearance. Valid browser-local choices take precedence. Which languages the interface offers is not configured — `client/locales/` is that list, while `server/locales/` independently defines the server's translated languages. See [internationalization](references/i18n.md), [frontend copy](references/frontend/references/i18n.md) and [themes and tokens](references/frontend/references/theme.md).
217
215
 
218
- ## Publish application releases
219
-
220
- Deploying to a Hub uses the `pnpm nocobase hub` commands, which the application has while it depends on `@nocobase/hub-cli`: `hub remote add` records the target App in `.nocobase/hub.json`, `hub auth login` saves its API key outside the project, and `hub deploy` builds for the Hub, uploads and deploys. Read `.agents/skills/nocobase-hub-cli/SKILL.md`, which that package ships, before running them, and the `nocobase-deployment` Skill for the rest of a production deployment.
221
-
222
- ## Logging and hosted applications
216
+ ## Logging
223
217
 
224
218
  Use the application logging service for diagnostics so entries carry application identity and follow its level and output policy. Development pretty output uses local time and displays `[appId/logger]`; file and JSON console output retain UTC timestamps and structured context. Request starts and headers, configuration diagnostics and AI resource loading stages are DEBUG; request completions and AI resource totals are INFO. Default optional `ai/skills` directories may be absent; explicitly configured missing directories still warn.
225
219
 
226
- The Hub configures hosted application output under `hub.logging.apps`; its own output uses `logging`. Deployed releases carry their own runtime and logging packages: updating the Hub cannot repair an old application formatter that prints numeric levels or omits context, or make an old runtime understand the structured console policy. Upgrade the application dependencies, rebuild and deploy a new release; never edit a deployed artifact or intercept process-wide stdout to rewrite other applications’ logs. Verify console enablement and pretty mode after upgrading.
220
+ Deployed releases carry their own runtime and logging packages: an old release keeps the formatter it was built with. Upgrade the application dependencies, rebuild and deploy a new release; never edit a deployed artifact or intercept process-wide stdout to rewrite its logs. Verify console enablement and pretty mode after upgrading.
227
221
 
228
222
  Authentication diagnostics use the application `auth` logger unless an explicit authentication logger is configured. A missing Better Auth base URL is a configuration warning, not a logging error: configure `app.publicOrigin` with the externally reachable origin in the application deployment configuration. Do not substitute the internal Host bind address or suppress the warning to make startup appear clean.
229
223
 
230
- ## Hub storage maintenance
224
+ ## Storage
231
225
 
232
- Hub storage separates Hub-owned state, Host runtime files, release archives, expanded revisions and persistent application volumes. Standalone source and compiled entries share the deployment directory's storage; `APP_STORAGE_DIR` selects another storage directory, and explicit storage paths take precedence over it. Embedded applications use Host-provided paths. Expanded releases live at `appRevisionsDir/<appId>/<sha256>` and restart recovery requires their installed metadata. Build archives use `storage/exports/dist.tar.gz`.
226
+ Standalone source and compiled entries share the deployment directory's storage; `APP_STORAGE_DIR` selects another storage directory, and explicit storage paths take precedence over it. Embedded applications use Host-provided paths. Expanded releases live at `appRevisionsDir/<appId>/<sha256>` and restart recovery requires their installed metadata. Build archives use `storage/exports/dist.tar.gz`.
@@ -22,7 +22,7 @@ Declare reusable collection permissions and business operations, defined as comp
22
22
 
23
23
  Every `server/routes/` endpoint installs authentication and authorization. A business operation checks `{ resource: { type: 'composite', id }, action }` with the request context's `authorize` once and binds each returned `conditions.database` policy through `repository.withPolicy`. Do not replace it with collection-level authorization or an in-memory filter. Use `authz.database.policyFor` for collection CRUD and `authz.database.authorizeRepository` for simple business Repository routes, mapping each method to its composite action. The authorization Skill documents these choices and their contracts.
24
24
 
25
- Declare `authz` on the first page of every path in `client/routes.ts`: `{ resource: { type: 'page', id }, action: 'access' }` for a business page, the page's `settings` item for a settings page, `'unrestricted'` for a root-only page, or `'skip'` explicitly; nothing is inferred from the route name. Nested pages inherit it; an omitted value on a first page defaults to `'unrestricted'` for protected App and settings pages and `'skip'` otherwise, with a development warning. Use `useCan({ resource, action })` for button visibility and server-computed eligibility for record-sensitive actions. Keep pending/failed checks closed and refresh after permission changes. Client visibility does not enforce the API. The authorization Skill’s `references/client-development.md` includes the component, relation controls and settings lifecycle; all required APIs are bundled in that Skill rather than external package documentation.
25
+ Declare `authz` on the first page of every path in `client/routes.ts`: `{ resource: { type: 'page', id }, action: 'access' }` for a business page, the page's `settings` item for a configuration page, `'unrestricted'` for a root-only page, or `'skip'` explicitly; nothing is inferred from the route name. Nested pages inherit it; an omitted value on a first page defaults to `'unrestricted'` for protected pages and `'skip'` otherwise, with a development warning. Use `useCan({ resource, action })` for button visibility and server-computed eligibility for record-sensitive actions. Keep pending/failed checks closed and refresh after permission changes. Client visibility does not enforce the API. The authorization Skill’s `references/client-development.md` includes the component, relation controls and settings lifecycle; all required APIs are bundled in that Skill rather than external package documentation.
26
26
 
27
27
  The permission workspace edits page grants, business actions with their data scopes, and settings items. Field and relation capabilities are code-owned. A new field or workflow must update its declaration and enforcement; it is not an administrator entering arbitrary database grants. Follow the dedicated Skill for custom record access, multi-table transactions, relation targets, protected assignments and last-administrator checks.
28
28
 
@@ -12,30 +12,29 @@ Write `pnpm nocobase`, not a bare `nocobase`: a machine may have an unrelated gl
12
12
 
13
13
  ## Find the command by task
14
14
 
15
- | Task | Command |
16
- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
17
- | Create `config.yml` for a new checkout | `pnpm nocobase config init` (`--dialect <name>` when several drivers are installed) |
18
- | Change a configuration value, or read a secret from the environment | `pnpm nocobase config set key=value`, `--from-env` for secrets |
19
- | Confirm the configuration before starting | `pnpm nocobase config check` |
20
- | See which environment variables the application reads | `pnpm nocobase config env` |
21
- | Describe every variable for a deployment (`dist/variables.json`) | `pnpm nocobase config variables`, `--out <file>` to write it |
22
- | Apply new migrations and seeds | `pnpm nocobase db apply` |
23
- | Undo or rerun the latest migration batch while its branch is open | `pnpm nocobase db rollback`, `pnpm nocobase db redo` |
24
- | Start the schema over from empty | `pnpm nocobase db reset` — destructive, see below |
25
- | Clear a checksum warning after a deliberate, schema-neutral edit | `pnpm nocobase db repair --dry-run`, then without `--dry-run` |
26
- | Release a migration lock a killed run left behind | `pnpm nocobase db unlock` |
27
- | Load sample data an installation skipped, in development | `pnpm nocobase db sample` |
28
- | Read the current data model | the files under `database/<connection>/collections/`, see below |
29
- | Find Collection metadata that disagrees with its table | `pnpm nocobase collections doctor` |
30
- | Check that client and server declare the same languages | `pnpm nocobase locales check` |
31
- | Add, remove or update a plugin | `pnpm nocobase plugin register`, `plugin unregister`, `plugin update` |
32
- | Check a plugin's registration without changing anything | `pnpm nocobase plugin inspect <name> --json` |
33
- | Remove a direct NocoBase package that is not a plugin | `pnpm nocobase package remove <package>` |
34
- | Refresh `.agents/skills/` after an install or upgrade | `pnpm nocobase skills sync` |
35
- | Build for another platform, or re-check an existing `dist/` | `pnpm build --target <platform>`; `pnpm nocobase dist retarget`, `dist check` |
36
- | Deploy to a Hub | `pnpm nocobase hub deploy`, after `hub remote add` and `hub auth login` — read its `nocobase-hub-cli` Skill |
37
- | 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 |
38
- | Pack that CLI, or the agent runner, for the application to serve | `pnpm nocobase cli build`, `pnpm nocobase cli build --runner` |
15
+ | Task | Command |
16
+ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
17
+ | Create `config.yml` for a new checkout | `pnpm nocobase config init` (`--dialect <name>` when several drivers are installed) |
18
+ | Change a configuration value, or read a secret from the environment | `pnpm nocobase config set key=value`, `--from-env` for secrets |
19
+ | Confirm the configuration before starting | `pnpm nocobase config check` |
20
+ | See which environment variables the application reads | `pnpm nocobase config env` |
21
+ | Describe every variable for a deployment (`dist/variables.json`) | `pnpm nocobase config variables`, `--out <file>` to write it |
22
+ | Apply new migrations and seeds | `pnpm nocobase db apply` |
23
+ | Undo or rerun the latest migration batch while its branch is open | `pnpm nocobase db rollback`, `pnpm nocobase db redo` |
24
+ | Start the schema over from empty | `pnpm nocobase db reset` — destructive, see below |
25
+ | Clear a checksum warning after a deliberate, schema-neutral edit | `pnpm nocobase db repair --dry-run`, then without `--dry-run` |
26
+ | Release a migration lock a killed run left behind | `pnpm nocobase db unlock` |
27
+ | Load sample data an installation skipped, in development | `pnpm nocobase db sample` |
28
+ | Read the current data model | the files under `database/<connection>/collections/`, see below |
29
+ | Find Collection metadata that disagrees with its table | `pnpm nocobase collections doctor` |
30
+ | Check that client and server declare the same languages | `pnpm nocobase locales check` |
31
+ | Add, remove or update a plugin | `pnpm nocobase plugin register`, `plugin unregister`, `plugin update` |
32
+ | Check a plugin's registration without changing anything | `pnpm nocobase plugin inspect <name> --json` |
33
+ | Remove a direct NocoBase package that is not a plugin | `pnpm nocobase package remove <package>` |
34
+ | Refresh `.agents/skills/` after an install or upgrade | `pnpm nocobase skills sync` |
35
+ | Build for another platform, or re-check an existing `dist/` | `pnpm build --target <platform>`; `pnpm nocobase dist retarget`, `dist check` |
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` |
39
38
 
40
39
  Every command listed takes `--connection <name>` or `--all` where connections apply; without either it acts on the default connection.
41
40
 
@@ -43,8 +42,8 @@ Every command listed takes `--connection <name>` or `--all` where connections ap
43
42
 
44
43
  - **`--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.
45
44
  - **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.
46
- - **Exit codes** are `0` for success, `1` for a runtime failure and `2` for invalid usage; `hub deploy` and `hub upload` add `3` for a result the Hub could not confirm. Keep a non-zero exit visible in your report; do not rerun until it passes by changing flags.
47
- - **Paths** given in a flag resolve from the current directory, as with any command line. The exception is `config init --config`, which resolves against the application root, the same way as `APP_CONFIG_FILE`. A default path a command names in its `--help`, such as the `hub deploy` archive, is inside the application.
45
+ - **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.
46
+ - **Paths** given in a flag resolve from the current directory, as with any command line. The exception is `config init --config`, which resolves against the application root, the same way as `APP_CONFIG_FILE`. A default path a command names in its `--help` is inside the application.
48
47
  - **Preview first.** `db apply`, `db rollback`, `db redo`, `db reset`, `db repair`, `plugin register`, `plugin unregister`, `plugin update`, `package remove` and `skills sync` take `--dry-run`: it changes nothing — it does not even create a SQLite file that does not exist yet — answers `status: "success-noop"`, and returns the plan in `result` — for the `db` commands `result.plan`, one entry per connection and kind with its `action` and the task names. Use it before any change whose effect you have not already confirmed with the user.
49
48
  - **Destructive commands need `--force` outside a terminal.** `db reset`, `db rollback`, `db redo` and `db repair` ask for confirmation interactively and refuse without `--force` in CI or any non-interactive shell, which is how an agent runs them: `error.code` is `FORCE_REQUIRED` (exit 2), `error.details.plan` is exactly what the command would do, and `error.suggestions` carry the `--force` and `--dry-run` forms. Do not add `--force` on your own initiative to get past that refusal: `db reset` drops every managed table. Show the user the plan, ask, and never run it against a database whose data matters. `db unlock --force` releases a lock that is still sending heartbeats, which lets a second run start beside a live one — only do it when the user confirms the other run is gone. A command that finds the lock held fails with `DATABASE_LOCKED`; `error.details` names the holder (`lockedBy`, `heartbeatAt`, whether it `expired`), and the suggestions say whether unlocking needs `--force`. Waiting and retrying is the usual answer.
50
49
  - **Do not start the application to run a command.** CLI commands work on files and the database directly; none of them needs `pnpm dev` running.
@@ -67,4 +66,4 @@ An application's own commands answer under the `app` topic, one file per command
67
66
 
68
67
  ## In a built dist/
69
68
 
70
- `pnpm build` writes `dist/cli/index.js`. A deployment runs `node dist/cli/index.js <topic> <command>` from any directory, or `pnpm nocobase <topic> <command>` inside `dist/`. Only runtime commands are registered there — `config`, `db`, `collections`, `locales`, `info`, the application's own commands and plugins' runtime commands. `dev`, `build`, `start`, `dist`, `plugin`, `package` and `skills` exist only in the source checkout, and so do the `hub` commands `@nocobase/hub-cli` contributes. See the `nocobase-deployment` Skill for production procedure.
69
+ `pnpm build` writes `dist/cli/index.js`. A deployment runs `node dist/cli/index.js <topic> <command>` from any directory, or `pnpm nocobase <topic> <command>` inside `dist/`. Only runtime commands are registered there — `config`, `db`, `collections`, `locales`, `info`, the application's own commands and plugins' runtime commands. `dev`, `build`, `start`, `dist`, `plugin`, `package` and `skills` exist only in the source checkout. See the `nocobase-deployment` Skill for production procedure.
@@ -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/`.
@@ -39,7 +39,7 @@ Conventions every page follows, each explained in its home:
39
39
  | Task | Read |
40
40
  | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41
41
  | A new page, its route and menu entry | [`page.md`](references/page.md) [§1](references/page.md#1-declare-the-route), [§2](references/page.md#2-the-page-component), [§6](references/page.md#6-menus) |
42
- | Page permissions, settings pages, the back button and breadcrumbs | [`page.md`](references/page.md) [§4](references/page.md#4-authz-page-authorization), [Settings pages](references/page.md#settings-pages), [§7](references/page.md#7-back-button-and-breadcrumbs) |
42
+ | Page permissions, settings pages, the back button and breadcrumbs | [`page.md`](references/page.md) [§4](references/page.md#4-authz-page-authorization), [Settings pages](references/page.md#5-settings-pages), [§7](references/page.md#7-back-button-and-breadcrumbs) |
43
43
  | Disabling or hiding a feature | [`page.md` §9](references/page.md#9-disable-a-feature-keep-the-page) |
44
44
  | Showing actions by permission (`useCan`) | [`page.md` §8](references/page.md#8-show-actions-by-permission-usecan) |
45
45
  | A plugin's page; customizing the shell, its header buttons | [`page.md` §10](references/page.md#10-customize-a-plugins-pages), [`shell.md`](references/shell.md) |
@@ -109,6 +109,6 @@ pnpm exec vitest run <related-test-files>
109
109
  - A changed `t()` key or route title always includes `tests/logic/app-locale-coverage.test.ts`; what it does not catch is in ["Checks" in `i18n.md`](references/i18n.md#checks).
110
110
  - Confirm that every test file you named ran: see ["Running tests" in `testing.md`](references/testing.md#running-tests).
111
111
  - When you changed server or database code as well, also run `pnpm exec tsc -p tsconfig.server.json --noEmit`.
112
- - When you changed a browser test under `tests/playwright/`, also run `pnpm exec tsc -p tsconfig.node.json --noEmit`, which covers `tests/playwright/` once Playwright is set up (a Hub application sets it up first, as [`references/testing.md`](references/testing.md) describes).
112
+ - When you changed a browser test under `tests/playwright/`, also run `pnpm exec tsc -p tsconfig.node.json --noEmit`, which covers `tests/playwright/` once Playwright is set up (an application without it sets it up first, as [`references/testing.md`](references/testing.md) describes).
113
113
 
114
114
  Passing all of these commands shows only that the code compiles and that the assertions you wrote hold; it does not mean the feature works. In your report, state what you ran, the results, and what you did not verify and why.
@@ -3,7 +3,7 @@
3
3
  Every endpoint request goes through the HTTP client the application provides:
4
4
 
5
5
  - **Do not** create your own client, do not use `fetch` or axios, do not hard-code `/api`, and do not build endpoint URLs from `location`. The client's base URL (the configuration key `api.baseURL`, by default `resolveAppUrl('/api')`) already includes the deployment base path (for example `/main`).
6
- - For a URL served by the application, such as an API download `href`, an API-backed image or a page link, use `resolveAppUrl('/api/…')` from `@nocobase/app-client`, which adds the runtime deployment base path. Keep runtime-generated resources, including workflow artifacts, on this helper.
6
+ - For a URL served by the application, such as an API download `href`, an API-backed image or a page link, use `resolveAppUrl('/api/…')` from `@nocobase/app-client`, which adds the runtime deployment base path. Keep runtime-generated resources on this helper.
7
7
  - For a static file shipped in the frontend build, use `resolveAssetUrl('/assets/logo.png')` from `@nocobase/app-client`. Paths are relative to the client output root (`dist/client/assets/logo.png` in this example), with or without a leading slash. The helper uses Vite's absolute HTTP(S) `base` when configured, and otherwise falls back to `resolveAppUrl`; existing absolute, protocol-relative, data and blob URLs are preserved. The templates set `base` from `CDN_BASE_URL` during the build, and Vite writes it into the client code as `import.meta.env.BASE_URL`. Changing CDN settings requires rebuilding and uploading the matching files. Business code should call the helper rather than read the build variable itself.
8
8
  - Import `useApiClient`, `apiClientToken`, the `ApiClient` type and `ApiClientError` from `@nocobase/app-client`. That way the application and plugins share one runtime and one error class, which is what makes `instanceof ApiClientError` reliable.
9
9
 
@@ -1,6 +1,6 @@
1
1
  # Child routes
2
2
 
3
- Child pages, page tabs and navigation groups are all declared as routes. Routes are the source of navigation in App, Settings and Dev; how child content is presented (inline, covering, dialog, drawer) is decided by page code.
3
+ Child pages, page tabs and navigation groups are all declared as routes. Routes are the source of the application's navigation; how child content is presented (inline, covering, dialog, drawer) is decided by page code.
4
4
 
5
5
  For the basic rules on route fields, `auth`, `authz`, menus, the back button and breadcrumbs, see [`page.md`](page.md). For dialogs and drawers (`RouteDialog`, `RouteDrawer`, `useRouteOverlay`, `beforeClose`), see [`overlay.md`](overlay.md).
6
6
 
@@ -67,7 +67,7 @@ For how to write `RouteDialog` and `RouteDrawer`, see [`overlay.md`](overlay.md)
67
67
 
68
68
  ### Use child routes by default
69
69
 
70
- - When building a page with tabs, each tab is a child route by default; the user does not have to ask for "routes" separately. This is the same for App, Settings and Dev pages, including plugin pages. When the user explicitly asks for a different interaction, follow the user's request.
70
+ - When building a page with tabs, each tab is a child route by default; the user does not have to ask for "routes" separately. This is the same for every page, including plugin pages. When the user explicitly asks for a different interaction, follow the user's request.
71
71
  - A tab is a view of the parent page, not a separate destination: tab routes declare no `navigation`, and no `breadcrumb` (the header's trail stops at the parent page).
72
72
  - Tab content goes in the parent route's `children`; the parent page places `<Outlet />` in its content area; switching tabs uses route navigation.
73
73
  - **Derive the selected tab from the URL**; do not keep a separate `activeTab` state. Every tab can be opened directly, survives a reload, and works with the browser's back and forward.
@@ -617,19 +617,18 @@ A page that shows a record whose detail is a page of its own — an orders list'
617
617
 
618
618
  - **Group**: only `name`, `navigation` and `children`, with no `componentLoader`. `path` is optional; when present, it becomes the prefix of the child routes' paths; when absent, the group is only a set of entries in the menu.
619
619
  - A group renders no business component (the route renderer provides its Outlet), cannot declare `authz`, and carries no page permission of its own: the first page below a group with no page above it declares its own `authz`.
620
- - Groups can contain groups. A group's `name` must be unique, like a route name; settings group names are unique across the whole settings area.
620
+ - Groups can contain groups. A group's `name` must be unique, like a route name.
621
621
  - **Clickable parent**: a page can also have `navigation` and child pages with `navigation`. In the menu it is then both a link and expandable: the link and the expand button are two separate controls. Choose how the child pages are presented according to [section 3](#3-four-ways-to-present-a-child-route).
622
622
  - Pages that should not appear in the menu, such as details and tab content, have no `navigation`. A descendant can still declare `navigation` when its ancestor does not.
623
623
  - A path with a parameter cannot have `navigation`.
624
624
  - `navigation.order` sets the order among siblings; lower numbers come first.
625
625
  - Navigation groups keep their expanded or collapsed state while the navigation tree stays mounted; opening a new page automatically expands its ancestor groups.
626
626
 
627
- ## 7. Settings pages and dev pages
627
+ ## 7. Settings pages
628
628
 
629
- - Use `defineSettingsRoutes()` and `defineDevRoutes()`; pages, groups and `children` are written the same way as in App routes. Do not write `/settings` or `/dev` in the path.
629
+ - A settings page is an ordinary App page under a navigation group of the application's own, such as Settings ([section 5 of `page.md`](page.md#5-settings-pages)); there is no `/settings` or `/dev` surface.
630
630
  - Tabs in settings pages also use child routes ([section 4](#4-page-tabs)); nested details and tabs usually have no `navigation`.
631
- - Settings pages and dev pages both require sign-in and declare `authz` on their first page, as [section 4 of `page.md`](page.md#4-authz-page-authorization) describes. A settings page checks its settings item (["Settings pages" in `page.md`](page.md#settings-pages)); its child pages and tabs inherit that check or declare another action or item of their own, never a page grant. A dev page usually writes `'skip'`.
632
- - Dev pages, and modules imported only by them, are left out of the production build.
631
+ - A settings page checks its settings item; its child pages and tabs inherit that check or declare another action or item of their own, never a page grant.
633
632
  - Navigation groups carry no page permission. Access checks in the browser do not replace server authorization.
634
633
 
635
634
  ## 8. Verify
@@ -640,7 +639,7 @@ A page that shows a record whose detail is a page of its own — an orders list'
640
639
  4. Use back and forward: the selected tab and the menu highlight match the URL.
641
640
  5. Check the menu, the copy in each language, the link and expand button of clickable parents, and navigation on narrow screens.
642
641
  6. Remove permission for the parent page: none of the child pages can load. Then remove permission for just one child page that declares `authz` explicitly.
643
- 7. Settings pages and dev pages: a settings page's menu position is as expected; a dev page opens by URL inside the App shell and does not appear in the production build.
642
+ 7. Settings pages: a settings page's menu position under its group is as expected.
644
643
  8. Covering child pages: opening one covers the parent from the top of the content area, whatever the parent's scroll position, and nothing of the parent shows below it; the back button returns to the list with exactly the search and filters it had, and nothing the child page or its tabs wrote is left in the list's URL; the covered page keeps its input and scroll position; after going back, it works normally.
645
644
  9. Pages with tabs whose header opens overlays: from a tab other than the default, open each one. Its URL is the tab's URL plus its own segment, the tab stays selected and its content mounted behind it, and closing, saving, Esc and Back all return to that tab; opening that URL directly shows the same tab behind it.
646
645
 
@@ -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
- // … existing groups
10
+ ...systemEnUS,
11
11
  navigation: {
12
- // … existing entries
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
- // … existing groups
237
+ ...systemZhCN,
238
238
  navigation: {
239
- // … existing entries
239
+ ...systemZhCN.navigation,
240
240
  projects: '项目',
241
241
  projectDashboard: '项目仪表盘',
242
242
  projectManagement: '项目管理',
@@ -2,11 +2,11 @@
2
2
 
3
3
  Part of the [projects worked example](../example.md).
4
4
 
5
- **Depends on**: [members card](members-card.md), [session alert](session-expired-alert.md), [copy](copy.md); the settings route and item in ["Settings pages" in `page.md`](../page.md#settings-pages).
5
+ **Depends on**: [members card](members-card.md), [session alert](session-expired-alert.md), [copy](copy.md); the settings route and item in ["Settings pages" in `page.md`](../page.md#5-settings-pages).
6
6
 
7
7
  **Add first**: `yes n | pnpm exec shadcn add alert card skeleton`, then format the files it creates ([how](../shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest)).
8
8
 
9
- Rules: ["Settings pages" in `page.md`](../page.md#settings-pages), and guideline T4.
9
+ Rules: ["Settings pages" in `page.md`](../page.md#5-settings-pages), and guideline T4.
10
10
 
11
11
  ```tsx
12
12
  // client/pages/settings/projects/index.tsx
@@ -377,5 +377,5 @@ export function ProjectReminderForm({
377
377
  - `PageContainer` and `PageHeader`, the form in a `max-w-2xl` column (guideline L4), fields grouped with `FieldSet`;
378
378
  - the buttons right-aligned below the form, linked with `form={formId}` when the form component renders none;
379
379
  - on success, refresh the list underneath through the outlet context's `reload()` (guideline R2; a covering page keeps the list mounted with its old rows), then `navigate(…, { replace: true })` back to the list or on to the record; Cancel navigates back with `replace` too, as closing an overlay does;
380
- - unsaved changes (T3.9): the application's router is a declarative `BrowserRouter`, so React Router's `useBlocker` is not available; the page keeps a `beforeunload` listener while the form reports `onDirtyChange(true)`, and records under "Guideline trade-offs" that in-app navigation is not guarded. When that guard matters, keep the form in a `RouteDialog`, whose `beforeClose` covers it ([section 2.5 of `overlay.md`](overlay.md#25-beforeclose-checks-before-closing)).
380
+ - unsaved changes (T3.9): the application's router is a declarative `BrowserRouter`, so React Router's `useBlocker` is not available; register a synchronous leave decision with `useNavigationGuard` from `@nocobase/app-client` (provided by `AppClientProviders`), and keep a separate `beforeunload` listener only while dirty or submitting. The host preserves the mounted page during rejected history navigation. For a form in a `RouteDialog`, its `beforeClose` covers closing the overlay ([section 2.5 of `overlay.md`](overlay.md#25-beforeclose-checks-before-closing)).
381
381
  - **Settings page**: each Card is an independent form, with its buttons at the bottom right of the Card (guidelines T4.1 and T4.2); see the members card.
@@ -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 | Purpose |
10
- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
11
- | `client/locales/en-US.ts` | English, including the sign-in pages' copy under `auth.*`; also defines the structure of the copy and exports the type `AppResource` |
12
- | `client/locales/zh-CN.ts` | Chinese; typed as `AppResource`, so its structure must match the English |
13
- | `client/locales/index.ts` | One dynamic `import()` per language, so the browser downloads only the language being shown |
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 variable, 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.
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