@nocobase/app-skills 0.1.0-beta.33 → 0.1.0-beta.35
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/skills/nocobase-app-development/SKILL.md +15 -39
- package/skills/nocobase-app-development/references/app-structure.md +56 -0
- package/skills/nocobase-app-development/references/cli.md +1 -1
- package/skills/nocobase-app-development/references/commands.md +2 -2
- package/skills/nocobase-app-development/references/dependencies.md +50 -0
- package/skills/nocobase-app-development/references/dev-server.md +45 -0
- package/skills/nocobase-app-development/references/frontend/references/child-routes.md +2 -1
- package/skills/nocobase-app-development/references/frontend/references/page.md +18 -0
- package/skills/nocobase-app-development/references/frontend/references/shadcn.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/shell.md +4 -4
- package/skills/nocobase-app-development/references/frontend/references/styling.md +4 -0
- package/skills/nocobase-app-development/references/frontend/references/theme.md +41 -35
- package/skills/nocobase-app-development/references/frontend/references/ui-library.md +19 -7
- package/skills/nocobase-app-development/references/frontend/ui-guidelines.md +8 -1
- package/skills/nocobase-app-development/references/lifecycle-parameters.md +95 -0
- package/skills/nocobase-app-development/references/lifecycle.md +21 -0
- package/skills/nocobase-app-development/references/plugins.md +50 -0
- package/skills/nocobase-app-development/references/services-and-jobs.md +1 -1
- package/skills/nocobase-app-upgrade/references/edge-cases.md +8 -3
- package/skills/nocobase-app-upgrade/references/theme-upgrade.md +1 -0
- package/skills/nocobase-deployment/SKILL.md +2 -2
package/package.json
CHANGED
|
@@ -19,7 +19,7 @@ Do not use it to upgrade the template this application was generated from, which
|
|
|
19
19
|
|
|
20
20
|
## Before you start
|
|
21
21
|
|
|
22
|
-
Read the application's `AGENTS.md` first for the rules that apply everywhere. This Skill's references are the detail behind it. Before running any `pnpm nocobase` command, read [the command line](references/cli.md): it maps tasks to commands and states the flags an agent must not add on its own.
|
|
22
|
+
Read the application's `AGENTS.md` first for the rules that apply everywhere, and the `.agents/rules/` files its index points to for your task. This Skill's references are the detail behind it. Before running any `pnpm nocobase` command, read [the command line](references/cli.md): it maps tasks to commands and states the flags an agent must not add on its own.
|
|
23
23
|
|
|
24
24
|
Confirm you are in an application and not a plugin package. An application has:
|
|
25
25
|
|
|
@@ -57,11 +57,7 @@ When the stages of a business record are fixed by developers rather than drawn b
|
|
|
57
57
|
|
|
58
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`.
|
|
59
59
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
Install plugins with `pnpm nocobase plugin register <name>`. All application plugins belong in `dependencies`, including client-only and disabled plugins, because deployment dependencies come from that field. Plugin frontend libraries remain peers and are not automatically installed in the deployment. Re-registering migrates legacy `devDependencies` entries while preserving the declared range; verify the manifest and lockfile afterward. With an older CLI, use `pnpm add --save-prod <package>@<declared-range>` to correct the declaration; `--no-install` leaves lockfile synchronization to the caller.
|
|
63
|
-
|
|
64
|
-
To update a registered plugin, use `pnpm nocobase plugin update @nocobase/app-plugin-authentication` (or the short name `authentication`). Omit the name to update all registered plugins; add `--dry-run` to preview. `plugin update` takes a positional name, not `--plugin`, and re-synchronizes Skills after a successful package update. See the Plugins section of the application's `README.MD` for version-range behavior and examples.
|
|
60
|
+
Install, update and customize plugins, and remove a direct NocoBase package, as [plugins](references/plugins.md) describes: `pnpm nocobase plugin register`, `plugin update` and `package remove` keep the manifest, the lockfile, the composition roots and the synchronized Skills consistent, so never hand-edit only one of them.
|
|
65
61
|
|
|
66
62
|
## Learn the endpoints from the API document
|
|
67
63
|
|
|
@@ -73,14 +69,6 @@ curl -H "x-api-key: <key>" http://127.0.0.1:13000/main/api/swagger
|
|
|
73
69
|
|
|
74
70
|
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.
|
|
75
71
|
|
|
76
|
-
## Removing a direct NocoBase package
|
|
77
|
-
|
|
78
|
-
Before removing an `@nocobase/*` dependency, search the application's imports, Client/Server/CLI plugin registrations, routes, services, configuration, tests, and build scripts for the package name and the contracts it provides. Migrate or remove those references first. `package remove` updates dependency metadata and generated Skills; it does not rewrite application code or configuration and cannot decide whether the capability is still needed.
|
|
79
|
-
|
|
80
|
-
Run `pnpm nocobase package remove @nocobase/example`. The command uses the application's package manager to update `package.json` and the lockfile, then removes only synchronized Skills recorded as owned by that package. An `@nocobase/app-plugin-*` target delegates to the plugin unregister workflow so its Client, Server, and CLI registrations are removed together; `pnpm nocobase plugin unregister <name>` remains available. Use `--dry-run` before a consequential removal and `--json` when structured output is needed.
|
|
81
|
-
|
|
82
|
-
After an interrupted or manual removal, verify that the manifest no longer declares the package and run a full `pnpm nocobase skills sync` to reconcile stale package-owned output. Passing an already-absent package to `package remove` cleans recorded historical Skill ownership without uninstalling or cleaning another package.
|
|
83
|
-
|
|
84
72
|
## Frontend work
|
|
85
73
|
|
|
86
74
|
Before writing or changing anything under `client/` — pages, components, styles, copy — read [the frontend workflow](references/frontend/ui-workflow.md). It decides whether the change takes the full workflow (a design file reviewed once, then an independent acceptance review), a theme change (tokens and presets, verified with the theme tests and a browser check) or a quick change (edit directly, then the static checks, the related tests and one look at the changed element in the browser), and which parts of [the UI guidelines](references/frontend/ui-guidelines.md) and [the frontend handbook](references/frontend/frontend-dev.md) to read at each step.
|
|
@@ -104,10 +92,15 @@ Read the page for the task in front of you. Do not read all of them.
|
|
|
104
92
|
| Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md) |
|
|
105
93
|
| Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md) |
|
|
106
94
|
| A record that moves through stages defined in code: approvals, tickets, orders, timeouts, effects after a state change | [record lifecycles](references/lifecycle.md) |
|
|
95
|
+
| Administrator-adjustable approval departments, reviewers, thresholds or business values in a code-defined lifecycle | [configurable lifecycle parameters](references/lifecycle-parameters.md); keep workflow structure in source. When building process pages with node-related parameters, prefer an editing dialog opened from the corresponding diagram node or transition. |
|
|
107
96
|
| Flowcharts, process diagrams or lifecycle state diagrams | Use UI Library `@nocobase/flow-diagram` for generic graphs and `@nocobase/lifecycle-diagram` for lifecycle descriptions; see [diagram guidance](references/lifecycle.md#draw-an-interactive-lifecycle-diagram) and the [UI catalog](references/frontend/references/ui-library.md#diagrams). Preserve their application theme tokens. |
|
|
108
97
|
| Write server and migration tests, choose a test layer, verify before finishing | [testing and verification](references/testing.md) |
|
|
109
98
|
| Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
|
|
110
99
|
| Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
|
|
100
|
+
| Where a file goes, how the client and server are composed, configuration, changing the framework structure | [application structure](references/app-structure.md) |
|
|
101
|
+
| Register, update, customize or remove a plugin; check what an installed plugin already provides | [plugins](references/plugins.md) |
|
|
102
|
+
| Add an npm package, decide `dependencies` versus `devDependencies`, diagnose a missing module or native binary | [adding a dependency](references/dependencies.md) |
|
|
103
|
+
| Report the application's URL, dev server restarts and file watching, develop against another backend | [the development server](references/dev-server.md) |
|
|
111
104
|
| Understand behavior inherited from an official application template | [template variants](references/template-variants.md) |
|
|
112
105
|
|
|
113
106
|
A feature with a page and an API usually needs migrations, server routes, and a frontend change that follows the frontend workflow.
|
|
@@ -136,9 +129,9 @@ client/locales/, client/service-provider.ts, server/routes/,
|
|
|
136
129
|
server/providers/, database/main/migrations/, database/main/seeds/, tests/
|
|
137
130
|
```
|
|
138
131
|
|
|
139
|
-
Everything else — `client/routing/`, `client/layouts/`, `client/theme/`, the server entry points, the build scripts, the tsconfigs — is the framework structure the template provides and evolves. Prefer the mechanism the system already offers: most work that looks like it needs a change there does not.
|
|
132
|
+
Everything else — `client/routing/`, `client/layouts/`, `client/theme/`, the server entry points, the build scripts, the tsconfigs — is the framework structure the template provides and evolves. Prefer the mechanism the system already offers: most work that looks like it needs a change there does not. [Application structure](references/app-structure.md) maps every directory and the composition files.
|
|
140
133
|
|
|
141
|
-
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
|
|
134
|
+
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 in the same change record the application-specific guidance in the matching `.agents/rules/<topic>.md`, adding its entry to the `AGENTS.md` index, so the guidance still describes the real application. Do not write the detail into `AGENTS.md` itself: it is a small always-on index of at most 32 KB that every agent loads on every start. The synchronized NocoBase Skills are package-owned; propose a change to their source package when the shared framework guidance itself is wrong.
|
|
142
135
|
|
|
143
136
|
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.
|
|
144
137
|
|
|
@@ -156,6 +149,9 @@ Generated .agents/skills/ — synchronized copies, gitignored, replaced
|
|
|
156
149
|
.claude/skills/ — symbolic links to the above so Claude Code
|
|
157
150
|
discovers them; gitignored, rewritten by the same sync
|
|
158
151
|
|
|
152
|
+
Rules .agents/rules/ — application-specific guidance, committed and
|
|
153
|
+
application-owned; AGENTS.md indexes it
|
|
154
|
+
|
|
159
155
|
Config config.yml — written by pnpm nocobase config init, gitignored, holds
|
|
160
156
|
secrets; document options in config.example.yml instead
|
|
161
157
|
```
|
|
@@ -180,33 +176,13 @@ These cause real damage and appear in every reference:
|
|
|
180
176
|
- **Visual consistency is application-wide.** Restyling only your part is a defect. Change the design tokens if a change is needed.
|
|
181
177
|
- **Route paths never include the deployment base path.** The runtime restores it.
|
|
182
178
|
- **Route navigation creates sidebar entries.** Declare `navigation` in `client/routes.ts`. Refine resources create no menu entries and, with no data provider registered, load nothing; pages load data with `useApiClient` (see [calling the API](references/frontend/references/api.md)).
|
|
183
|
-
- **Reach for the built-in mechanism first.** Changing framework structure is allowed when nothing else fits — comment it and
|
|
179
|
+
- **Reach for the built-in mechanism first.** Changing framework structure is allowed when nothing else fits — comment it and record it in `.agents/rules/`.
|
|
184
180
|
- **Tests live in `tests/`,** never beside the source; browser tests against a running application go in `tests/playwright/`.
|
|
185
181
|
- **Remove direct NocoBase packages with `package remove` after reviewing their usage.** Do not hand-delete only the manifest entry or leave synchronized Skills and plugin registrations behind.
|
|
186
182
|
|
|
187
|
-
##
|
|
188
|
-
|
|
189
|
-
When reporting or opening this application's address, use the `Local:` URL printed by `pnpm dev`, including the application base path. In normal full-stack development, the Hono server proxies Vite: the user-facing entry uses the server port (`APP_SERVER_PORT`, default 13000), while Vite's port (normally 5173) serves the frontend development process. A response from Vite alone does not verify the application entry.
|
|
190
|
-
|
|
191
|
-
For an existing run without available startup output, identify its process and working directory, confirm the actual server listening port and configured base path, and check that URL before sharing it. Occupied ports advance automatically, so do not assume defaults. Report when the run belongs to another checkout. Use a host reachable by the user; `localhost` refers to the machine where the browser runs.
|
|
192
|
-
|
|
193
|
-
With `PROXY_TARGET_URL`, the local Hono server is skipped and Vite becomes the local application entry. Use the printed `Local:` URL in this mode too; `APP_SERVER_PORT` selects its local port (default 5173). See the remote backend development guidance below.
|
|
194
|
-
|
|
195
|
-
## Development file watching
|
|
196
|
-
|
|
197
|
-
`pnpm dev` checks native file watching before starting its children. If watcher resources are exhausted or native events are unavailable, it uses polling for client and server hot updates and disables agent annotations for that run, with a warning. An explicit `CHOKIDAR_USEPOLLING=true` selects the same mode. Configuration files use stat polling so atomic saves and newly created files restart the server without native directory watchers.
|
|
198
|
-
|
|
199
|
-
Vite must exclude the application's entire `dist/` tree from development file watching. Its default exclusion covers only `dist/client`; watching the compiled server and vendored packages can cause `EMFILE` after a build. Keep the exclusion scoped to this application so linked workspace dependencies, including their `dist/` files, still receive hot updates.
|
|
200
|
-
|
|
201
|
-
## Remote backend development
|
|
202
|
-
|
|
203
|
-
Treat `/main` in examples as a default, never as a fixed route. Local `APP_BASE_PATH` resolves from the command-line environment, then `.env.local`, then `.env`, with `/main` as the fallback. Determine the remote application's actual public mount path separately and include it in `PROXY_TARGET_URL`; local and remote paths may differ. For example, local `APP_BASE_PATH=/local` and a target ending in `/crm` map `/local/api` to `/crm/api` and `/local/ws` to `/crm/ws`.
|
|
204
|
-
|
|
205
|
-
For local client debugging against another running application, use `PROXY_TARGET_URL=<remote-application-base-url> pnpm dev` (for example, `http://127.0.0.1:13000/main`, without `/api`). This starts Vite, proxies API and WebSocket paths, and skips the local server and its watchers. Existing `beforeDev` hooks still run. Open the printed Local URL. Client edits reload locally; backend edits require running or deploying the target separately. Requests use the target's data and permissions. See README.MD for authentication and path mapping requirements. Unset the variable to develop both sides locally.
|
|
206
|
-
|
|
207
|
-
The proxy maps same-origin browser HTTP and WebSocket Origin headers to the target origin, with matching Referer paths mapped to the target app base. It preserves foreign origins and does not add missing Origin headers. Test browser handshakes with an explicit Origin; an Origin-less Node WebSocket test does not verify browser compatibility. Production does not use this Vite adaptation: configure `APP_PUBLIC_ORIGIN` and preserve public Host/protocol information through the reverse proxy.
|
|
183
|
+
## The development server
|
|
208
184
|
|
|
209
|
-
|
|
185
|
+
When reporting or opening this application's address, use the `Local:` URL printed by `pnpm dev`, including the application base path; never infer it from default ports or from a response on Vite's port. [The development server](references/dev-server.md) covers verifying an existing run's URL, what restarts the development run, file watching, and developing the client against another backend with `PROXY_TARGET_URL`.
|
|
210
186
|
|
|
211
187
|
## Finishing
|
|
212
188
|
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# How an application is put together
|
|
2
|
+
|
|
3
|
+
Read this when you need to know where a file goes, which file composes the client or the server, how configuration reaches a module, or before changing the framework structure the template provides.
|
|
4
|
+
|
|
5
|
+
## Where things go
|
|
6
|
+
|
|
7
|
+
Business code goes in these places. This is where you work, and where you should stay unless the task genuinely requires otherwise:
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
client/routes.ts Declare a page route
|
|
11
|
+
client/pages/ The page component; a folder when a page has children or files of its own
|
|
12
|
+
client/components/ Your components
|
|
13
|
+
client/components/ui/ shadcn/ui primitives; add with the CLI, never hand-write or edit
|
|
14
|
+
client/hooks/ Hooks shared across features
|
|
15
|
+
client/locales/ Every user-visible string; system/ holds the template's copy
|
|
16
|
+
client/service-provider.ts Client startup: services that boot with the application
|
|
17
|
+
server/routes/ HTTP endpoints
|
|
18
|
+
server/providers/ Services and their lifecycle
|
|
19
|
+
database/main/migrations/ Schema changes
|
|
20
|
+
database/main/seeds/ Required initial data
|
|
21
|
+
database/main/collections/ Generated Collection artifacts; regenerate, never edit
|
|
22
|
+
cli/commands/ Commands this application owns
|
|
23
|
+
tests/ Tests; never beside the source
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
A page with children or page-local helpers uses a folder with `index.tsx`; child folders mirror route paths. Keep page-local components and data in that folder, reserving `client/components/` for application-wide components. See [child routes](frontend/references/child-routes.md) for examples.
|
|
27
|
+
|
|
28
|
+
A feature with a page and an API touches five places: a migration for the table, a route in `server/routes/`, a page in `client/pages/` declared in `client/routes.ts`, navigation on the page route, and strings in `client/locales/`.
|
|
29
|
+
|
|
30
|
+
## How the client is composed
|
|
31
|
+
|
|
32
|
+
`client/runtime.ts` composes the browser application; `client/react-providers.ts` declares React providers in outer-to-inner layers `root`, `application`, and `extension`. Applications use the first two and plugins own the last; `before` and `after` order providers only within their layer.
|
|
33
|
+
|
|
34
|
+
## How the server is composed
|
|
35
|
+
|
|
36
|
+
`server/runtime.ts` composes configuration, plugins, providers and routes; `server/app.ts` assembles the application. `server/standalone.ts` starts the Node listener and `server/embedded.ts` lets a host mount the same runtime. Register endpoints through `server/routes/index.ts`; queue consumers and background jobs are registered from a service provider, not discovered from a directory.
|
|
37
|
+
|
|
38
|
+
`server/app.ts` calls `createAppFromRuntime(runtime)` to transfer configuration, paths, mode and Host logging policy and bind `runtime.app`. Keep Provider, middleware and route registration explicit and ordered; `startApplicationInScope` owns startup and shutdown binding.
|
|
39
|
+
|
|
40
|
+
`runtime.paths`, configuration context `paths`, and `app.paths` share one resolved `AppPaths` object. Use `paths.storage('...')`, `paths.database('...')`, or the corresponding directory fields. `AppPathOptions` is input only; application path policies run before the final object is created and configuration is loaded. Standalone entries declare the deployment root in `server/runtime.ts` so the server and CLI share persistent storage outside the compiled code directory.
|
|
41
|
+
|
|
42
|
+
## Configuration
|
|
43
|
+
|
|
44
|
+
Editable module defaults live in `server/config/` and are collected by `defaultAppConfigs` in its `index.ts`; `server/config.ts` loads the configuration file. Each section declares the environment variables that set it in `env` of its `defineAppConfig`, with a `description` and, where it applies, `secret`, `required`, `generate` or `firstStartOnly` in the helper's second argument; `pnpm nocobase config env` lists them all, `pnpm nocobase config variables` describes each, and `pnpm build` writes that description to `dist/variables.json` for whoever deploys the build. `server/config/database.ts` maps `DB_*` onto the main connection and `server/config/users.ts` maps `INITIAL_ADMIN_*` onto the initial administrator. `config.yml` is read as written: a `${NAME}` in it is not expanded. [Services and jobs](services-and-jobs.md#application-code-configuration) shows how a module declares and reads its configuration.
|
|
45
|
+
|
|
46
|
+
## The rest is framework structure
|
|
47
|
+
|
|
48
|
+
`client/routing/`, `client/layouts/`, `client/theme/`, the server entry points, the `package.json` scripts that call `nocobase`, and the tsconfigs are the scaffolding the template provides. It is still this application's own source — it shipped to the user and they may change it — but it is the part the template evolves, so an edit there is what a future upgrade has to reconcile. [Customizing the shell](frontend/references/shell.md) lists the shell behaviors to keep.
|
|
49
|
+
|
|
50
|
+
Prefer the mechanism the system already provides. Declare a page in `client/routes.ts` and add `navigation` when it needs a menu entry. Refine resources add no menu entries and, with no data provider registered, load nothing; pages load data through `useApiClient`. A page uses `authz` to restrict access; a plugin page is customized through an option or an override. Before editing the shell to add a menu, check the route and its `navigation` declaration.
|
|
51
|
+
|
|
52
|
+
When the built-in mechanism genuinely cannot express what is being asked, changing this structure is a legitimate answer — not a last resort to apologize for. Do it deliberately, and leave the next agent enough to work with:
|
|
53
|
+
|
|
54
|
+
- Comment what you changed and why the built-in path did not fit. On upgrade, an agent reconciling the template's version needs to know whether your change is still needed.
|
|
55
|
+
- Record the application-specific guidance in the same change, so it describes the application as it actually is: update the topic file under the application's `.agents/rules/`, or add one, and keep its entry in the `AGENTS.md` index. Do not grow `AGENTS.md` itself; it stays a small always-on index of at most 32 KB that every agent loads on every start.
|
|
56
|
+
- If the framework's shared guidance is wrong for every application, propose the change to the source `@nocobase/app-skills` package instead of editing its synchronized copy.
|
|
@@ -51,7 +51,7 @@ Every command listed takes `--connection <name>` or `--all` where connections ap
|
|
|
51
51
|
|
|
52
52
|
## Reading the data model
|
|
53
53
|
|
|
54
|
-
`database/<connection>/collections/` holds what the database currently resolves each Collection to — `collection.json`, `metadata.json` and `schema.json` per Collection, plus `_manifest.json` — written by `pnpm nocobase collections generate`. Read these files, and search across them, rather than inferring the model from migrations.
|
|
54
|
+
`database/<connection>/collections/` holds what the database currently resolves each Collection to — `collection.json`, `metadata.json` and `schema.json` per Collection, plus `_manifest.json` — written by `pnpm nocobase collections generate`. Read these files, and search across them, rather than inferring the model from migrations. Edit metadata through migrations or the Collection Metadata Service and regenerate, never by hand.
|
|
55
55
|
|
|
56
56
|
The directory is a local cache for every connection, external ones included: gitignored, safe to delete, and never read back. `db apply`, `db redo`, `db rollback` and `db reset` refresh it for each connection whose migrations they change, and `pnpm dev` does the same after its startup migrations; a built `dist/` never writes it. Run `pnpm nocobase collections generate` yourself only when a command ran with `--no-collections` or warned that the refresh failed, after editing an external connection's `metadata/`, or after another system changed an external connection's schema. `--check` exits non-zero when the files are out of date. Never edit them by hand or import them from a migration.
|
|
57
57
|
|
|
@@ -8,9 +8,9 @@ A command this application owns is a file under `cli/commands/` that default-exp
|
|
|
8
8
|
|
|
9
9
|
Do not name a directory under `cli/commands/` `dist`, `build`, `coverage` or `generated`: each is ignored by `.gitignore`, Prettier or the shared ESLint preset, so a command inside one would go unlinted, or never reach git, without any warning.
|
|
10
10
|
|
|
11
|
-
`cli/` is compiled into `dist`, and every application command is registered there too, so a command runs in a deployment and may import only packages in `dependencies`. There is no development-only application command: one that needs the sources, such as a code generator, cannot read them in a deployment. Keep such work in a script, or in a plugin's `devCommands`.
|
|
11
|
+
`cli/` is compiled into `dist`, and every application command is registered there too, so a command runs in a deployment and may import only packages in `dependencies`. There is no development-only application command: one that needs the sources, such as a code generator, cannot read them in a deployment. Keep such work in a script, or in a plugin's `devCommands`. Change shared behavior in `@nocobase/app-cli` rather than copying it into the application, and use plugin build and dev hooks for local build and development extensions.
|
|
12
12
|
|
|
13
|
-
Write an application command when the work belongs to this application alone. Work several applications share belongs in a plugin, which contributes its commands under its own topic.
|
|
13
|
+
Write an application command when the work belongs to this application alone. Work users trigger while the application serves is a server route or a job, not a command. Work several applications share belongs in a plugin, which contributes its commands under its own topic.
|
|
14
14
|
|
|
15
15
|
<!-- command-authoring:start -->
|
|
16
16
|
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Adding a dependency
|
|
2
|
+
|
|
3
|
+
Read this before adding a package to `package.json`, when the shadcn CLI or a UI Library item has just added one, and when a build or a deployment fails on a missing module or a native binary.
|
|
4
|
+
|
|
5
|
+
## Which field a package goes in
|
|
6
|
+
|
|
7
|
+
Which half of the application imports it decides where it goes.
|
|
8
|
+
|
|
9
|
+
| The import is reached from | Declare it in |
|
|
10
|
+
| --------------------------------------- | ----------------- |
|
|
11
|
+
| `server/`, `database/`, or `cli/` | `dependencies` |
|
|
12
|
+
| `client/`, build tooling, tests | `devDependencies` |
|
|
13
|
+
| `import type` only, wherever it appears | `devDependencies` |
|
|
14
|
+
|
|
15
|
+
That split looks backwards until you see how the two halves are deployed. `pnpm build` bundles the client: Vite resolves every client import and inlines it into `dist/client`, so nothing has to resolve it again later. The server is not bundled. `dist/server` keeps its bare imports, and `pnpm build` generates `dist/package.json` from your `dependencies` and installs a `node_modules` next to it — that tree is what the deployed server resolves against, and `devDependencies` are not in it.
|
|
16
|
+
|
|
17
|
+
So the two mistakes fail in opposite ways. A server import left in `devDependencies` resolves in every development checkout and is absent exactly once — on the deployed server, with a bare `Cannot find package` naming nothing that points back here. A client package put in `dependencies` never breaks anything — it is just installed into every deployment, where the server never requires it. That one is invisible, so it accumulates: `lucide-react` and `@xyflow/react` were 44 MB of it before this rule was written down.
|
|
18
|
+
|
|
19
|
+
What decides it is where the importing file lives and what the import is, not what the package is for. `import ts from 'typescript'` in `server/` is a runtime dependency even though TypeScript sounds like tooling. `import type { Config } from 'x'` is erased before anything runs, so it stays a devDependency wherever it appears. A dynamic `import()` counts — deferring the load changes when a package is needed, not whether.
|
|
20
|
+
|
|
21
|
+
Keep `@nocobase/db` in `dependencies` alongside the database driver. It supplies the driver's runtime peer and lets TypeScript resolve the inferred database configuration declaration through the public package name. Moving it to `devDependencies` can cause TS2883 in an installed application even while the source workspace builds successfully.
|
|
22
|
+
|
|
23
|
+
A plugin's browser packages arrive by a third route and need nothing from you. Plugins declare those as peer dependencies, so installing a plugin brings one shared copy into this application, while `dist/` sets `autoInstallPeers: false` and installs none of them. Application plugins themselves belong in `dependencies`; see [plugins](plugins.md).
|
|
24
|
+
|
|
25
|
+
## Packages the shadcn CLI adds
|
|
26
|
+
|
|
27
|
+
The shadcn CLI adds the packages a primitive or a UI Library item needs to `dependencies`. Move the new ones, such as `react-day-picker` for `calendar`, to `devDependencies`, because client code is bundled. Leave `@nocobase/i18n` in `dependencies`, where the server needs it, and put back the `^` of its range, which the CLI pins. [shadcn](frontend/references/shadcn.md) covers the rest of what to do after adding a primitive.
|
|
28
|
+
|
|
29
|
+
## What the build checks
|
|
30
|
+
|
|
31
|
+
`pnpm build` checks the server half: it reads every value import in `server/`, `database/`, and `cli/` and fails the build if any of those packages is missing from `dist/package.json`. It cannot see an import whose specifier is built at run time:
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
await import(`${name}/index.js`); // invisible to the check
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Declare such a package in `dependencies` when you write the code; nothing will remind you later.
|
|
38
|
+
|
|
39
|
+
## When a build or a deployment fails
|
|
40
|
+
|
|
41
|
+
| Symptom | Cause | Fix |
|
|
42
|
+
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
43
|
+
| `Cannot find module 'x'` on the server, works locally | `x` is in `devDependencies`, which `dist/package.json` is not generated from | Move it to `dependencies` |
|
|
44
|
+
| A browser package will not resolve while building the application | A plugin declares it as a peer and nothing provides it | Add it to the application's `devDependencies` |
|
|
45
|
+
| `Error loading shared library`, `invalid ELF header`, or a bare `.node` path at startup | The binary does not match the server | Compare `require('./dist/package.json').nocobase.buildTarget` with the server's `process.platform`, `process.arch`, and `process.versions.modules`, then rebuild with matching flags |
|
|
46
|
+
| `no prebuilt binary for <target>` during the build | The package publishes no build for that combination | Check the package supports the target; musl coverage is thinner than glibc |
|
|
47
|
+
|
|
48
|
+
Node ABI to major version: 115 is Node 20, 127 is 22, 137 is 24, 147 is 26.
|
|
49
|
+
|
|
50
|
+
`pnpm build` targets the machine it runs on, so `pnpm build && pnpm start` works. A deployment build says where it is going: `--target linux-x64`, `--target linux-arm64`, `--target linux-x64-musl`, plus `--node-version` when the server's Node major differs. A `.node` binary must match the target platform, architecture, and C library; addons using the Node ABI must also match its version. `pg`, `mysql2`, and `tedious` are plain JavaScript, so an application using only those is portable as built. The Finishing section of [the Skill](../SKILL.md#finishing) and the `nocobase-deployment` Skill cover build targets in full.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# The development server
|
|
2
|
+
|
|
3
|
+
Read this when you report or open the application's address, when `pnpm dev` restarts, refuses to start or watches too much, or when you develop the client against another running application.
|
|
4
|
+
|
|
5
|
+
## Application access URLs
|
|
6
|
+
|
|
7
|
+
When reporting or opening this application's address, use the `Local:` URL printed by `pnpm dev`, including the application base path. In normal full-stack development, the Hono server proxies Vite: the user-facing entry uses the server port (`APP_SERVER_PORT`, default 13000), while Vite's port (normally 5173) serves the frontend development process. A response from Vite alone does not verify the application entry.
|
|
8
|
+
|
|
9
|
+
For an existing run without available startup output, identify its process and working directory, confirm the actual server listening port and configured base path, and check that URL before sharing it. Occupied ports advance automatically, so do not assume defaults. Report when the run belongs to another checkout. Use a host reachable by the user; `localhost` refers to the machine where the browser runs.
|
|
10
|
+
|
|
11
|
+
With `PROXY_TARGET_URL`, the local Hono server is skipped and Vite becomes the local application entry. Use the printed `Local:` URL in this mode too; `APP_SERVER_PORT` selects its local port (default 5173). See [remote backend development](#remote-backend-development) below.
|
|
12
|
+
|
|
13
|
+
## What restarts the development run
|
|
14
|
+
|
|
15
|
+
Changes to `.env` and `.env.local` (including creation, atomic replacement, and deletion) restart the full development run after its previous processes exit. The new run reloads environment files, ports, proxy settings, and startup hooks; explicit shell variables still take precedence. Use the newly printed URL if the port or base path changes. This also applies in proxy mode. `config.yml` changes restart only the local server. `NOCOBASE_STRICT_STARTUP=true` disables both automatic restarts.
|
|
16
|
+
|
|
17
|
+
Changes to `package.json`, the lockfile, and the package manager's install state restart the local server once they have been quiet for a few seconds. An install writes several of them over as long as fetching and linking take, so restarting on the first write would bring the server back against a half-installed `node_modules` — and the next write would arrive while it was still shutting down, which is where the watcher escalates to SIGKILL. Waiting for quiet turns one install into one restart.
|
|
18
|
+
|
|
19
|
+
## One development server per application
|
|
20
|
+
|
|
21
|
+
One development server runs per application root; a second is refused with the first one's process id. Nothing else catches it, because the port check advances to the next free port and the duplicate then fails on the migration lock the first server holds, long before it binds anything. `NOCOBASE_DEV_ALLOW_MULTIPLE=true` starts one anyway. A run that only proxies a remote backend does not take the lock, and a lock left behind by a killed run is taken over rather than reported.
|
|
22
|
+
|
|
23
|
+
`pnpm dev` also shortens the shutdown budget, through `APP_SHUTDOWN_TIMEOUT_MS`, to less than the five seconds the file watcher waits before force-killing the server. The deployment defaults — a 30 second HTTP drain behind a load balancer — would never be reached here, and a force-killed server never releases its migration lock. Set the variable explicitly to override it in either direction.
|
|
24
|
+
|
|
25
|
+
Tests that start auxiliary Vite servers must use an isolated temporary `cacheDir`, including when their fixture links the application's `node_modules`. Never delete or rewrite a running development server's dependency cache. See [testing and verification](testing.md) for cache ownership and recovery.
|
|
26
|
+
|
|
27
|
+
## File watching
|
|
28
|
+
|
|
29
|
+
`pnpm dev` checks native file watching before starting its children. If watcher resources are exhausted or native events are unavailable, it uses polling for client and server hot updates and disables agent annotations for that run, with a warning. An explicit `CHOKIDAR_USEPOLLING=true` selects the same mode. Configuration files use stat polling so atomic saves and newly created files restart the server without native directory watchers.
|
|
30
|
+
|
|
31
|
+
Vite must exclude the application's entire `dist/` tree from development file watching. Its default exclusion covers only `dist/client`; watching the compiled server and vendored packages can cause `EMFILE` after a build. Keep the exclusion scoped to this application so linked workspace dependencies, including their `dist/` files, still receive hot updates.
|
|
32
|
+
|
|
33
|
+
## Remote backend development
|
|
34
|
+
|
|
35
|
+
Treat `/main` in examples as a default, never as a fixed route. Local `APP_BASE_PATH` resolves from the command-line environment, then `.env.local`, then `.env`, with `/main` as the fallback. Determine the remote application's actual public mount path separately and include it in `PROXY_TARGET_URL`; local and remote paths may differ. For example, `APP_BASE_PATH=/local PROXY_TARGET_URL=http://127.0.0.1:13000/crm pnpm dev` forwards local `/local/api` and `/local/ws` to remote `/crm/api` and `/crm/ws`.
|
|
36
|
+
|
|
37
|
+
For local client debugging against another running application, use `PROXY_TARGET_URL=<remote-application-base-url> pnpm dev` (for example, `https://backend.example.com/main`, without `/api`). This starts Vite, proxies API and WebSocket paths, and skips the local server and its watchers. Existing `beforeDev` hooks still run. Open the printed Local URL. Client edits reload locally; backend edits require running or deploying the target separately. Requests, including writes, use the target's data and permissions. See the application's README.MD for authentication and path mapping requirements. Unset the variable to develop both sides locally.
|
|
38
|
+
|
|
39
|
+
The proxy maps same-origin browser HTTP and WebSocket Origin headers to the target origin, with matching Referer paths mapped to the target app base. It preserves foreign origins and does not add missing Origin headers. Keep backend origin checks enabled. Test browser handshakes with an explicit Origin; an Origin-less Node WebSocket test does not verify browser compatibility. Production does not use this Vite adaptation: configure `APP_PUBLIC_ORIGIN` and preserve public Host/protocol information through the reverse proxy.
|
|
40
|
+
|
|
41
|
+
Use `APP_SERVER_PORT` for the local entry port in both development modes. With `PROXY_TARGET_URL` it selects Vite's preferred port, defaulting to 5173; without it, it selects the local backend port, defaulting to 13000, and Vite still starts from 5173. If occupied, the port advances automatically. Open the printed Local URL and keep the remote service address in `PROXY_TARGET_URL`; this variable does not change it.
|
|
42
|
+
|
|
43
|
+
## Development logging
|
|
44
|
+
|
|
45
|
+
`pnpm dev` owns the ready banner and public URL; `APP_SERVER_START_LOG=false` suppresses the underlying listener announcement through the `env` of `server/config/server.ts`. Keep that mapping when editing deployment environment settings. Request starts, request headers and config diagnostics use DEBUG; the normal INFO output contains completion summaries. See the Logging section of [the Skill](../SKILL.md#logging) for hosted logging and upgrade limits.
|
|
@@ -618,11 +618,12 @@ A page that shows a record whose detail is a page of its own — an orders list'
|
|
|
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
620
|
- Groups can contain groups. A group's `name` must be unique, like a route name.
|
|
621
|
+
- **How a group shows in the menu**: a top-level group is a section, its title a small heading over its entries, which are always shown; use it to sort the menu into areas such as Records or Settings. A group inside another group is a collapsible sub-menu. `NavigationMenu`'s `sections={false}` draws top-level groups as collapsible sub-menus too.
|
|
621
622
|
- **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
623
|
- 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
624
|
- A path with a parameter cannot have `navigation`.
|
|
624
625
|
- `navigation.order` sets the order among siblings; lower numbers come first.
|
|
625
|
-
-
|
|
626
|
+
- Collapsible groups keep their expanded or collapsed state while the navigation tree stays mounted; opening a new page automatically expands its ancestor groups.
|
|
626
627
|
|
|
627
628
|
## 7. Settings pages
|
|
628
629
|
|
|
@@ -275,6 +275,24 @@ Write `navigation` on the route. The application sidebar reads its menu entries
|
|
|
275
275
|
- Do not change the shell (`client/layouts/`) or the ServiceProvider to add a menu entry, and do not add a Refine resource for a menu. Refine resources produce no menu entries (see ["Loading data in a component" in `api.md`](api.md#loading-data-in-a-component) for what they are for); the home page entry is declared in the routes as well.
|
|
276
276
|
- A new page with a menu entry usually touches four places: `client/routes.ts`, the page component, `client/locales/` and, for an App page that requires sign-in, the page grant list in `tests/logic/client-routes.test.ts` ([section 12](#12-update-the-route-test)).
|
|
277
277
|
|
|
278
|
+
### A count beside an entry
|
|
279
|
+
|
|
280
|
+
An entry can show how many things wait on the viewer behind it, such as unread messages or requests to decide. A count changes while the page is open, so it is not part of the route's `navigation`: the App layout reads it with the hook that keeps it current and passes it to `NavigationMenu` in `badges`, keyed by the route's `name`:
|
|
281
|
+
|
|
282
|
+
```tsx
|
|
283
|
+
// client/layouts/app-layout.tsx
|
|
284
|
+
const { data: unread = 0 } = useInboxUnreadCount(); // @nocobase/app-plugin-notification-in-app/client/inbox
|
|
285
|
+
|
|
286
|
+
<NavigationMenu
|
|
287
|
+
items={menuItems}
|
|
288
|
+
label={navigationLabel}
|
|
289
|
+
selectedKey={selectedKey}
|
|
290
|
+
badges={{ inbox: unread }}
|
|
291
|
+
/>;
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
A number is something waiting; `{ count, live: true, hint }` is work under way, such as runs in progress, drawn in the primary color behind a pulsing dot, with `hint` (translated, such as "2 running") as its words. The menu does the rest: nothing at zero, "99+" above 99, the count in the entry's accessible name and tooltip, and in the collapsed sidebar a dot on the icon's corner. A count goes on a page entry the menu always shows — a top-level entry or a section's — not on a group or an entry inside a sub-menu. Which counts belong in the menu at all is guideline L8 of [`../ui-guidelines.md`](../ui-guidelines.md).
|
|
295
|
+
|
|
278
296
|
## 7. Back button and breadcrumbs
|
|
279
297
|
|
|
280
298
|
The shell header shows the current page's breadcrumb after the sidebar toggle, on every page; pages never render breadcrumbs themselves. A page that sits below another one — a covering child page, a record's own page, a form too long for a dialog — has a back button above its title (guideline L6), unless its header trail already leads back the same way; do not render both, and do not add a "Back to list" button to `actions`.
|
|
@@ -25,7 +25,7 @@ pnpm exec prettier --write client/components/ui/field.tsx client/components/ui/s
|
|
|
25
25
|
- **Translate the English they carry**, as ["English built into primitives"](#english-built-into-primitives) below lists.
|
|
26
26
|
- Each document of the worked example names what it needs on its **Add first** line ([`example.md`](example.md)).
|
|
27
27
|
- A bare name comes from `@shadcn`, the registry for primitives, and `@nocobase/<item>` from the NocoBase UI Library ([section 3 of `styling.md`](styling.md#3-use-shadcn); offline, the catalog in [`ui-library.md`](ui-library.md)). Neither needs the user's choice; ask before adding from any other registry, as the skill says.
|
|
28
|
-
- When a primitive needs an npm package the application does not have yet (`recharts` for `chart`, `cmdk` for `command`), the CLI installs it into `dependencies`, such as `react-day-picker` for `calendar`, and a UI Library item does the same with the packages it declares. Move them to `devDependencies`: client code is bundled, and `dependencies` is what every deployment installs (
|
|
28
|
+
- When a primitive needs an npm package the application does not have yet (`recharts` for `chart`, `cmdk` for `command`), the CLI installs it into `dependencies`, such as `react-day-picker` for `calendar`, and a UI Library item does the same with the packages it declares. Move them to `devDependencies`: client code is bundled, and `dependencies` is what every deployment installs ([adding a dependency](../../dependencies.md)). A package already declared in `devDependencies` stays there. An item that translates its labels also adds `@nocobase/i18n` again, which pins its range in `dependencies` to an exact version; leave it in `dependencies`, where the server needs it, and put the `^` back.
|
|
29
29
|
- Import `cn` from the `cn` package, which `devDependencies` declares, as the registry's primitives and the template's own code do. `client/lib/utils.ts` only re-exports it, the way `shadcn init` writes the file, so an older `#lib/utils` import still works; write new code against `cn`.
|
|
30
30
|
- Apart from formatting and those translations, keep each primitive as the CLI writes it. For a different look, use its props or change the theme ([`theme.md`](theme.md)). The template's own copies differ from the registry too, which is one more reason to answer no: `dialog.tsx`, `sheet.tsx`, `spinner.tsx` and `toast.tsx` translate their labels, and `button.tsx` sizes its small text with `text-sm` instead of the registry's fixed `text-[0.8rem]`.
|
|
31
31
|
- To update a primitive, compare first with `pnpm exec shadcn add <name> --diff <file>`, and overwrite only with the user's approval, as "Updating Components" in the skill says. Then apply the translations again: `tests/components/primitive-labels.test.tsx` fails when a shipped primitive has lost one.
|
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
# Customizing the application shell
|
|
2
2
|
|
|
3
|
-
The shell is `client/routing/` and `client/layouts/`, with the header, sidebar and account controls in `client/layouts/components/`. It is template scaffolding this application owns: declare business pages, menus and permissions on the routes instead ([`page.md`](page.md)), and change the shell only when they cannot express the requirement. When you do, comment in the code what you changed and why, so that a later template upgrade can judge whether the change is still needed (
|
|
3
|
+
The shell is `client/routing/` and `client/layouts/`, with the header, sidebar and account controls in `client/layouts/components/`. It is template scaffolding this application owns: declare business pages, menus and permissions on the routes instead ([`page.md`](page.md)), and change the shell only when they cannot express the requirement. When you do, comment in the code what you changed and why, so that a later template upgrade can judge whether the change is still needed, and record the shell's application-specific behavior in `.agents/rules/` as [application structure](../../app-structure.md#the-rest-is-framework-structure) describes.
|
|
4
4
|
|
|
5
5
|
## 1. Behaviors to keep
|
|
6
6
|
|
|
7
7
|
- There is no settings area and no Settings or Inbox entry in the header: every signed-in page renders inside `AppLayout`, and settings pages are ordinary pages in the sidebar ([section 5 of `page.md`](page.md#5-settings-pages)). Do not add a second layout or a `/settings` route split to the router.
|
|
8
8
|
- The account menu's language control (`client/layouts/components/language-switcher.tsx`) is a submenu with radio items and must stay inside `DropdownMenuContent`, which provides its keyboard navigation and selected state.
|
|
9
|
-
-
|
|
10
|
-
- The sidebar is shadcn's `Sidebar`, composed in `client/layouts/components/app-sidebar.tsx` (provider, desktop sidebar, phone sheet, header toggle) and `navigation-menu.tsx` (the route tree as `SidebarMenu*` entries with controlled `Collapsible` sub-menus). Keep `client/components/ui/sidebar.tsx` as the shadcn CLI writes it and change the sidebar from these two files: the widths are set through the provider's `style` in spacing units (`--sidebar-width`, `--sidebar-width-icon`) so they follow the density preset; the phone sheet is rendered in `app-sidebar.tsx` with a translated title instead of the primitive's own; and the provider's Ctrl/Cmd+B shortcut is stopped by a `document` keydown listener, so the key stays with editors.
|
|
11
|
-
- The desktop sidebar can collapse to icons: leaf entries then show their label in a tooltip without delay and groups open in a popover on hover or keyboard focus, keeping the filtered entries, parent-page links, nested groups and the highlight of the group holding the current page. The collapsed state is shared through `useSidebarPreference` under `nocobase:sidebar:collapsed` by every application on the same origin, while whether the phone sheet is open stays local to each layout.
|
|
9
|
+
- Collapsible navigation groups keep their expanded or collapsed state while the navigation tree stays mounted; opening a new page expands its ancestor groups without collapsing the others.
|
|
10
|
+
- The sidebar is shadcn's `Sidebar`, composed in `client/layouts/components/app-sidebar.tsx` (provider, desktop sidebar, phone sheet, header toggle) and `navigation-menu.tsx` (the route tree as `SidebarMenu*` entries: a top-level group with no page is a section under a heading, its entries always shown; clickable parents and nested groups are controlled `Collapsible` sub-menus; counts beside entries come from the layout through its `badges`, [`page.md`](page.md#a-count-beside-an-entry)). Keep `client/components/ui/sidebar.tsx` as the shadcn CLI writes it and change the sidebar from these two files: the widths are set through the provider's `style` in spacing units (`--sidebar-width`, `--sidebar-width-icon`) so they follow the density preset; the phone sheet is rendered in `app-sidebar.tsx` with a translated title instead of the primitive's own; and the provider's Ctrl/Cmd+B shortcut is stopped by a `document` keydown listener, so the key stays with editors.
|
|
11
|
+
- The desktop sidebar can collapse to icons: leaf entries then show their label in a tooltip without delay and section headings hide and their entries keep their icons, collapsible groups open in a popover on hover or keyboard focus, keeping the filtered entries, parent-page links, nested groups and the highlight of the group holding the current page. The collapsed state is shared through `useSidebarPreference` under `nocobase:sidebar:collapsed` by every application on the same origin, while whether the phone sheet is open stays local to each layout.
|
|
12
12
|
- The authorization provider clears the permission snapshot before rendering a new session; route navigation and page guards subscribe to the authorization revision, so account switches and permission changes take effect without a reload.
|
|
13
13
|
- When signing out, the account menu checks the result from Better Auth and shows a localized error message on failure; do not treat navigating away as having signed out.
|
|
14
14
|
|
|
@@ -327,6 +327,7 @@ export function DeleteProjectButton({
|
|
|
327
327
|
- Status data needs text; do not rely on color alone to tell values apart.
|
|
328
328
|
- Make each enum (for example project status) one component, shared by the list and the detail view (`ProjectStatusBadge`, see [`i18n.md`](i18n.md)).
|
|
329
329
|
- Icons in a Badge also get `data-icon`; to render it as a link, use `render={<Link … />}`.
|
|
330
|
+
- A badge has two sizes, which `client/styles.css` draws for every `Badge`, the plugins' included. The default one stands on its own: a status in a table's column or among a record's particulars. The small one, `data-size='sm'` (`size='sm'` on `StatusBadge`), sits beside a title or a name, on a card or a board's card, or several to a dense row. Choose between them with the attribute rather than with `h-*`, `px-*` or a `text-[11px]` on the badge, which the stylesheet overrides.
|
|
330
331
|
|
|
331
332
|
## 10. Icons
|
|
332
333
|
|
|
@@ -339,6 +340,9 @@ export function DeleteProjectButton({
|
|
|
339
340
|
- **The application must look like one product.** Before writing a component, look at how neighboring pages handle the same problem: spacing scale, heading sizes, cards or flat sections, where actions go. Follow them.
|
|
340
341
|
- **When a different look is genuinely needed, change it globally.** Change the tokens in `client/theme/themes/*.css` ([`theme.md`](theme.md)), or change the component all pages share, so the whole application changes together.
|
|
341
342
|
- **Do not change only the part you are working on.** A page with its own spacing, button styling, or color scheme is a defect. If you think the application's style should change, raise it and change it globally; do not let one page's look diverge.
|
|
343
|
+
- **Whatever may be clicked shows the pointer.** `client/styles.css` gives buttons, links, menu items, options, tabs, checkboxes, radios, switches, comboboxes, `summary`, `select`, `label[for]` and native checkbox, radio and file inputs the pointer cursor unless disabled. Prefer those elements; something clickable that is none of them, such as a card whose click handler sits on a `div`, adds `cursor-pointer` itself, and a disabled one keeps the arrow.
|
|
344
|
+
- **A card that opens something lifts under the pointer.** It rises half a unit, takes `shadow-md` and the `--hover` grey: `transition-[translate,box-shadow,background-color] duration-200 ease-out hover:-translate-y-0.5 hover:bg-hover hover:shadow-md motion-reduce:transition-none motion-reduce:hover:translate-y-0` (the `group-hover:` forms when the card sits inside the clickable element, as the template homepage's capability cards do). The card's own frame stays as it is; an icon tile inside it takes a frame of the general border, `ring-1 ring-transparent group-hover:ring-border`. A card that only shows content does not react to the pointer, and a row in a list or table takes the `--hover` grey without lifting: the template's stylesheet gives it to every `table` row that keeps the primitive's own hover, and a list item you build takes `hover:bg-hover`.
|
|
345
|
+
- **Every control shares one focus.** `client/styles.css` gives fields (the `input`, `textarea`, `select-trigger` and `input-group` slots), buttons, links, tabs, menu items, checkboxes, switches and radios, the plugins' copies included, a half-strength `--ring` border and a 2px halo at a fifth of `--ring` when focused, in place of the 3px ring the primitives draw; an invalid field keeps its red and a destructive button its own color. It is unlayered, so it wins over a control's own `focus-visible:` utilities: do not add `focus-visible:ring-*` or `focus-visible:border-*` classes to restyle one control's focus, and change the shared rule instead when the focus should look different. To give focus another color, change `--ring` in the theme ([`theme.md`](theme.md)), not the rule.
|
|
342
346
|
|
|
343
347
|
## 12. Dark mode
|
|
344
348
|
|
|
@@ -30,7 +30,7 @@ The template ships two presets. They share every color, font and shadow and diff
|
|
|
30
30
|
|
|
31
31
|
| id | Label (en-US / zh-CN) | Role | `--spacing` | `--radius` | Line heights |
|
|
32
32
|
| --------- | --------------------- | --------------------------------------------------- | ----------- | ---------- | ----------------------- |
|
|
33
|
-
| `compact` | Compact / 紧凑 | First in the registry: the default and the fallback | `0.
|
|
33
|
+
| `compact` | Compact / 紧凑 | First in the registry: the default and the fallback | `0.225rem` | `0.5rem` | Tighter than Tailwind's |
|
|
34
34
|
| `default` | Spacious / 宽松 | The roomier alternative | `0.25rem` | `0.5rem` | Tailwind's defaults |
|
|
35
35
|
|
|
36
36
|
The id `default` dates from when that preset was the default. It keeps the id because ids are saved in browsers and named in `config.yml`, and it is labeled Spacious so that the label does not claim it is the default selection. Do not relabel it "Default".
|
|
@@ -40,37 +40,39 @@ The id `default` dates from when that preset was the default. It keeps the id be
|
|
|
40
40
|
### Colors
|
|
41
41
|
|
|
42
42
|
- Values are complete CSS colors, normally OKLCH, not HSL channels. Do not wrap them in `hsl()`.
|
|
43
|
-
- Define all
|
|
43
|
+
- Define all 32 color tokens in both the light and the dark rule.
|
|
44
44
|
- Surfaces and foregrounds come in pairs: a background and the text or icons on it. A pair does not guarantee enough contrast; measure it (guideline A5 in [`../ui-guidelines.md`](../ui-guidelines.md)).
|
|
45
45
|
|
|
46
|
-
| Tokens | Meaning and consumers
|
|
47
|
-
| --------------------------------------------------- |
|
|
48
|
-
| `--background`, `--foreground` | Page surface and default text
|
|
49
|
-
| `--card`, `--card-foreground` | Cards and panels
|
|
50
|
-
| `--popover`, `--popover-foreground` | Floating surfaces: menus, popovers, dialogs
|
|
51
|
-
| `--primary`, `--primary-foreground` | Primary actions
|
|
52
|
-
| `--secondary`, `--secondary-foreground` | Secondary actions
|
|
53
|
-
| `--muted`, `--muted-foreground` | Subtle surfaces and supporting text
|
|
54
|
-
| `--accent`, `--accent-foreground` | Interactive highlighted surfaces (hovered or focused menu items)
|
|
55
|
-
| `--
|
|
56
|
-
| `--
|
|
57
|
-
| `--
|
|
58
|
-
| `--
|
|
59
|
-
| `--sidebar
|
|
60
|
-
| `--sidebar-
|
|
61
|
-
| `--sidebar-
|
|
46
|
+
| Tokens | Meaning and consumers |
|
|
47
|
+
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| `--background`, `--foreground` | Page surface and default text |
|
|
49
|
+
| `--card`, `--card-foreground` | Cards and panels |
|
|
50
|
+
| `--popover`, `--popover-foreground` | Floating surfaces: menus, popovers, dialogs |
|
|
51
|
+
| `--primary`, `--primary-foreground` | Primary actions |
|
|
52
|
+
| `--secondary`, `--secondary-foreground` | Secondary actions |
|
|
53
|
+
| `--muted`, `--muted-foreground` | Subtle surfaces and supporting text |
|
|
54
|
+
| `--accent`, `--accent-foreground` | Interactive highlighted surfaces (hovered or focused menu items) |
|
|
55
|
+
| `--hover` | The light grey of what is picked out: a hovered row or button, the menu's current and hovered entries, a table's header |
|
|
56
|
+
| `--destructive` | Destructive actions and errors |
|
|
57
|
+
| `--border`, `--input`, `--ring` | General borders; input borders and surfaces; focus indicators |
|
|
58
|
+
| `--chart-1` through `--chart-5` | Five chart series colors |
|
|
59
|
+
| `--sidebar`, `--sidebar-foreground` | Navigation surface and text |
|
|
60
|
+
| `--sidebar-primary`, `--sidebar-primary-foreground` | Selected navigation item surface and text |
|
|
61
|
+
| `--sidebar-accent`, `--sidebar-accent-foreground` | Hovered navigation item surface and text |
|
|
62
|
+
| `--sidebar-border`, `--sidebar-ring` | Navigation dividers and focus indicators |
|
|
62
63
|
|
|
63
64
|
The matching classes are `bg-card text-card-foreground`, `border-input`, `ring-ring`, `bg-sidebar text-sidebar-foreground` and so on. Charts must reference the series explicitly with `fill-chart-1`, `stroke-chart-2` or `var(--chart-1)`; a chart library does not pick these variables up on its own.
|
|
64
65
|
|
|
65
66
|
There is no `--destructive-foreground`. The primitives draw destructive buttons and badges as `text-destructive` on a `bg-destructive/10` tint (`/20` in dark), so `--destructive` must read as text on the page, card and popover surfaces and on its own tint.
|
|
66
67
|
|
|
67
|
-
The template
|
|
68
|
+
The template's grounds, text and lines are neutral, with zero chroma: `--background`, `--card`, `--popover`, `--muted`, `--secondary`, `--hover`, `--border`, `--input` and the sidebar's grounds. Its color sits in `--primary` (the NocoBase blue) and what follows it — `--accent`, `--ring`, the current navigation entry's words — and in `--destructive`, the status colors and the five chart series.
|
|
68
69
|
|
|
69
70
|
**Surface and outline tokens carry structure, not decoration.** A preset that forgets this reads as a color clash rather than as a style:
|
|
70
71
|
|
|
71
72
|
- Keep `--card` and `--popover` in the hue family of `--background`, so a panel lifts off the page instead of changing color.
|
|
72
73
|
- Keep `--muted` a tint close to the background.
|
|
73
74
|
- Keep `--border` and `--input` low-chroma hairlines, not a second statement of `--primary`.
|
|
75
|
+
- Keep `--border` fainter than `--input`. General borders — cards, tables, dividers, the sidebar's and header's rules, overlays — are the faint line that separates surfaces, so the template sets the light `--border` to `--input`'s color at 60% opacity, and the dark rule likewise keeps `--border` below `--input`. Form fields keep the firmer `--input`, so a person can still see where to type. Do not darken a border with `border-foreground/…` or a fixed color to make one panel stand out, and do not give fields `border-border`. Because that line is translucent, it is tuned to the template's very light `--background`: a preset that darkens `--background` fades its borders with it, so make `--border` opaque there (`oklch(0.9 0 0)`, `--input`'s color) or darker in step, and check a card's frame on the page before keeping the change.
|
|
74
76
|
- Put the preset's actual color in `--primary`, `--secondary`, `--accent` and the chart series, which appear on small, deliberate areas.
|
|
75
77
|
- Check a preset on a page that stacks several panels and dozens of dividers, not on one that shows a single card.
|
|
76
78
|
|
|
@@ -83,15 +85,17 @@ Sidebar tokens may reference the preset's general colors, as both template prese
|
|
|
83
85
|
/* … */
|
|
84
86
|
--sidebar: var(--card);
|
|
85
87
|
--sidebar-foreground: var(--card-foreground);
|
|
86
|
-
--sidebar-primary: color-mix(in
|
|
88
|
+
--sidebar-primary: color-mix(in srgb, var(--primary) 8%, var(--sidebar));
|
|
87
89
|
--sidebar-primary-foreground: var(--primary);
|
|
88
|
-
--sidebar-accent: var(--
|
|
89
|
-
--sidebar-accent-foreground: var(--foreground);
|
|
90
|
+
--sidebar-accent: var(--hover);
|
|
91
|
+
--sidebar-accent-foreground: var(--sidebar-foreground);
|
|
90
92
|
--sidebar-border: var(--border);
|
|
91
93
|
--sidebar-ring: var(--ring);
|
|
92
94
|
}
|
|
93
95
|
```
|
|
94
96
|
|
|
97
|
+
The current entry sits on a faint tint of `--primary` with its words and icon in `--primary`; a hovered entry takes `--hover`, the grey a table's header also takes, and keeps the menu's words. Keep the tint faint, so a menu of many entries stays quiet and the current one still stands out.
|
|
98
|
+
|
|
95
99
|
They remain independently configurable: to change the sidebar, change these tokens. Do not redefine general colors such as `--card` on the sidebar to change its appearance.
|
|
96
100
|
|
|
97
101
|
### Fonts
|
|
@@ -155,14 +159,14 @@ The Spacious line heights are Tailwind's defaults.
|
|
|
155
159
|
|
|
156
160
|
### Spacing
|
|
157
161
|
|
|
158
|
-
- `--spacing` is a positive CSS length: `0.
|
|
162
|
+
- `--spacing` is a positive CSS length: `0.225rem` in Compact and `0.25rem`, Tailwind's default, in Spacious. Numeric classes such as `p-4`, `gap-2`, `h-8`, `size-4` and `w-64` multiply it by their suffix, so `h-8` is 1.8rem in Compact and 2rem in Spacious.
|
|
159
163
|
- Changing it moves padding, gaps, control and icon sizes and the navigation width together; the sidebar's widths are `--sidebar-width` and `--sidebar-width-icon`, set in spacing units (64 and 12) in `client/layouts/components/app-sidebar.tsx`. Check typography and spacing together: text must not be clipped, and targets must stay usable.
|
|
160
164
|
- Percentages, viewport units, container widths such as `max-w-2xl` or `w-xs`, and arbitrary values such as `mt-[7px]` do not use this scale. Breakpoints do not change.
|
|
161
165
|
- Use numeric classes for ordinary spacing and sizes. Keep deliberate constraints that should not scale, such as viewport limits, images and separators. Do not change the root font size to simulate density, and do not add ad hoc height tokens.
|
|
162
166
|
|
|
163
167
|
### Radius
|
|
164
168
|
|
|
165
|
-
`--radius` is a nonnegative CSS length: `0.
|
|
169
|
+
`--radius` is a nonnegative CSS length: `0.5rem` in both presets. The `@theme inline` block in `client/styles.css` derives the public corner classes from it:
|
|
166
170
|
|
|
167
171
|
| Class | Multiplier |
|
|
168
172
|
| ------------- | ---------- |
|
|
@@ -214,7 +218,7 @@ Some values stay fixed on purpose. Know which ones, and keep your own explicit.
|
|
|
214
218
|
|
|
215
219
|
### Constraints from the token test
|
|
216
220
|
|
|
217
|
-
`tests/logic/theme-tokens.test.ts` requires `compact.css` and `default.css` to be identical, in both the light and the dark rule, except for `--spacing`, `--radius` and the `--text-*` variables, and it requires Compact's `--spacing` to be smaller than Spacious'. Today the two differ in spacing
|
|
221
|
+
`tests/logic/theme-tokens.test.ts` requires `compact.css` and `default.css` to be identical, in both the light and the dark rule, except for `--spacing`, `--radius` and the `--text-*` variables, and it requires Compact's `--spacing` to be smaller than Spacious'. Today the two differ in spacing and line heights; the radius and the text sizes are the same. So:
|
|
218
222
|
|
|
219
223
|
- A change to colors, fonts or shadows goes into both files, light and dark rules alike.
|
|
220
224
|
- Density (spacing, radius, text sizes and line heights) may differ between the two.
|
|
@@ -225,7 +229,7 @@ Some values stay fixed on purpose. Know which ones, and keep your own explicit.
|
|
|
225
229
|
The steps below add a preset with the id `forest`.
|
|
226
230
|
|
|
227
231
|
1. **Copy a file.** Copy the preset whose density the new one should share to `client/theme/themes/forest.css`: `compact.css` for the application's default density, `default.css` for the spacious one. Use a stable id of lowercase letters, digits and hyphens, and name the file after it: the token test loads `client/theme/themes/<id>.css` for every registered id.
|
|
228
|
-
2. **Set the selectors and tokens.** Light uses `:root[data-theme='forest'], .theme-preview[data-theme='forest']`; dark uses `:root.dark[data-theme='forest'], :root.dark .theme-preview[data-theme='forest']`. Keep the single quotes: the token test looks the selectors up by their exact text. If you copied `default.css`, delete its bare `:root` and `:root.dark` selectors. Only `default.css` may carry them; whichever file is imported last would otherwise take over the fallback. Set `--radius` and all
|
|
232
|
+
2. **Set the selectors and tokens.** Light uses `:root[data-theme='forest'], .theme-preview[data-theme='forest']`; dark uses `:root.dark[data-theme='forest'], :root.dark .theme-preview[data-theme='forest']`. Keep the single quotes: the token test looks the selectors up by their exact text. If you copied `default.css`, delete its bare `:root` and `:root.dark` selectors. Only `default.css` may carry them; whichever file is imported last would otherwise take over the fallback. Set `--radius` and all 32 colors, keep the fonts, sizes, spacing and shadows unless the preset is meant to change them, and repeat every color in the dark rule.
|
|
229
233
|
|
|
230
234
|
```css
|
|
231
235
|
/* client/theme/themes/forest.css */
|
|
@@ -239,7 +243,7 @@ The steps below add a preset with the id `forest`.
|
|
|
239
243
|
ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI',
|
|
240
244
|
'PingFang SC', 'Microsoft YaHei', sans-serif;
|
|
241
245
|
/* … --font-serif through --shadow-2xl: copied from compact.css unchanged */
|
|
242
|
-
--radius: 0.
|
|
246
|
+
--radius: 0.5rem;
|
|
243
247
|
--background: oklch(0.985 0.005 150);
|
|
244
248
|
--foreground: oklch(0.2 0.02 150);
|
|
245
249
|
--card: oklch(0.995 0.003 150);
|
|
@@ -254,8 +258,9 @@ The steps below add a preset with the id `forest`.
|
|
|
254
258
|
--muted-foreground: oklch(0.5 0.02 150);
|
|
255
259
|
--accent: oklch(0.93 0.04 130);
|
|
256
260
|
--accent-foreground: oklch(0.25 0.04 150);
|
|
261
|
+
--hover: color-mix(in srgb, var(--muted) 70%, var(--card));
|
|
257
262
|
--destructive: oklch(0.577 0.245 27.325);
|
|
258
|
-
--border: oklch(0.9 0.01 150);
|
|
263
|
+
--border: oklch(0.9 0.01 150 / 60%);
|
|
259
264
|
--input: oklch(0.9 0.01 150);
|
|
260
265
|
--ring: oklch(0.55 0.1 150);
|
|
261
266
|
--chart-1: oklch(0.55 0.13 150);
|
|
@@ -265,10 +270,10 @@ The steps below add a preset with the id `forest`.
|
|
|
265
270
|
--chart-5: oklch(0.8 0.12 90);
|
|
266
271
|
--sidebar: var(--card);
|
|
267
272
|
--sidebar-foreground: var(--card-foreground);
|
|
268
|
-
--sidebar-primary: color-mix(in
|
|
273
|
+
--sidebar-primary: color-mix(in srgb, var(--primary) 8%, var(--sidebar));
|
|
269
274
|
--sidebar-primary-foreground: var(--primary);
|
|
270
|
-
--sidebar-accent: var(--
|
|
271
|
-
--sidebar-accent-foreground: var(--foreground);
|
|
275
|
+
--sidebar-accent: var(--hover);
|
|
276
|
+
--sidebar-accent-foreground: var(--sidebar-foreground);
|
|
272
277
|
--sidebar-border: var(--border);
|
|
273
278
|
--sidebar-ring: var(--ring);
|
|
274
279
|
}
|
|
@@ -289,6 +294,7 @@ The steps below add a preset with the id `forest`.
|
|
|
289
294
|
--muted-foreground: oklch(0.7 0.02 150);
|
|
290
295
|
--accent: oklch(0.3 0.04 140);
|
|
291
296
|
--accent-foreground: oklch(0.97 0.005 150);
|
|
297
|
+
--hover: color-mix(in srgb, var(--muted) 70%, var(--card));
|
|
292
298
|
--destructive: oklch(0.704 0.191 22.216);
|
|
293
299
|
--border: oklch(1 0 0 / 10%);
|
|
294
300
|
--input: oklch(1 0 0 / 15%);
|
|
@@ -300,10 +306,10 @@ The steps below add a preset with the id `forest`.
|
|
|
300
306
|
--chart-5: oklch(0.82 0.12 90);
|
|
301
307
|
--sidebar: var(--card);
|
|
302
308
|
--sidebar-foreground: var(--card-foreground);
|
|
303
|
-
--sidebar-primary: color-mix(in
|
|
309
|
+
--sidebar-primary: color-mix(in srgb, var(--primary) 8%, var(--sidebar));
|
|
304
310
|
--sidebar-primary-foreground: var(--primary);
|
|
305
|
-
--sidebar-accent: var(--
|
|
306
|
-
--sidebar-accent-foreground: var(--foreground);
|
|
311
|
+
--sidebar-accent: var(--hover);
|
|
312
|
+
--sidebar-accent-foreground: var(--sidebar-foreground);
|
|
307
313
|
--sidebar-border: var(--border);
|
|
308
314
|
--sidebar-ring: var(--ring);
|
|
309
315
|
}
|
|
@@ -426,7 +432,7 @@ Run the theme tests:
|
|
|
426
432
|
pnpm exec vitest run tests/logic/theme-tokens.test.ts tests/logic/theme-preferences.test.ts tests/logic/client-theme.test.tsx
|
|
427
433
|
```
|
|
428
434
|
|
|
429
|
-
- `theme-tokens.test.ts` checks that every registered preset defines all
|
|
435
|
+
- `theme-tokens.test.ts` checks that every registered preset defines all 32 colors and every non-color token in its light rule and every color in its dark rule, with the same declarations on the preview selectors; that Compact and Spacious differ only in dimensions, with Compact's spacing smaller; and, by compiling `client/styles.css` with Tailwind, that the color, font, size, line height, spacing, radius and shadow classes and the `body`, `h1` and `code` fonts still read the runtime variables.
|
|
430
436
|
- `theme-preferences.test.ts` checks that Compact is first, the storage keys for each base path, restoring both choices at startup without reading another application's keys, and the fallbacks for invalid values, removed presets and unavailable storage.
|
|
431
437
|
- `client-theme.test.tsx` checks the provider and the popover: labels in en-US and zh-CN, choosing and saving, configured defaults against saved choices, startup and provider agreeing, clearing and syncing across tabs, invalid values, and unavailable storage.
|
|
432
438
|
|
|
@@ -30,7 +30,7 @@ An agent's runs on one subject: a compact side-column log with a live timer, an
|
|
|
30
30
|
|
|
31
31
|
### agent-composer
|
|
32
32
|
|
|
33
|
-
The message box for talking to an agent: page-context chips inside it, files to send (attach, paste, drop, uploaded before sending), Enter to send, Stop while the agent works, and a toolbar slot for a
|
|
33
|
+
The message box for talking to an agent: page-context chips inside it, files to send (attach, paste, drop, uploaded before sending), Enter to send, Stop while the agent works, and a toolbar slot for a picker such as the agent's. Use it wherever a person writes to an agent. Presentational: context chips, drafts and focus come from the agents plugin's chat hooks (@nocobase/app-plugin-agents/client/chat) through optional props.
|
|
34
34
|
|
|
35
35
|
- Kind: component
|
|
36
36
|
- Install: `yes n | pnpm exec shadcn add @nocobase/agent-composer`
|
|
@@ -41,18 +41,18 @@ The message box for talking to an agent: page-context chips inside it, files to
|
|
|
41
41
|
|
|
42
42
|
### agent-picker
|
|
43
43
|
|
|
44
|
-
The one way to pick an agent: a trigger with the agent's avatar (availability dot on its corner) and name, and a menu of
|
|
44
|
+
The one way to pick an agent: a trigger with the agent's avatar (availability dot on its corner) and name, and a menu of every enabled agent with what it is good at, its default and "personal runners only" tags, and why one cannot answer the viewer now (it cannot be picked then). Two appearances: field, which looks like a form's select, for forms and settings; toolbar, compact, for a composer. Presentational: pass ChatAgent records from @nocobase/app-plugin-agents/shared/conversations.
|
|
45
45
|
|
|
46
46
|
- Kind: component
|
|
47
47
|
- Install: `yes n | pnpm exec shadcn add @nocobase/agent-picker`
|
|
48
48
|
- Installs to: `client/components/agent-picker.tsx`
|
|
49
49
|
- Plugin dependencies: `@nocobase/app-plugin-agents`
|
|
50
50
|
- Example: `@nocobase/agent-picker-demo` (`pnpm exec shadcn view @nocobase/agent-picker-demo`)
|
|
51
|
-
- After installing: Pass the agents (useChatAgents from @nocobase/app-plugin-agents/client/chat for chat, or useAgentOptions().agents from @nocobase/app-plugin-agents/client/kit for a form), value and onSelect. appearance is field by default (
|
|
51
|
+
- After installing: Pass the agents (useChatAgents from @nocobase/app-plugin-agents/client/chat for chat, or useAgentOptions().agents from @nocobase/app-plugin-agents/client/kit for a form), value and onSelect. appearance is field by default (noneOption offers no agent, placeholder, disabled, id for a label); appearance='toolbar' fits a composer, and bound marks an existing conversation, whose agent cannot change. Also exports AgentIdentity (avatar, dot and name as one row, for a picker that lists agents among people), AvailabilityDot, AgentTags and AgentTag. Every word comes from the labels prop, English by default.
|
|
52
52
|
|
|
53
53
|
### agent-chat
|
|
54
54
|
|
|
55
|
-
The agents' chat: a side panel beside the content area with the conversation, live steps, a composer with page-context chips and files to send (attach, paste, drop),
|
|
55
|
+
The agents' chat: a side panel beside the content area with the conversation, live steps, a composer with page-context chips and files to send (attach, paste, drop), the agent picker, the history, a full-page conversation view, and header, floating and Ask agent launchers. Use it to let people talk to agents from any page. Wired to the headless hooks of @nocobase/app-plugin-agents/client/chat.
|
|
56
56
|
|
|
57
57
|
- Kind: block
|
|
58
58
|
- Install: `yes n | pnpm exec shadcn add @nocobase/agent-chat`
|
|
@@ -169,6 +169,17 @@ Markdown rendered as compact prose for descriptions and comments, with mention c
|
|
|
169
169
|
- Example: `@nocobase/markdown-view-demo` (`pnpm exec shadcn view @nocobase/markdown-view-demo`)
|
|
170
170
|
- After installing: Pass the Markdown as content. renderCodeBlock draws a fenced block itself, such as a mermaid diagram; mentionIcon picks a mention chip's icon by its kind. remarkCjkAutolink ends a bare URL at CJK text or full-width punctuation; add it after remark-gfm wherever else you render the same Markdown.
|
|
171
171
|
|
|
172
|
+
### long-text
|
|
173
|
+
|
|
174
|
+
A long text shown in part, the last line fading out instead of an ellipsis. LongText is for where there is room, such as the description under a page's title or a comment: five lines that unfold in place on a click. LongTextPreview is for a narrow column, such as a record's introduction or address beside its page: three muted lines whose whole text opens in a pop-up, so the column never grows. Neither reacts unless the text overflows.
|
|
175
|
+
|
|
176
|
+
- Kind: component
|
|
177
|
+
- Install: `yes n | pnpm exec shadcn add @nocobase/long-text`
|
|
178
|
+
- Installs to: `client/components/long-text.tsx`
|
|
179
|
+
- Plugin dependencies: none
|
|
180
|
+
- Example: `@nocobase/long-text-demo` (`pnpm exec shadcn view @nocobase/long-text-demo`)
|
|
181
|
+
- After installing: Pass the text as children; a string keeps its line breaks, and rendered content such as MarkdownView works too. LongTextPreview needs a label, the heading of the pop-up that shows the text whole.
|
|
182
|
+
|
|
172
183
|
### comment-thread
|
|
173
184
|
|
|
174
185
|
A record's activity line: comment threads with reactions, reply, edit, delete and resolve, the consumer's own entries between them, and a composer with modes and files. Use it for a record's discussion, such as an issue's comments from @nocobase/app-plugin-projects.
|
|
@@ -196,14 +207,15 @@ Files on a record or a message: image thumbnails and file chips with download, t
|
|
|
196
207
|
|
|
197
208
|
### property-fields
|
|
198
209
|
|
|
199
|
-
The fields of a record's property card: the titled card, label and value rows, a select, chips with creation, a date, a number, a person as a value, and a row of avatars. Use it for the side column of a detail page.
|
|
210
|
+
The fields of a record's property card: the titled card, label and value rows, a select, chips with creation, a date, a number, a line of text, a long text, a link, a person as a value, and a row of avatars. Use it for the side column of a detail page. PropertyCard draws its fields one of two ways: variant form shows every value in its control, and variant inline reads first, each value plain text that a double-click, Enter or F2 edits, shaded under the pointer, with a copy button on hover; a long text opens whole on a click, and a link, which a click opens, is edited from a pencil.
|
|
200
211
|
|
|
201
212
|
- Kind: component
|
|
202
213
|
- Install: `yes n | pnpm exec shadcn add @nocobase/property-fields`
|
|
203
214
|
- Installs to: `client/components/property-fields.tsx`
|
|
204
215
|
- Plugin dependencies: none
|
|
216
|
+
- Also installs: `@nocobase/long-text`
|
|
205
217
|
- Example: `@nocobase/property-fields-demo` (`pnpm exec shadcn view @nocobase/property-fields-demo`)
|
|
206
|
-
- After installing: Values in, changes out: each field reports a change through onChange. Pass PropertyFieldLabels built from your locale resources for the words the fields show themselves.
|
|
218
|
+
- After installing: Values in, changes out: each field reports a change through onChange. Pass PropertyFieldLabels built from your locale resources for the words the fields show themselves. Set variant='inline' on PropertyCard for the read-first card, and give each field an aria-label, its name while it shows as text.
|
|
207
219
|
|
|
208
220
|
### rich-text-editor
|
|
209
221
|
|
|
@@ -328,7 +340,7 @@ One issue, compact: identifier, title, status in its workflow colour, priority,
|
|
|
328
340
|
|
|
329
341
|
### issue-detail
|
|
330
342
|
|
|
331
|
-
An issue's page as presentational parts: the two-column frame of cards on the page background, the header and description opening the body card, an add bar under it, the secondary parts (
|
|
343
|
+
An issue's page as presentational parts: the two-column frame of cards on the page background, the header and description opening the body card, an add bar under it, the secondary parts (sub-issues, dependencies with an issue search, files) as sections sharing one heading pattern and hidden while empty, files dropped or pasted on the body, and the side column over property-fields. Use it for an issue detail page over the hooks of @nocobase/app-plugin-projects/client/issues.
|
|
332
344
|
|
|
333
345
|
- Kind: block
|
|
334
346
|
- Install: `yes n | pnpm exec shadcn add @nocobase/issue-detail`
|
|
@@ -42,6 +42,8 @@ These are this application's UI design guidelines: foundations, page structure,
|
|
|
42
42
|
|
|
43
43
|
**L7 [Must] The primary action appears in exactly one place**: while a list is empty it is only inside the empty state (S2); once the list has rows it is only in the page header. Decide from loaded data, so the header shows no action while the list loads rather than one that disappears. A search or filter that matches nothing is not an empty list (S3): the header keeps its action. A primary action that opens a `DropdownMenu` aligns the menu with its trigger, `align='end'` in the header and `align='center'` in the empty state; each item is an icon and a name on one line with the `DropdownMenuItem` defaults, no sub-label.
|
|
44
44
|
|
|
45
|
+
**L8 [Should] A count beside a menu entry is what waits on the viewer**: unread messages, requests to decide, work assigned to them and not yet done. Never a total of records ("Leads 18"), which the page itself shows. Zero shows nothing. Work under way the viewer may want to follow, such as runs in progress, is a live count with words of its own ("2 running"). One thing is counted in one place: an entry and a header button, such as the inbox button, do not both count the same items. See ["A count beside an entry" in `references/page.md`](references/page.md#a-count-beside-an-entry).
|
|
46
|
+
|
|
45
47
|
## T Page templates
|
|
46
48
|
|
|
47
49
|
### T1 List page: browse, find and manage one kind of record
|
|
@@ -68,6 +70,7 @@ Structure, top to bottom: PageHeader (primary action "New X") → toolbar (searc
|
|
|
68
70
|
- **T2.2 [Must]** The top of the drawer or detail page shows the record name. Actions on the record (edit, delete) sit in a fixed position at the top or the bottom, grouped together, not one on the left and one on the right.
|
|
69
71
|
- **T2.3 [Must]** The detail view can be opened directly by URL, and a refresh still shows the same record (see I6).
|
|
70
72
|
- **T2.4 [Must]** Fields are laid out in two columns, "label — value", and an empty value shows "—"; multi-line text keeps its line breaks; very long values (emails, URLs) may wrap and must not break the layout.
|
|
73
|
+
- **T2.5 [Should] Particulars read first and edit in place**: a record's particulars in the side column of its page, or in its drawer, use the UI Library `property-fields` card with `variant='inline'`: each value is plain text, shaded under the pointer when the user may change it, edited on a double-click (Enter or F2 from the keyboard) and saved on the pick or when it loses focus, Escape leaving it as it was. A single click never enters editing, so a value can be selected and copied. A value people copy — an email, a phone number, an address, a website — gets a copy button on hover (`copyable`). A long text opens beside the column in a pop-up on a click and is edited there with a double-click, so the column keeps its height; a link, which a click opens, is edited from a pencil shown on hover, so following it never starts an edit. A value the user may not change is plain text, with no shading and no pencil. A form filled in at once, such as a create dialog, keeps every value in its control (the card's default `variant='form'`, or T3).
|
|
71
74
|
|
|
72
75
|
### T3 Form: create and edit
|
|
73
76
|
|
|
@@ -152,6 +155,8 @@ Do not show raw backend error messages (untranslated exception messages, stack t
|
|
|
152
155
|
|
|
153
156
|
**I13 [Must] Menus on icon triggers size to their items**: the shadcn `DropdownMenuContent` defaults to its trigger's width, so the menu of an icon button (a row's "…", a card's "More") is as narrow as the icon and wraps every item. Every `DropdownMenuContent` whose trigger is an icon button, or any trigger narrower than its items, gets `className='w-auto min-w-40'`: as wide as its longest item, and never narrower than `min-w-40`. Keep the class on the call site rather than in a wrapper component, beside positioning props such as `align='end'`. A menu whose trigger is at least as wide as its items, such as a labelled button, keeps the default.
|
|
154
157
|
|
|
158
|
+
**I14 [Must] Long text shows in part, by where it sits**: a description, an introduction, a note or a comment never ends in an ellipsis mid-sentence, and never pushes a narrow column longer than its neighbours. Where there is room, such as the description under a page's title or a comment in a timeline, show up to five lines and unfold the rest in place on a click (`LongText`). In a narrow column, such as a record's particulars beside its page or a card, show up to three muted lines and open the whole text in a pop-up beside it (`LongTextPreview`), so the column keeps its height. The last line fades out, and a text that fits is shown plainly, with nothing to click. Both come from the UI Library item `@nocobase/long-text` ([`references/ui-library.md`](references/ui-library.md)). A table cell or a list item's one-line summary keeps `truncate` or `line-clamp-1`, where the row opens the record.
|
|
159
|
+
|
|
155
160
|
## R Data freshness
|
|
156
161
|
|
|
157
162
|
**R1 [Must] Never write from stale data**: edit, delete and similar actions work from the record's latest data (see T3.8). Take particular care when the backend replaces fields wholesale; otherwise the write overwrites changes that someone else, or the same user, just made.
|
|
@@ -200,7 +205,7 @@ The design review and the acceptance review both go through this checklist item
|
|
|
200
205
|
|
|
201
206
|
- [ ] The page template and overlay choices are correct, and stacking follows the rules (T1–T5, I1)
|
|
202
207
|
- [ ] Page structure: PageContainer, PageHeader, one primary button per view, actions in the right places, a back button on a page below another one, which returns to that other page with its search and filters unchanged, and the primary action in exactly one place: the empty state while the list is empty, the header once it has rows (L1, L2, L5, L6, L7)
|
|
203
|
-
- [ ] Navigation is consistent: entries in one group all carry an icon or none does,
|
|
208
|
+
- [ ] Navigation is consistent: entries in one group all carry an icon or none does, a group's own icon does not repeat its first child's, and a count beside an entry is only what waits on the viewer (`page.md` §6, L8)
|
|
204
209
|
- [ ] All states are covered: loading, empty, no results, load failed, submitting, a block the user may not see; whether a failure offers a retry follows S4 (S1–S6)
|
|
205
210
|
- [ ] List: search placeholder, filters and clearing them, first column, enum Badges, row actions, formatting, date and number columns sortable, all four states, result cap notice, a cut-off cell ending in an ellipsis with its full content on hover (T1.1–T1.6, T1.8–T1.11)
|
|
206
211
|
- [ ] Detail view: drawer or page, record name and grouped actions, opens by URL, label–value layout with "—" for empty values (T2.1–T2.4)
|
|
@@ -213,6 +218,8 @@ The design review and the acceptance review both go through this checklist item
|
|
|
213
218
|
- [ ] Overlays and their state have URLs; every record and overlay opens over the view the user is on — a filtered list, a dashboard, a board, a drawer, the tab being shown — at that view's URL plus its own segments, and closing returns to exactly that URL, checked from a view other than the first one too: a tab other than the default, a list with a filter applied (I6, I9)
|
|
214
219
|
- [ ] Each overlay has the component, width and structure I1 gives what it holds, confirmations are AlertDialogs, and a dialog that can outgrow the screen caps its height at `calc(100dvh-2rem)` with a fixed footer and a scrolling body (I1)
|
|
215
220
|
- [ ] Dates are picked from a Calendar in a Popover, never a native date input, and a range has presets; a drawer holding a form or details is medium width; select popups grow with their options and wrap long ones; menus on icon triggers size to their items (I10–I13)
|
|
221
|
+
- [ ] A record's particulars read as text and edit on a double-click, with copy on hover and a pencil for links (T2.5)
|
|
222
|
+
- [ ] Long text fades after five lines and unfolds in place where there is room, and after three muted lines opening in a pop-up in a narrow column, never an ellipsis mid-sentence (I14)
|
|
216
223
|
- [ ] Actions without permission are hidden and unavailable ones disabled with a reason; everything works with the keyboard (I7, I8)
|
|
217
224
|
- [ ] Color, font size, spacing, radius and icons use only tokens, scales and lucide-react, and fixed sizes are explained (F1–F5, F7)
|
|
218
225
|
- [ ] Copy exists in every language `client/locales/index.ts` offers, wording is consistent, and button and title copy follows the rules (C1–C4, C6, C7)
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Configurable lifecycle parameters
|
|
2
|
+
|
|
3
|
+
Use this when administrators need to adjust approval departments, reviewers, thresholds, reopening windows or other business values while developers keep the workflow in source. Read [record lifecycles](lifecycle.md) first. This capability belongs to `@nocobase/lifecycle`; verify that the installed package exports `StoredLifecycleParameters` and `normalizeReviewerSelections` before using it. An older installation needs a compatible release upgrade rather than invented APIs.
|
|
4
|
+
|
|
5
|
+
## Code declaration and storage
|
|
6
|
+
|
|
7
|
+
Declare defaults in `parameters` and a code-owned `parameterConfiguration` with groups. Every group has key, title, schemaVersion and fields; every field has type, title and a parse function returning its complete normalized JSON value. Optional field bindings name a state or transition. The flow declares readMode and snapshotTransition, and individual fields can override readMode. Groups can declare a validate function and sameReadMode arrays for joint invariants.
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
import { StoredLifecycleParameters, type ParameterGroup } from '@nocobase/lifecycle';
|
|
11
|
+
import { z } from 'zod';
|
|
12
|
+
|
|
13
|
+
const thresholds: ParameterGroup = {
|
|
14
|
+
key: 'approvalThresholds', title: 'Approval thresholds', schemaVersion: 1,
|
|
15
|
+
fields: {
|
|
16
|
+
automaticLimit: {
|
|
17
|
+
type: 'number', title: 'Automatic approval limit',
|
|
18
|
+
parse: (value) => z.number().finite().nonnegative().parse(value),
|
|
19
|
+
bindings: [{ transition: 'submit' }],
|
|
20
|
+
},
|
|
21
|
+
financeLimit: {
|
|
22
|
+
type: 'number', title: 'Finance review limit',
|
|
23
|
+
parse: (value) => z.number().finite().nonnegative().parse(value),
|
|
24
|
+
bindings: [{ state: 'financeReview' }],
|
|
25
|
+
},
|
|
26
|
+
},
|
|
27
|
+
sameReadMode: [['automaticLimit', 'financeLimit']],
|
|
28
|
+
validate: (values) => {
|
|
29
|
+
if (Number(values.automaticLimit) > Number(values.financeLimit))
|
|
30
|
+
throw new Error('Automatic approval cannot exceed the finance limit.');
|
|
31
|
+
},
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
// In the definition:
|
|
35
|
+
parameters: { automaticLimit: 500, financeLimit: 5000 },
|
|
36
|
+
parameterConfiguration: {
|
|
37
|
+
readMode: 'snapshot', snapshotTransition: 'submit', groups: [thresholds],
|
|
38
|
+
},
|
|
39
|
+
|
|
40
|
+
// Register on the application's existing lifecycle runtime:
|
|
41
|
+
runtime.register(expenseLifecycle, {
|
|
42
|
+
parameterConfiguration: {
|
|
43
|
+
store: new StoredLifecycleParameters(lifecycleStore, collectionNames),
|
|
44
|
+
scope: ({ record }) => scopeFromAuthoritativeRecord(record),
|
|
45
|
+
legacyRecord: (record) => record.parameterContract !== 1,
|
|
46
|
+
snapshotRequired: (record) => record.status !== 'draft',
|
|
47
|
+
},
|
|
48
|
+
});
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Create six collections with an immutable migration, using application-owned names: heads (string id, scope, groupKey, status, integer revision; unique scope/groupKey); versions (string id, JSON payload, JSON selectionCounts); selections (string id, versionId, ruleKey, integer group, type, referenceId; index versionId); requests (string id, actorId, text fingerprint, integer revision); snapshots (string id, JSON payload); usages (string id, JSON payload, recordKey, zoned timestamp at; index recordKey/at/id). Pass names as `{ heads, versions, selections, requests, snapshots, usages }`. Existing LifecycleStore implementations are unchanged; custom parameter adapters implement the separate LifecycleParameterStore interface, including read/save/snapshot/saveSnapshot/usage/saveUsage/listUsage.
|
|
52
|
+
|
|
53
|
+
Resolve scope and record identity from server-owned context. Authenticate and authorize configuration read/write before validators or record lookup. In the save transaction validate referenced entities in that scope, then call `store.save({ scope, group, values, expectedRevision, requestId, actorId, at }, transactionHandle)`. Save exactly the complete declared group: never accept undeclared fields, schemaVersion, modes, workflow structure or client-provided effective values. A stale revision is a 409 configuration conflict; the same request and values replay its immutable version. Reused request IDs with different input fail. Only an absent configuration uses code defaults; read errors and incompatible schemas fail.
|
|
54
|
+
|
|
55
|
+
## Snapshot, live and execution consistency
|
|
56
|
+
|
|
57
|
+
Snapshot fixes all declared snapshot fields at the first successful formal submission, before routing, setters and hooks, in the business transaction. Draft preview writes nothing. Return, withdrawal and resubmission keep the original snapshot. Snapshot rules fix their choices, not organization membership. New snapshot fields missing from an old submitted record require a migration; never fabricate historical values using current settings. Define an explicit legacyRecord policy when introducing the contract to existing records, and use a version marker on newly created records.
|
|
58
|
+
|
|
59
|
+
Live reads current complete values for every execution, effect retry and continuation transition. A same-record execution shares one resolution through guard, execute, route, set, hooks and nested tx.fire calls; different records have independent resolutions. For business actions use `runtime.withParameterExecution(name, recordId, async (parameters, tx) => { ... }, { actionId, transaction })` after the application's action replay check. This helper writes an identified action's usage fact but does not deduplicate the business action. Query services in guards and callbacks must use tx.handle.
|
|
60
|
+
|
|
61
|
+
Use `runtime.view()` for record availability and effective parameterValues from one authoritative preview. Use `lifecycleDescriptionViewAsync(runtime, name, { record: null, purpose: 'preview', transactionHandle: undefined })` for an authorized current configuration description. Record-aware previews pass the authoritative record. Preview is informative; actual execution rechecks guards.
|
|
62
|
+
|
|
63
|
+
Transitions, identified actions and each effect attempt record actual values and per-field revision/schema/origin/mode. Effect facts persist before external execution and are fenced against the active attempt. `store.snapshot()`, `store.usage()` and `store.listUsage(scope, lifecycle, recordId)` expose history. Pruning effect runs preserves configuration facts. Display “Not recorded” for missing historical usage and show current effective values separately.
|
|
64
|
+
|
|
65
|
+
Do not change payment amounts, accounts or recipients through live configuration while retaining an effect run's idempotency key. Those identities come from persisted business facts. Simulated notification copy is a safe demonstration of fresh live values on retry. Trigger timeouts remain code-owned.
|
|
66
|
+
|
|
67
|
+
## Reviewer rules and task boundaries
|
|
68
|
+
|
|
69
|
+
Use `type: 'reviewers'`, parsed with `normalizeReviewerSelections(value, ['department', 'role', 'user'])`. Persist flat choices `{ group, type, referenceId }`, never arbitrary expression JSON or scripts. Same-group conditions intersect, separate groups union and deduplicate. Alternative people belong in separate groups.
|
|
70
|
+
|
|
71
|
+
Register selectors with `resolveReviewerSelections(choices, { scope, applicantId, transactionHandle }, { selectors, eligible })`. Each selector returns IDs for its code-declared reference type; eligible uniformly filters every result, including explicit users. Departments use exact membership unless code explicitly provides another named selector, roles respect scope, and inactive users and the applicant are filtered. Code determines a zero-candidate failure and the node's decision policy. Custom types may resolve positions, contextual department references or named queries without accepting arbitrary scripts.
|
|
72
|
+
|
|
73
|
+
On task creation resolve the snapshot or live rule against current organization data and persist candidates on the task. Existing candidates stay fixed. A single approver field is not a multi-person approval system. To demonstrate multiple candidates, declare a separate finite “any candidate can decide” workflow and use version checks so only one concurrent decision succeeds. Real approval plugins need their own compatibility verification for action replay, settings previews, task construction and opinion reuse; fixed current-round tasks or inherited opinions cannot stand in for rule configuration.
|
|
74
|
+
|
|
75
|
+
## Optional user interfaces
|
|
76
|
+
|
|
77
|
+
Respect the user's existing UI and scope. API-only work needs no configuration page or diagram. An existing settings page can embed a form. Offer a central page or optional bound diagram entry only when useful. Do not add a mandatory diagram or a second workflow-design system.
|
|
78
|
+
|
|
79
|
+
When building a page with configurable parameters tied to business process nodes, prefer an editing entry on the corresponding diagram node or transition. For example, clicking a finance-review node can open a dialog for its reviewer rules and approval threshold, so users can adjust those values in their process context. If the page already includes a diagram, incorporate this entry as part of the page design; if a diagram has not been requested, suggest this interaction when discussing the process interface. Parameters with no node or transition relationship can stay in an embedded form or settings page.
|
|
80
|
+
|
|
81
|
+
For save request IDs, follow the [browser request ID guidance](lifecycle.md#5-the-page): use an HTTP-compatible generator and retain the key for retries of the same save.
|
|
82
|
+
|
|
83
|
+
The example plugin exports `ParameterEditor`, `parameterApi` and `boundParameterGroups` from `@nocobase/app-plugin-lifecycle-example/client`. They illustrate a shared editor with an injected API, complete-version CAS saves, read-only mode and preserved drafts on conflicts. They are example exports, not an automatically installed platform settings service. Applications can implement the same contracts in their own UI.
|
|
84
|
+
|
|
85
|
+
For a working reference in the NocoBase source repository, inspect `packages/examples/app-plugin-lifecycle-example/client/pages/parameters.tsx` and `client/components/parameter-binding-editor.tsx` in the same package: `useParameterBindingEditor` connects diagram bindings to a dialog containing the shared `ParameterEditor` and refreshes the page after saving. Reuse the same editor and save contract for diagram and settings entries when both exist.
|
|
86
|
+
|
|
87
|
+
For click-to-edit diagrams, derive groups from description.parameterConfiguration.groups and bindings referencing the clicked state or transition name. One entry can bind several fields or groups. Intercept only bound entries; unbound entries retain the component's ordinary details. In the example, ProcessDiagram's onParameterBinding(kind, name) returns true when the shared editor handles the click. Clicking opens configuration and never fires a transition. Use the diagram component's actual node/edge callbacks rather than assuming an event API.
|
|
88
|
+
|
|
89
|
+
Show field titles, units, validation, read mode and effective timing. Snapshot changes affect new submissions; live changes affect subsequent executions/retries. Read-only viewers see disabled fields and no save control. On 409 keep draft inputs, fetch the current revision and values, then require a deliberate retry against that revision. Label an editor opened from history as current configuration; never rewrite an old snapshot, actual usage fact or candidate list.
|
|
90
|
+
|
|
91
|
+
## Validate the integration
|
|
92
|
+
|
|
93
|
+
Test complete schemas and cross-field constraints, CAS/replay, reference scope and authorization before validation. Prove draft previews create no facts, first submission freezes every snapshot field, failed transactions/savepoints remove it, resubmission retains it, and missing historical fields fail. Check same-record actions/nested transitions share values while different records do not. Prove fresh live retries preserve business idempotency and record each attempt's facts.
|
|
94
|
+
|
|
95
|
+
Exercise reviewer intersections/unions, duplicate and inactive/applicant filtering, changed department choices, changed organization membership and fixed existing candidates. Test simultaneous decisions. For chosen UI entry points verify shared save behavior, read-only rendering, preserved conflict drafts, multi-field bindings, untouched unbound entries and distinct current/history labels in the running application. Use the normal testing helpers and run skills sync after installation so this reference is reachable from the normal Skill entry.
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Use `@nocobase/lifecycle` when a business record moves through stages that developers define in source: an expense report, a ticket, a contract, an order, a leave request. The record keeps its state in one of its own fields, every change is a transition declared in a definition, and the work a transition owes outside the database — mail, payments, calls to other systems — runs as effects after the transaction commits. There is no separate process instance, so the state is never kept in two places.
|
|
4
4
|
|
|
5
|
+
Administrators can adjust code-declared business parameters without editing workflow structure. For configurable approval departments, reviewer choices, thresholds, snapshot/live reads and optional configuration editors, read [configurable lifecycle parameters](lifecycle-parameters.md).
|
|
6
|
+
|
|
5
7
|
## Choose it or something else
|
|
6
8
|
|
|
7
9
|
| The requirement | Use |
|
|
@@ -14,6 +16,12 @@ Use `@nocobase/lifecycle` when a business record moves through stages that devel
|
|
|
14
16
|
|
|
15
17
|
A parent and its children can each have a lifecycle and point at each other by foreign key, such as a document and the tasks it distributes; a child's last transition can move the parent on in the same transaction.
|
|
16
18
|
|
|
19
|
+
## Ask about the process UI
|
|
20
|
+
|
|
21
|
+
When developing a lifecycle, ask whether the user wants to display a flowchart or a related process interface, unless they have already stated their preference. For example, ask in the user's language: “Would you like this process to include a flowchart or a process interface showing its current state, available actions and history? If yes, we can render it with the flow diagram components from our UI Library.”
|
|
22
|
+
|
|
23
|
+
If the user chooses yes, use the UI Library's `@nocobase/lifecycle-diagram` to render the lifecycle definition and record progress; `@nocobase/flow-diagram` is available for generic process graphs. Follow [the diagram integration guidance](#draw-an-interactive-lifecycle-diagram) and [the frontend workflow](frontend/ui-workflow.md) for the surrounding process interface. Respect separate preferences: a user may want state, action buttons and history without a diagram. If they decline both a diagram and a process interface, continue implementing the lifecycle without adding either.
|
|
24
|
+
|
|
17
25
|
## Rules that are never broken
|
|
18
26
|
|
|
19
27
|
1. **The state lives only in the record's own field.** Query, filter and count on it like any other column; keep no copy elsewhere.
|
|
@@ -376,6 +384,8 @@ return view.available.map((transition) => (
|
|
|
376
384
|
|
|
377
385
|
Render the buttons from `view.available`, never from a hard-coded state check, so the page and the server use the same judgement. Translate titles and blocker messages by their stable `name` and `code`, as every user-visible string goes through a translation key. `fire` sends a fresh `requestId` and the version on screen; on `CONFLICT` tell the person the record changed and reload rather than retrying. On `INVALID_INPUT`, mark the fields in `error.problems`. The hook refreshes every 4 seconds by default; `refreshMs` changes it. Follow [the frontend workflow](frontend/ui-workflow.md) for the page itself.
|
|
378
386
|
|
|
387
|
+
For browser request IDs, prefer the built-in lifecycle client, which already handles environments without `crypto.randomUUID()`. Custom submissions and parameter saves must not call it unconditionally: it requires a secure context and can be unavailable on HTTP test hosts. Use a shared helper that falls back to `crypto.getRandomValues(new Uint8Array(16))`, encoded as hex, or an existing HTTP-compatible ID utility. Generate one key per logical operation and reuse it with the same payload for transport retries; changed input or a new decision needs a new key. Verify submission with `randomUUID` unavailable, not only on localhost or HTTPS.
|
|
388
|
+
|
|
379
389
|
## 6. Tests
|
|
380
390
|
|
|
381
391
|
Unit-test the definition with the test kit — a memory store, a fake clock and in-process effects — so waits, retries and refusals need no database:
|
|
@@ -429,10 +439,21 @@ The installed package's README lists its entries; the full guide, design notes a
|
|
|
429
439
|
|
|
430
440
|
## Draw an interactive lifecycle diagram
|
|
431
441
|
|
|
442
|
+
When building a process page whose configurable business parameters relate to nodes or transitions, prefer an entry on the corresponding diagram element that opens a parameter-editing dialog. Map the clicked state's or transition's stable name through code-declared parameter bindings and open the same editor used by the settings page or embedded form, if present. A bound entry can expose several groups; unbound entries keep their ordinary details. Read [configurable lifecycle parameters](lifecycle-parameters.md#optional-user-interfaces) for the working example, authorization, CAS conflicts and current-versus-historical values.
|
|
443
|
+
|
|
432
444
|
When a page needs a lifecycle diagram, use the UI Library's `@nocobase/lifecycle-diagram` component (React Flow + ELK) instead of building a canvas or turning Mermaid source into an interactive view. Read `pnpm exec shadcn view @nocobase/lifecycle-diagram-demo`, then install with `yes n | pnpm exec shadcn add @nocobase/lifecycle-diagram` and format the created files. It includes `@nocobase/flow-diagram`, which is also available alone for a generic directed graph. Follow [the UI Library guidance](frontend/references/styling.md#3-use-shadcn) and its [offline catalog](frontend/references/ui-library.md) for discovery and installation.
|
|
433
445
|
|
|
434
446
|
Import `LifecycleDiagram` from `#components/lifecycle-diagram`. Pass the hook's `description.description`, an `ariaLabel`, `currentState: view.record.status` (use the lifecycle's own state field), and `availableTransitions: view.available.filter((item) => item.allowed).map((item) => item.name)`. Translate labels by stable state/transition names with `stateLabel` and `transitionLabel`; add the shared `flowDiagram` keys to your locale resources. Use `onStateClick` and `onTransitionClick` to open details, including effects, triggers and continuations from the description. Definitions remain in source and clicking the diagram never fires a transition; action buttons still follow `view.available`. Pass `history={view.history.transitions}` for visited paths; the component matches the exact transition, source and destination, including retries. `visitedStates` supplements node highlights only; never infer a traversed edge from the current state or visited endpoints. Pass a translated `endLabel` to display a separate decorative end marker after each explicit final state, without treating every state lacking outgoing transitions as final. Keep `toMermaid()` for documentation and export.
|
|
435
447
|
|
|
436
448
|
For detailed page diagrams, prefer `direction="DOWN" autoHeight`: the canvas grows with the full layout, including outer routes and labels. A wide graph fitted into a short fixed-height panel makes its labels unreadable. Check the actual lifecycle definition in the target page, rather than judging a simple preview alone.
|
|
437
449
|
|
|
450
|
+
The label callbacks receive description objects, not name strings. Read `state.name` in `stateLabel` and `transition.name` in `transitionLabel` when building translation keys:
|
|
451
|
+
|
|
452
|
+
```tsx
|
|
453
|
+
stateLabel={(state) => t(`leaves.states.${state.name}`)}
|
|
454
|
+
transitionLabel={(transition) => t(`leaves.transitions.${transition.name}`)}
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
Adapt the translation key prefix to the feature.
|
|
458
|
+
|
|
438
459
|
Preserve the component’s application theme tokens: `--primary` for current, visited and available highlights, subdued neutral strokes for other edges, and card/foreground/border tokens for the canvas and labels. Current nodes have a stronger fill and ring, visited nodes a light fill, with no extra “visited” label. Labels stay on the routes; automatic transitions remain solid and may show `⚙` through `transitionLabel`. Do not introduce a separate palette or hard-coded accent color. Check light/dark themes and a changed application primary color when customizing the rendering.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Plugins in an application
|
|
2
|
+
|
|
3
|
+
Read this before registering, updating, customizing or removing a plugin, and before building a feature an installed plugin may already provide.
|
|
4
|
+
|
|
5
|
+
## Read a plugin's Skill before building what it already does
|
|
6
|
+
|
|
7
|
+
**You are not starting from scratch.** This application ships with NocoBase packages that already solve whole categories of requirement, and packages may publish a Skill explaining how to use them. `pnpm nocobase skills sync` copies Skills from direct `@nocobase/*` dependencies and registered plugins into `.agents/skills/`. Before implementing a feature, check whether an installed and registered plugin already covers it:
|
|
8
|
+
|
|
9
|
+
| The requirement sounds like | Read the Skill for |
|
|
10
|
+
| -------------------------------------------------------------------------------------------- | ------------------------------------- |
|
|
11
|
+
| Email, IM, or in-app messages; notifying someone that something happened | `@nocobase/app-plugin-notification` |
|
|
12
|
+
| Roles, permissions, "user A may only see their own records", field-level or row-level access | `@nocobase/app-plugin-authorization` |
|
|
13
|
+
| Sign-in, registration, sessions, password reset | `@nocobase/app-plugin-authentication` |
|
|
14
|
+
| User listing, account state, password reset, and application-owned role assignment | `@nocobase/app-plugin-users` |
|
|
15
|
+
| File upload and metadata through Repository | `@nocobase/app-plugin-file` |
|
|
16
|
+
| Translated text and language switching | `@nocobase/app-plugin-i18n` |
|
|
17
|
+
|
|
18
|
+
Run `pnpm nocobase skills sync` if `.agents/skills/` is missing or looks out of date, then read the Skill for the plugin you need. It documents that plugin's public entries, the ownership boundary, and how to verify the result — which is faster and more correct than inferring an API from its source.
|
|
19
|
+
|
|
20
|
+
Building a permission system, a notification sender, or a job scheduler by hand when a registered plugin already provides one is the most expensive mistake available here. Prefer the plugin; write your own only when you have read its Skill and confirmed it genuinely does not fit.
|
|
21
|
+
|
|
22
|
+
`.agents/skills/` is generated output: gitignored, and every synchronized package-owned directory is replaced wholesale on the next sync, so never edit a file there. The same sync mirrors each synchronized directory into `.claude/skills/` as a symbolic link, because Claude Code discovers skills only there; that mirror is generated and gitignored too. Put application-specific guidance in the application's committed `.agents/rules/`, linked from its `AGENTS.md`.
|
|
23
|
+
|
|
24
|
+
## The composition roots
|
|
25
|
+
|
|
26
|
+
Plugins are registered in `client/plugins.ts`, `server/plugins.ts`, and `cli/plugins.ts`. Presence in the array enables a plugin and array order is contribution order. A plugin appears in the roots matching what it ships, so a plugin with only commands is listed in `cli/plugins.ts` alone. Bulk Skills synchronization and plugin updates discover plugins from these composition roots.
|
|
27
|
+
|
|
28
|
+
Skills synchronization reads direct `@nocobase/*` dependencies from the application manifest and retains compatibility with explicitly registered plugins. It does not make an unregistered runtime plugin active; the composition roots remain the authority for registration and contribution order.
|
|
29
|
+
|
|
30
|
+
Let `pnpm nocobase plugin register` and `pnpm nocobase plugin unregister` add and remove entries. Edit these files by hand only to reorder entries or to pass a plugin its options.
|
|
31
|
+
|
|
32
|
+
## Installing and updating
|
|
33
|
+
|
|
34
|
+
Install plugins with `pnpm nocobase plugin register <name>`. All application plugins belong in `dependencies`, including client-only and disabled plugins, because deployment dependencies come from that field. Plugin frontend libraries remain peers and are not automatically installed in the deployment. Re-registering migrates legacy `devDependencies` entries while preserving the declared range; verify the manifest and lockfile afterward. With an older CLI, use `pnpm add --save-prod <package>@<declared-range>` to correct the declaration; `--no-install` leaves lockfile synchronization to the caller.
|
|
35
|
+
|
|
36
|
+
To update a registered plugin, use `pnpm nocobase plugin update @nocobase/app-plugin-authentication`, or omit the name to update all registered plugins. Prefer the full package name; `authentication` is also accepted as a short name. The name is a positional argument, not `--plugin`. Use `--dry-run` to preview. With pnpm, updates stay within declared version ranges; after a successful update, all registered plugin Skills are re-synchronized. See the Plugins section of the application's `README.MD` for version-range behavior and examples.
|
|
37
|
+
|
|
38
|
+
## Customizing a page a plugin owns
|
|
39
|
+
|
|
40
|
+
To customize a page a plugin owns, pass an option on its registration, add a source extension under `client/extensions/*/extension.ts`, or add an entry to `client/route-overrides.ts`. Do not redeclare the plugin's route — a duplicate `/install` is a conflict, not a customization. An override replaces only `componentLoader`; route identity, path, and auth mode stay with the plugin. One route takes one override across all three mechanisms. Route overrides must stay lazy, declare a `componentEntry`, and load a default-exported component. See section 10 of [pages and routes](frontend/references/page.md).
|
|
41
|
+
|
|
42
|
+
Authentication pages are not plugin-owned: `/login`, `/register`, `/forgot-password`, and `/reset-password` are application routes declared in `client/routes.ts`. Authentication pages in `client/pages/auth/` use relative links and the authentication plugin's `client/actions` hooks; do not call authentication endpoints directly or create a second session store.
|
|
43
|
+
|
|
44
|
+
## Removing a direct NocoBase package
|
|
45
|
+
|
|
46
|
+
Before removing an `@nocobase/*` dependency, search the application's imports, Client/Server/CLI plugin registrations, routes, services, configuration, tests, and build scripts for the package name and the contracts it provides. Migrate or remove those references first. `package remove` updates dependency metadata and generated Skills; it does not rewrite application code or configuration and cannot decide whether the capability is still needed, so never use it to remove a capability the application still needs.
|
|
47
|
+
|
|
48
|
+
Run `pnpm nocobase package remove @nocobase/example`. The command uses the application's package manager to update `package.json` and the lockfile, then removes only synchronized Skills recorded as owned by that package. An `@nocobase/app-plugin-*` target delegates to the plugin unregister workflow so its Client, Server, and CLI registrations are removed together; `pnpm nocobase plugin unregister <name>` remains available. Use `--dry-run` before a consequential removal and `--json` when structured output is needed.
|
|
49
|
+
|
|
50
|
+
After an interrupted or manual removal, verify that the manifest no longer declares the package and run a full `pnpm nocobase skills sync` to reconcile stale package-owned output. Passing an already-absent package to `package remove` cleans recorded historical Skill ownership without uninstalling or cleaning another package.
|
|
@@ -234,7 +234,7 @@ See the `@nocobase/queue` README for the full contract.
|
|
|
234
234
|
|
|
235
235
|
### Application code configuration
|
|
236
236
|
|
|
237
|
-
Each file under `server/config/` defines one section with `defineAppConfig` from `@nocobase/app-server/config`. `server/config/index.ts` imports those sections and exports `defaultAppConfigs({ auth })`. The client uses the same helpers from `@nocobase/app-client`, in their function form only.
|
|
237
|
+
Each file under `server/config/` defines one section with `defineAppConfig` from `@nocobase/app-server/config`. `server/config/index.ts` imports those sections and exports `defaultAppConfigs({ auth })`. The client uses the same helpers from `@nocobase/app-client`, in their function form only. Providers and routes read this typed configuration rather than `process.env`.
|
|
238
238
|
|
|
239
239
|
On the server, `defineAppConfig((runtime) => options)` declares defaults alone. The object form adds rules:
|
|
240
240
|
|
|
@@ -108,15 +108,19 @@ Unregistering a plugin leaves its records and migration history intact. Do not r
|
|
|
108
108
|
|
|
109
109
|
## Documentation and generated directories
|
|
110
110
|
|
|
111
|
-
`AGENTS.md`, `CLAUDE.md`,
|
|
111
|
+
`AGENTS.md`, `CLAUDE.md`, `README.MD`, and the files under `.agents/rules/` ship with the template and may contain user additions. Take the template's version where the user wrote nothing and merge where they did. `.agents/rules/` is committed and application-owned: merge each file the target changes, keep every rules file the user added, and never replace the directory wholesale.
|
|
112
112
|
|
|
113
|
-
|
|
113
|
+
`AGENTS.md` is a small always-on index of at most 32 KB that links to `.agents/rules/` and the synchronized Skills. When TARGET ships that index form and the project still has an older, long `AGENTS.md` with user edits, take TARGET's index and keep the user's application-specific additions by moving each into the matching `.agents/rules/<topic>.md`, or a new one linked from the index, rather than appending them to `AGENTS.md`. Show the user where each addition went.
|
|
114
|
+
|
|
115
|
+
An application generated before templates shipped `.agents/rules/` ignores `/.agents/` wholesale in `.gitignore`, which keeps the rules out of version control. Replace that line with `/.agents/*` followed by `!/.agents/rules/`, keep `/.claude/skills/` ignored, and confirm with `git check-ignore -v .agents/rules/<file>` that a rules file is no longer ignored.
|
|
116
|
+
|
|
117
|
+
Older template releases also shipped a committed `skills/` directory. A target release that moves those Skills into `@nocobase/app-skills` does not authorize deleting local changes. Compare each legacy file with the BASE template: an unchanged template copy may be removed only after install and `pnpm nocobase skills sync` produce the corresponding package-owned Skill under `.agents/skills/`; a modified or added file is application-owned and must be preserved. Keep a customized legacy directory with explicit links from `AGENTS.md`, or move its rules into `.agents/rules/` or another committed application-owned source after showing the user the exact relocation. Never silently fold custom content into a generated copy.
|
|
114
118
|
|
|
115
119
|
Older releases may include `MIGRATION.md`. Treat it as historical context and verify each suggestion against BASE → TARGET and the project's state; never remove a capability that TARGET still provides solely because an old note says to. When TARGET removes the document, delete an unchanged template copy, but preserve or relocate the user's own operational notes before removing a customized copy.
|
|
116
120
|
|
|
117
121
|
`.mcp.json`, `.cursor/mcp.json` and `.vscode/mcp.json` ship with the template and configure the shadcn MCP server for Claude Code, Cursor and VS Code. The user may have added servers of their own, or created one of these files before the template shipped it. Merge them as JSON objects, never by overwriting: take the template's entry under `mcpServers` (`servers` in `.vscode/mcp.json`) where the user's entry by that name is unchanged or missing, keep every other server and setting the user has, and ask before replacing a `shadcn` entry they changed.
|
|
118
122
|
|
|
119
|
-
`.agents/skills/` is generated and gitignored. `pnpm nocobase skills sync` replaces each synchronized package-owned Skill directory wholesale, so never merge into or edit it. Local custom guidance belongs in committed application-owned files outside this generated directory
|
|
123
|
+
`.agents/skills/` is generated and gitignored. `pnpm nocobase skills sync` replaces each synchronized package-owned Skill directory wholesale, so never merge into or edit it. Local custom guidance belongs in committed application-owned files outside this generated directory, normally `.agents/rules/`.
|
|
120
124
|
|
|
121
125
|
`config.yml`, optional generated `.env`, `.gitignore`, `.npmrc`, and `pnpm-workspace.yaml` were written by the generator or by `pnpm nocobase config init` and appear in no diff at all.
|
|
122
126
|
|
|
@@ -155,6 +159,7 @@ Template structure — where most of the delta lands
|
|
|
155
159
|
Both sides edit these — the hardest decisions
|
|
156
160
|
client/plugins.ts server/plugins.ts cli/plugins.ts
|
|
157
161
|
package.json config.example.yml optional .env.example AGENTS.md CLAUDE.md
|
|
162
|
+
.agents/rules/
|
|
158
163
|
.mcp.json .cursor/mcp.json .vscode/mcp.json
|
|
159
164
|
|
|
160
165
|
Legacy application-owned guidance, when present
|
|
@@ -26,6 +26,7 @@ If the user explicitly requests the new default theme, replace only the agreed t
|
|
|
26
26
|
|
|
27
27
|
- Compare theme presets and `client/styles.css` together with shell wrappers, background assets, sidebar navigation, authentication forms, table components, overlays, toast configuration, and loading adapters affected by the target delta. Class names and `data-slot` selectors must match the application's installed component version.
|
|
28
28
|
- Preserve the application's branding, locale namespace, font choices, mobile navigation, login handlers, registration policy, plugin registrations, and business pages. Adapt presentation to its existing framework contracts rather than copying imports or APIs unavailable in its installed SDK.
|
|
29
|
+
- Merge a token together with everything that uses it. When BASE → TARGET adds a token, such as a `--hover` grey that components draw as `bg-hover`, give it a value in every preset PROJECT keeps, its own presets included, and map it in `client/styles.css` where TARGET does: a utility whose variable is undefined draws nothing, without an error, so a merged component quietly loses its hover or its ground. When TARGET removes or renames a token, such as `--overlay-backdrop`, search PROJECT for every remaining use, its own pages and components included, and move each to what TARGET draws instead. Treat a new global rule keyed by an attribute, such as a badge's `data-size`, the same way: a component that sets the attribute only looks right once the rule has been merged too.
|
|
29
30
|
- Check both first-level and nested navigation. A first-level row-height override does not affect `sidebar-menu-sub-button`; inspect row height, vertical gaps, long labels, scrolling, active state, collapsed rail, and keyboard focus in compact and spacious modes. Derive spacing from theme tokens, and preserve the primitive's collapsed/hidden behavior.
|
|
30
31
|
- Check authentication controls as a group: identifier input, password container, submit button, pending state, and forgot-password position. Keep registration hidden where the application disables it; do not add a sign-up link merely to match a template screenshot.
|
|
31
32
|
- Verify table headers on an actual business table, including header background, text contrast, sorting, alignment, and density. Verify shell gradients or watermarks outside an example homepage; preserve mobile layouts and ensure decorative layers cannot intercept clicks or obscure content.
|
|
@@ -5,7 +5,7 @@ description: Plan, build, deploy, verify, upgrade, and troubleshoot NocoBase 3 a
|
|
|
5
5
|
|
|
6
6
|
# NocoBase production deployment
|
|
7
7
|
|
|
8
|
-
Use this Skill to execute a complete deployment workflow. Read the application's `AGENTS.md
|
|
8
|
+
Use this Skill to execute a complete deployment workflow. Read the application's `AGENTS.md`, the `.agents/rules/` files it indexes for building and deployment, and `README.MD` before changing files or running stateful commands: the README documents this application's build targets, archive layout and configuration variables. The Deployment section of the NocoBase 3 documentation is the reference for command details and platform-specific examples; in the nocobase3 source repository it is `docs/docs/<lang>/deployment/`.
|
|
9
9
|
|
|
10
10
|
Do not treat a process being healthy as proof that the application is usable. A deployment is complete only after the database, configuration, application behavior, and persistence checks below have evidence.
|
|
11
11
|
|
|
@@ -38,7 +38,7 @@ Run the checks that the project actually defines; do not invent a test or lint c
|
|
|
38
38
|
pnpm build --target linux-x64 --node-version 24 --tar
|
|
39
39
|
```
|
|
40
40
|
|
|
41
|
-
`pnpm build` creates the production `dist` tree and installs or retargets production dependencies for the selected platform. The build is not tied to a mount path: the client uses relative asset URLs by default, or an absolute CDN prefix when configured below, and the server serves it at the `APP_BASE_PATH` it runs with, so one archive can be mounted at `/crm` or at the origin root. `--tar` additionally creates `storage/exports/dist.tar.gz`, containing `dist/` and `config.example.yml`; it does not contain the runtime configuration, database, uploads, or other business data. Inspect the archive before transfer:
|
|
41
|
+
`pnpm build` creates the production `dist` tree and installs or retargets production dependencies for the selected platform. The build is not tied to a mount path: the client uses relative asset URLs by default, or an absolute CDN prefix when configured below, and the server serves it at the `APP_BASE_PATH` it runs with, so one archive can be mounted at `/crm` or at the origin root. `--tar` additionally creates `storage/exports/dist.tar.gz`, containing `dist/` and `config.example.yml`; it does not contain the runtime configuration, database, uploads, or other business data. Extracting it produces exactly those two paths rather than scattering `server/` and `node_modules/` into the directory you unpacked in. `config.example.yml` travels with it because a deployment has to write a `config.yml` before it can start, and the example is the only statement of what may go in it. Directories of executable shims are left out: a `.bin` entry points at a path on the machine that installed it, and a dangling one makes `pnpm install` in the extracted tree report a corrupt store rather than repair it. Without `--tar` no archive is produced, which is what you want when the build is only going to be run locally. Inspect the archive before transfer:
|
|
42
42
|
|
|
43
43
|
```bash
|
|
44
44
|
tar -tzf storage/exports/dist.tar.gz | head -30
|