@nocobase/app-skills 0.1.0-beta.33 → 0.1.0-beta.34
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 +14 -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/shadcn.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/shell.md +1 -1
- 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-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.
|
|
@@ -108,6 +96,10 @@ Read the page for the task in front of you. Do not read all of them.
|
|
|
108
96
|
| Write server and migration tests, choose a test layer, verify before finishing | [testing and verification](references/testing.md) |
|
|
109
97
|
| Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
|
|
110
98
|
| Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
|
|
99
|
+
| Where a file goes, how the client and server are composed, configuration, changing the framework structure | [application structure](references/app-structure.md) |
|
|
100
|
+
| Register, update, customize or remove a plugin; check what an installed plugin already provides | [plugins](references/plugins.md) |
|
|
101
|
+
| Add an npm package, decide `dependencies` versus `devDependencies`, diagnose a missing module or native binary | [adding a dependency](references/dependencies.md) |
|
|
102
|
+
| Report the application's URL, dev server restarts and file watching, develop against another backend | [the development server](references/dev-server.md) |
|
|
111
103
|
| Understand behavior inherited from an official application template | [template variants](references/template-variants.md) |
|
|
112
104
|
|
|
113
105
|
A feature with a page and an API usually needs migrations, server routes, and a frontend change that follows the frontend workflow.
|
|
@@ -136,9 +128,9 @@ client/locales/, client/service-provider.ts, server/routes/,
|
|
|
136
128
|
server/providers/, database/main/migrations/, database/main/seeds/, tests/
|
|
137
129
|
```
|
|
138
130
|
|
|
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.
|
|
131
|
+
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
132
|
|
|
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
|
|
133
|
+
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
134
|
|
|
143
135
|
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
136
|
|
|
@@ -156,6 +148,9 @@ Generated .agents/skills/ — synchronized copies, gitignored, replaced
|
|
|
156
148
|
.claude/skills/ — symbolic links to the above so Claude Code
|
|
157
149
|
discovers them; gitignored, rewritten by the same sync
|
|
158
150
|
|
|
151
|
+
Rules .agents/rules/ — application-specific guidance, committed and
|
|
152
|
+
application-owned; AGENTS.md indexes it
|
|
153
|
+
|
|
159
154
|
Config config.yml — written by pnpm nocobase config init, gitignored, holds
|
|
160
155
|
secrets; document options in config.example.yml instead
|
|
161
156
|
```
|
|
@@ -180,33 +175,13 @@ These cause real damage and appear in every reference:
|
|
|
180
175
|
- **Visual consistency is application-wide.** Restyling only your part is a defect. Change the design tokens if a change is needed.
|
|
181
176
|
- **Route paths never include the deployment base path.** The runtime restores it.
|
|
182
177
|
- **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
|
|
178
|
+
- **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
179
|
- **Tests live in `tests/`,** never beside the source; browser tests against a running application go in `tests/playwright/`.
|
|
185
180
|
- **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
181
|
|
|
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.
|
|
182
|
+
## The development server
|
|
208
183
|
|
|
209
|
-
|
|
184
|
+
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
185
|
|
|
211
186
|
## Finishing
|
|
212
187
|
|
|
@@ -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.
|
|
@@ -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,6 +1,6 @@
|
|
|
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
|
|
|
@@ -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
|
|
@@ -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
|