@nocobase/app-skills 0.1.0-beta.26 → 0.1.0-beta.27
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 +2 -2
- package/skills/nocobase-app-development/SKILL.md +24 -30
- package/skills/nocobase-app-development/references/authorization.md +1 -1
- package/skills/nocobase-app-development/references/cli.md +26 -27
- package/skills/nocobase-app-development/references/frontend/frontend-dev.md +2 -2
- package/skills/nocobase-app-development/references/frontend/references/api.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/child-routes.md +7 -8
- package/skills/nocobase-app-development/references/frontend/references/example/settings-page.md +2 -2
- package/skills/nocobase-app-development/references/frontend/references/form.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/page.md +63 -125
- package/skills/nocobase-app-development/references/frontend/references/shadcn.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/shell.md +12 -14
- package/skills/nocobase-app-development/references/frontend/references/testing.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/theme.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/ui-library.md +1 -1
- package/skills/nocobase-app-development/references/frontend/scripts/capture.md +1 -1
- package/skills/nocobase-app-development/references/frontend/shadcn/SKILL.md +1 -1
- package/skills/nocobase-app-development/references/frontend/shadcn/agents/openai.yml +4 -4
- package/skills/nocobase-app-development/references/frontend/shadcn/cli.md +7 -7
- package/skills/nocobase-app-development/references/frontend/shadcn/customization.md +11 -11
- package/skills/nocobase-app-development/references/frontend/shadcn/rules/base-vs-radix.md +18 -14
- package/skills/nocobase-app-development/references/frontend/shadcn/rules/chat.md +16 -16
- package/skills/nocobase-app-development/references/frontend/shadcn/rules/composition.md +45 -43
- package/skills/nocobase-app-development/references/frontend/shadcn/rules/forms.md +38 -32
- package/skills/nocobase-app-development/references/frontend/shadcn/rules/icons.md +8 -8
- package/skills/nocobase-app-development/references/frontend/shadcn/rules/styling.md +12 -11
- package/skills/nocobase-app-development/references/http-api.md +11 -11
- package/skills/nocobase-app-development/references/lifecycle.md +428 -0
- package/skills/nocobase-app-development/references/organization/settings-page.md +6 -4
- package/skills/nocobase-app-development/references/organization.md +3 -3
- package/skills/nocobase-app-development/references/services-and-jobs.md +1 -1
- package/skills/nocobase-app-development/references/template-variants.md +0 -6
- package/skills/nocobase-app-development/references/testing.md +1 -2
- package/skills/nocobase-app-upgrade/SKILL.md +4 -2
- package/skills/nocobase-app-upgrade/references/edge-cases.md +14 -16
- package/skills/nocobase-app-upgrade/references/theme-upgrade.md +43 -0
- 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.
|
|
3
|
+
"version": "0.1.0-beta.27",
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
|
98
|
-
|
|
|
99
|
-
| Anything under `client/`: pages, routes, components, styling, forms, API calls, copy, frontend tests
|
|
100
|
-
| Add an API endpoint, a webhook, or a callback; authenticate and authorize it
|
|
101
|
-
| Name an endpoint, shape its response or errors, validate its input, paginate a list, document it in the API document
|
|
102
|
-
| Query or write data, resolve the database, work with transactions
|
|
103
|
-
| Create a table, alter a column, add an index, write required initial data
|
|
104
|
-
| Switch the database, register a dialect, add a second connection
|
|
105
|
-
| Translate server-produced text, add a language, set the default language
|
|
106
|
-
| Departments, positions or another organisation dimension that permission sets are assigned to
|
|
107
|
-
| Design who gets what across departments, heads and cross-department work
|
|
108
|
-
| Add a reusable service, share it across routes, run background or scheduled work
|
|
109
|
-
|
|
|
110
|
-
|
|
|
111
|
-
|
|
|
112
|
-
|
|
|
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):
|
|
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
|
|
|
@@ -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
|
-
##
|
|
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
|
-
|
|
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
|
-
##
|
|
224
|
+
## Storage
|
|
231
225
|
|
|
232
|
-
|
|
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
|
|
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
|
-
|
|
|
37
|
-
|
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
@@ -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 (
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
627
|
+
## 7. Settings pages
|
|
628
628
|
|
|
629
|
-
-
|
|
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
|
-
-
|
|
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
|
|
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
|
|
package/skills/nocobase-app-development/references/frontend/references/example/settings-page.md
CHANGED
|
@@ -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;
|
|
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.
|