@nocobase/app-skills 0.1.0-beta.51 → 0.1.0-beta.53
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 +7 -3
- package/skills/nocobase-app-development/SKILL.md +3 -1
- package/skills/nocobase-app-development/references/dependencies.md +34 -0
- package/skills/nocobase-app-development/references/dev-server.md +3 -1
- package/skills/nocobase-app-development/references/frontend/references/page.md +2 -2
- package/skills/nocobase-app-development/references/frontend/references/ui-library.md +27 -0
- package/skills/nocobase-app-development/references/internal-package-example.md +48 -0
- package/skills/nocobase-app-development/references/plugins.md +20 -2
- package/skills/nocobase-app-development/scripts/create-internal-package.mjs +87 -0
- package/skills/nocobase-app-plugin-development/SKILL.md +68 -0
- package/skills/nocobase-app-plugin-development/agents/openai.yaml +6 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/cli/count.ts +14 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/cli/index.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/index.ts +16 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/de-DE.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/en-US.ts +11 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/es-ES.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/fr-FR.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/id-ID.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/index.ts +16 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/ja-JP.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/pt-BR.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/vi-VN.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/zh-CN.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/locales/zh-TW.ts +10 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/public-config.ts +13 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/client/reading-list.tsx +56 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/database/migrations/202610180001_reading_list.ts +16 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/eslint.config.js +6 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/package.json +49 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/config.ts +39 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/index.ts +22 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/provider.ts +31 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/providers/index.ts +5 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/routes.ts +56 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/server/service.ts +35 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/cli/count.test.ts +44 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/client/public-config.test.tsx +19 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/client/reading-list.test.tsx +87 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/database/migration.test.ts +26 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/package.json +5 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/server/app.ts +19 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/server/runtime.ts +67 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/fixtures/app/server/standalone.ts +31 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/helpers/app.ts +27 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/server/config.test.ts +38 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tests/server/routes.test.ts +50 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/tsconfig.json +16 -0
- package/skills/nocobase-app-plugin-development/assets/testing-example/vitest.config.ts +34 -0
- package/skills/nocobase-app-plugin-development/references/cli.md +363 -0
- package/skills/nocobase-app-plugin-development/references/client-api.md +222 -0
- package/skills/nocobase-app-plugin-development/references/client-child-routes.md +351 -0
- package/skills/nocobase-app-plugin-development/references/client-components.md +272 -0
- package/skills/nocobase-app-plugin-development/references/client-examples.md +641 -0
- package/skills/nocobase-app-plugin-development/references/client-pages-and-routes.md +125 -0
- package/skills/nocobase-app-plugin-development/references/client-routing.md +159 -0
- package/skills/nocobase-app-plugin-development/references/client.md +162 -0
- package/skills/nocobase-app-plugin-development/references/configuration.md +65 -0
- package/skills/nocobase-app-plugin-development/references/database.md +225 -0
- package/skills/nocobase-app-plugin-development/references/http-api.md +184 -0
- package/skills/nocobase-app-plugin-development/references/i18n.md +374 -0
- package/skills/nocobase-app-plugin-development/references/plugin-foundation.md +203 -0
- package/skills/nocobase-app-plugin-development/references/plugin-skills.md +118 -0
- package/skills/nocobase-app-plugin-development/references/registration.md +135 -0
- package/skills/nocobase-app-plugin-development/references/registry.md +11 -0
- package/skills/nocobase-app-plugin-development/references/repository-examples.md +264 -0
- package/skills/nocobase-app-plugin-development/references/server-route-examples.md +518 -0
- package/skills/nocobase-app-plugin-development/references/server.md +291 -0
- package/skills/nocobase-app-plugin-development/references/service-examples.md +470 -0
- package/skills/nocobase-app-plugin-development/references/services.md +188 -0
- package/skills/nocobase-app-plugin-development/references/system-settings.md +106 -0
- package/skills/nocobase-app-plugin-development/references/testing-example.md +59 -0
- package/skills/nocobase-app-plugin-development/references/testing.md +139 -0
- package/skills/nocobase-app-plugin-development/references/theme-tokens.md +105 -0
- package/skills/nocobase-app-plugin-development/scripts/verify-testing-example.mjs +90 -0
- package/skills/nocobase-app-upgrade/SKILL.md +7 -1
- package/skills/nocobase-app-upgrade/references/edge-cases.md +6 -0
- package/skills/nocobase-app-upgrade/references/list-navigation-upgrade.md +18 -0
- package/skills/nocobase-app-upgrade/references/plugin-development-skill.md +32 -0
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nocobase/app-skills",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
4
|
-
"description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
|
|
3
|
+
"version": "0.1.0-beta.53",
|
|
4
|
+
"description": "Agent Skills for developing applications and plugins, upgrading and deploying NocoBase applications.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -10,7 +10,11 @@
|
|
|
10
10
|
},
|
|
11
11
|
"prettier": "@nocobase/dev-config/prettier",
|
|
12
12
|
"files": [
|
|
13
|
-
"skills"
|
|
13
|
+
"skills",
|
|
14
|
+
"!skills/nocobase-app-plugin-development/**/node_modules",
|
|
15
|
+
"!skills/nocobase-app-plugin-development/**/storage",
|
|
16
|
+
"!skills/nocobase-app-plugin-development/**/dist",
|
|
17
|
+
"!skills/nocobase-app-plugin-development/**/coverage"
|
|
14
18
|
],
|
|
15
19
|
"publishConfig": {
|
|
16
20
|
"access": "public"
|
|
@@ -11,6 +11,8 @@ metadata:
|
|
|
11
11
|
|
|
12
12
|
# NocoBase 3 application development
|
|
13
13
|
|
|
14
|
+
When the task creates or maintains a reusable plugin under this App's `packages/`, read `<app-root>/.agents/skills/nocobase-app-plugin-development/SKILL.md` by its explicit project path. It ships alongside this Skill in `@nocobase/app-skills`. Use this application's guidance for App-owned features and the plugin Skill for plugin-owned contracts and packaging; do not install the older global plugin development Skill.
|
|
15
|
+
|
|
14
16
|
Use this Skill when building a complete application or an individual feature: business and administration pages, endpoints, data, services and their tests.
|
|
15
17
|
|
|
16
18
|
Do not use it to develop a published plugin package. Plugin development has its own protocol and lives in a separate repository.
|
|
@@ -37,7 +39,7 @@ Do not infer the application's capabilities from a template name or from this Sk
|
|
|
37
39
|
|
|
38
40
|
## The one rule that decides most tasks
|
|
39
41
|
|
|
40
|
-
Build the feature in the application. Do not run a plugin generator, create a `packages/plugins/` directory, or write a `defineServerPlugin()` declaration for this application's own feature. Create a plugin only when the user explicitly asks for an independently published, reusable package.
|
|
42
|
+
Build the feature in the application. Do not run a plugin generator, create a `packages/plugins/` directory, or write a `defineServerPlugin()` declaration for this application's own feature. Create a plugin only when the user explicitly asks for an independently published, reusable package. Ordinary internal workspace packages for shared code are different: when the application needs them, follow [internal workspace packages](references/dependencies.md#internal-workspace-packages), keeping one application at the workspace root with internal packages under `packages/`. The [runnable package example](references/internal-package-example.md) supplies complete configuration and explains declaration watching.
|
|
41
43
|
|
|
42
44
|
## Check the installed plugins first
|
|
43
45
|
|
|
@@ -48,3 +48,37 @@ Declare such a package in `dependencies` when you write the code; nothing will r
|
|
|
48
48
|
Node ABI to major version: 115 is Node 20, 127 is 22, 137 is 24, 147 is 26.
|
|
49
49
|
|
|
50
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.
|
|
51
|
+
|
|
52
|
+
## Internal workspace packages
|
|
53
|
+
|
|
54
|
+
An application may own a pnpm workspace without moving its `client/`, `server/`, `cli/` or `database/`. Declare `packages: ['packages/*']` in its root `pnpm-workspace.yaml`, preserving existing settings, and put ordinary shared packages below `packages/`. Use unique package names and explicit `workspace:*` references: server imports belong in the application's `dependencies`, client-only imports in `devDependencies`. Internal packages can be private; sharing code does not require a plugin or an npm release. Never import a sibling package through a relative filesystem path.
|
|
55
|
+
|
|
56
|
+
The supported layout is one application at the root with internal packages below `packages/`; this is not a general multi-application monorepo workflow. Use the [runnable internal-package example](internal-package-example.md) for complete source, configuration, scripts, application imports and declaration watching.
|
|
57
|
+
|
|
58
|
+
Use `src/` for an ordinary package's sources. Prefer source imports during development, with compiled declarations for typechecking and compiled imports for deployment. For example:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"name": "@my-app/shared",
|
|
63
|
+
"version": "0.0.1",
|
|
64
|
+
"private": true,
|
|
65
|
+
"type": "module",
|
|
66
|
+
"files": ["dist"],
|
|
67
|
+
"exports": {
|
|
68
|
+
".": { "types": "./dist/index.d.ts", "import": "./src/index.ts" }
|
|
69
|
+
},
|
|
70
|
+
"publishConfig": {
|
|
71
|
+
"exports": {
|
|
72
|
+
".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`publishConfig.exports` also tells the application build which exports to put in its vendored deployment copy; it does not require publishing. Give the package a `build` script that emits JavaScript and declarations into `dist`, plus `lint`, `typecheck`, `test`, `check` and `fix` scripts using `@nocobase/dev-config`. Install the package's build tooling as its own development dependencies. Keep React and identity-sensitive NocoBase runtimes as peers, supplied by the application. Browser packages must not expose server-only imports through their client entry.
|
|
79
|
+
|
|
80
|
+
Run `pnpm install` once at the application root. Build a new package before standalone typechecking needs its declarations. When runtime imports point to `src` but types point to `dist`, keep a declaration watcher running (`tsc --emitDeclarationOnly --watch`); otherwise exported type changes leave consumers checking stale declarations. During `pnpm dev`, Vite loads linked client sources and the server watches reachable internal workspace packages, including transitive ones, under `src/`, `server/`, `database/` and `shared/`; it also watches compiled `dist/` for packages that choose compiled exports. Such packages need their own build watcher running separately. Restart development after adding a package or changing the dependency graph so the watch set is recalculated.
|
|
81
|
+
|
|
82
|
+
`pnpm build` builds workspace dependencies before application typechecking and client bundling. The deployment includes runtime workspace packages and their transitive runtime dependencies under `dist/vendor`, using their compiled exports. Keep runtime assets in `dist` or in literal paths named by `files`; glob patterns in `files` are not copied by the deployment builder. Verify a deployment outside the source workspace. Do not run a recursive build that also selects the root application while its own build is rebuilding dependencies; an external topological build may set `NOCOBASE_SKIP_WORKSPACE_DEPENDENCY_BUILD=1` once it owns that ordering.
|
|
83
|
+
|
|
84
|
+
Each internal package owns its checks. Current templates exclude `packages/` from root linting and formatting and run the packages' `check` scripts through `pnpm check:packages` before the application checks. During a template upgrade, retain internal packages, their `workspace:` dependencies and custom workspace patterns, then reinstall at the application root and check the affected packages and application together.
|
|
@@ -14,6 +14,8 @@ With `PROXY_TARGET_URL`, the local Hono server is skipped and Vite becomes the l
|
|
|
14
14
|
|
|
15
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
16
|
|
|
17
|
+
In normal watch mode the public entry port stays open while the application backend restarts on a private loopback port. New connections wait up to 30 seconds for that backend, so shared-package edits can update client modules even during a server restart. Requests already sent to the old backend are never replayed; a pending API call or realtime connection can still be interrupted. Keep using the printed `Local:` URL rather than the private backend port. Strict startup and remote-backend mode do not use this connection proxy.
|
|
18
|
+
|
|
17
19
|
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
20
|
|
|
19
21
|
## One development server per application
|
|
@@ -38,7 +40,7 @@ For local client debugging against another running application, use `PROXY_TARGE
|
|
|
38
40
|
|
|
39
41
|
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
42
|
|
|
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
|
|
43
|
+
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 public application 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
44
|
|
|
43
45
|
## Development logging
|
|
44
46
|
|
|
@@ -309,7 +309,7 @@ The shell header shows the current page's breadcrumb after the sidebar toggle, o
|
|
|
309
309
|
|
|
310
310
|
- It is a muted text link with an arrow and "Back" (`navigation.back`), turning to the foreground on hover.
|
|
311
311
|
- By default it leads to the parent route and keeps the query string, as closing an overlay does: from `/projects/import?status=active` it returns to `/projects?status=active`, and the list keeps its search and filters. The parent is found by route, not by path segment, so a child route with a two-segment path returns to its parent too.
|
|
312
|
-
- **
|
|
312
|
+
- When the shell has visited the parent, the default back link restores that parent's recorded query, including an explicitly empty query. Without a recorded parent (including a direct detail URL or reload), **the fallback query string is the current one.** The page it returns to gets its search and filters back only if every link on the way down carried them: a link into a page below another one forwards `location.search` whole, never a selection of it. Whatever the page being left wrote there goes back too, unless the page removes it: a page that writes parameters of its own, itself or in its tabs (the Orders tab's `ordersQ`), passes `to` with those parameters removed — `<BackButton to={{ pathname: '..', search: withoutParams(location.search, CUSTOMER_PAGE_PARAMS) }} />`, with `withoutParams` from [`example/url-search.md`](example/url-search.md) — so the list gets exactly its own back, and the next customer does not open with the previous one's order search. `..` still follows the parent route the page was opened from.
|
|
313
313
|
- `to` sends it elsewhere, for a page that belongs to exactly one parent, such as a record page declared beside its list: `<BackButton to={{ pathname: '/customers', search: location.search }} />`. For a module reused under several parents — a record's page opened from another page as well (["The same detail page over another page" in `child-routes.md`](child-routes.md#the-same-detail-page-over-another-page)) — omit it, or keep `..` as its `pathname` when only the query string changes, as the previous point does, so the back button follows the parent route it was opened from; a hard-coded path sends a user who came from elsewhere to a page they were not on. `children` replaces the label; keep "Back" unless the destination needs naming.
|
|
314
314
|
- It navigates rather than going back in the browser history, which a page opened from a link or a refresh does not have, and it replaces the history entry, as closing an overlay does: the browser's Back then does not reopen the page just left, such as a form that would come back empty.
|
|
315
315
|
|
|
@@ -321,7 +321,7 @@ By default the trail is generated from the matched route levels:
|
|
|
321
321
|
|
|
322
322
|
- A route with `breadcrumb` is a level, titled by it; a menu page (`navigation` with a component) without one is a level titled by its `navigation.title`. Tab, dialog and drawer routes declare neither and add no level, so an overlay leaves the page beneath as the current level.
|
|
323
323
|
- A level the viewer may not open is left out, so a denied page's title never shows.
|
|
324
|
-
- Earlier page levels link to their actual URLs, without query
|
|
324
|
+
- Earlier page levels link to their actual URLs with the query recorded when that ancestor was last visited in the current route ancestry. This restores its search, filters and page without copying detail-only parameters. An ancestor never visited in this mounted shell (for example, a direct detail URL or a reload) links without a query; use an explicit `usePageBreadcrumb` destination when a deep link must carry a known parent query. A group without a component is plain text. The last level is the current page and is not a link.
|
|
325
325
|
- `breadcrumb.title` is a static translation key and names the kind of page ("Project details"), so it can sit on a path with parameters and is known before anything loads.
|
|
326
326
|
|
|
327
327
|
A page whose trail names records, or should lead back with the parent's search, declares its whole trail with `usePageBreadcrumb` from `@nocobase/app-client`, the page itself last:
|
|
@@ -288,6 +288,20 @@ Theme-aware, read-only lifecycle diagram using React Flow and ELK. Shows the cur
|
|
|
288
288
|
- Example: `@nocobase/lifecycle-diagram-demo` (`pnpm exec shadcn view @nocobase/lifecycle-diagram-demo`)
|
|
289
289
|
- After installing: Pass description.description from useLifecycle/createLifecycleHook, currentState from view.record, availableTransitions filtered from view.available, and history from view.history.transitions. History matches the exact transition/source/destination; current state alone never implies a visited path. Pass a translated endLabel for separate decorative markers on explicit final states. Defaults to direction DOWN, autoHeight and initialMinZoom 0.7 for readable vertical page reading. The Fit control still shows the entire graph; an explicit initialMinZoom overrides the default. Override direction and autoHeight explicitly for compact canvases. stateActions supplies explicit configuration buttons; nodeDescription displays real policy summaries. Translate ariaLabel, stateLabel and transitionLabel; append a gear to automatic transition labels if needed. Edges are solid with inline labels and subdued neutral strokes; current/visited/available highlights use the application primary theme token. Current nodes have a stronger border and ring; icons, top accents and status footers distinguish current, visited and configurable nodes using theme tokens. onStateClick/onTransitionClick open details and never fire transitions. Keep toMermaid for documentation/export. Pass configuration={label, canConfigure, onConfigure} for automatic Configure buttons on authorized bound states and configuration selection on bound transitions. onConfigure receives the exact target and permitted bound fields grouped by native parameter key; connect the existing real editor and API. canConfigure is required and is only a UI affordance. Explicit direction/style overrides are reserved for user-requested customization; Mermaid is documentation/export only.
|
|
290
290
|
|
|
291
|
+
## File
|
|
292
|
+
|
|
293
|
+
### file-component-ui
|
|
294
|
+
|
|
295
|
+
Application-owned upload, list, thumbnail, and preview components for business file endpoints.
|
|
296
|
+
|
|
297
|
+
- Kind: block
|
|
298
|
+
- Install: `yes n | pnpm exec shadcn add @nocobase/file-component-ui`
|
|
299
|
+
- Installs to: `client/extensions/nocobase-file-component-ui/`
|
|
300
|
+
- Plugin dependencies: `@nocobase/app-plugin-file`
|
|
301
|
+
- Also installs: `@nocobase/attachment-list`
|
|
302
|
+
- Example: `@nocobase/file-component-ui-demo` (`pnpm exec shadcn view @nocobase/file-component-ui-demo`)
|
|
303
|
+
- After installing: Requires the File plugin services and your own authorized file repository. Pass a ClientFileRepository to FileUploadField. Merge locales/ into application locales. The default template preinstalls this block; reconcile existing copies instead of overwriting them.
|
|
304
|
+
|
|
291
305
|
## Inbox
|
|
292
306
|
|
|
293
307
|
### inbox
|
|
@@ -313,6 +327,19 @@ A header button linking to the inbox, with an amber badge for what waits on the
|
|
|
313
327
|
- Example: `@nocobase/inbox-button-demo` (`pnpm exec shadcn view @nocobase/inbox-button-demo`)
|
|
314
328
|
- After installing: Render <InboxButton badge={inboxBadge(waiting, unread)} /> inside a TooltipProvider, with inboxBadge from #components/inbox-badge, waiting what your inbox counts as waiting (0 without decisions) and unread from useInboxUnreadCount() of @nocobase/app-plugin-notification-in-app/client/inbox; useDocumentTitleBadge(badge?.text ?? null) prefixes the tab title. Add the inboxButton.* keys its README lists to client/locales/.
|
|
315
329
|
|
|
330
|
+
## Notification
|
|
331
|
+
|
|
332
|
+
### notification-logs-ui
|
|
333
|
+
|
|
334
|
+
Application-owned delivery and provider attempt log components backed by the NocoBase notification API.
|
|
335
|
+
|
|
336
|
+
- Kind: block
|
|
337
|
+
- Install: `yes n | pnpm exec shadcn add @nocobase/notification-logs-ui`
|
|
338
|
+
- Installs to: `client/extensions/nocobase-notification-logs-ui/`
|
|
339
|
+
- Plugin dependencies: none
|
|
340
|
+
- Example: `@nocobase/notification-logs-ui-demo` (`pnpm exec shadcn view @nocobase/notification-logs-ui-demo`)
|
|
341
|
+
- After installing: Requires the Notification server plugin and authorized access to GET /api/notifications/logs. Mount NotificationLogsPage in an application-owned route and merge locales/ into application locales. Shows the newest 100 logs; adds no route or permissions.
|
|
342
|
+
|
|
316
343
|
## Other
|
|
317
344
|
|
|
318
345
|
### data-table
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# A runnable internal package
|
|
2
|
+
|
|
3
|
+
This example supports one application at the workspace root, with private shared packages below `packages/`. It does not establish a general multi-application monorepo workflow. Custom workspace patterns are preserved during creation and upgrades, but the automatic internal-source watches and template package checks target `packages/`; a different layout needs its own watching and checks.
|
|
4
|
+
|
|
5
|
+
Run the [example creator](../scripts/create-internal-package.mjs) from an installed application root:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
node .agents/skills/nocobase-app-development/scripts/create-internal-package.mjs
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
It creates `packages/shared` and refuses to overwrite it. The generated package includes `src/index.ts`, a behavior test, `tsconfig.json`, ESLint and Vitest configurations, ignore files, and `build`, `dev:types`, `typecheck`, `lint`, `format`, `test`, `check` and `fix` scripts. Tooling dependencies use the application's installed versions, including `@nocobase/dev-config`; no registry lookup chooses unrelated newer versions. The sample has no Node-only runtime imports, so its `greet` function and `Greeting` type work in both application halves. Adapt the package name and behavior to the application after trying it.
|
|
12
|
+
|
|
13
|
+
Ensure `pnpm-workspace.yaml` includes `packages/*`, retaining its other settings. Add `"@my-app/shared": "workspace:*"` to the application's `dependencies` for this shared server/client example. A client-only package belongs in `devDependencies`. Then run:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
pnpm install
|
|
17
|
+
pnpm --filter @my-app/shared fix
|
|
18
|
+
pnpm --filter @my-app/shared build
|
|
19
|
+
pnpm check:packages
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Import by package name from either `client/` or `server/`:
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { greet, type Greeting } from '@my-app/shared';
|
|
26
|
+
|
|
27
|
+
const greeting: Greeting = greet('Ada');
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Use `greeting.message` in the feature that consumes it; keep user-visible application copy in the application's translations. The package exports `src/index.ts` at development runtime and `dist/index.d.ts` to TypeScript. Its `publishConfig.exports` directs deployment imports to `dist/index.js`; it remains private and needs no publishing or plugin registration.
|
|
31
|
+
|
|
32
|
+
## Keep declarations current
|
|
33
|
+
|
|
34
|
+
Build once before the application's first standalone typecheck. During development, run this in a separate terminal alongside `pnpm dev`:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pnpm --filter @my-app/shared dev:types
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Vite and tsx read the changed source immediately, while application typechecking reads the generated declarations. Without the declaration watcher, changing an exported type can leave the editor and `pnpm typecheck` checking the previous API even though the runtime uses the new code. Wait for the watcher to finish without errors before checking consumers; a failed emit can leave older declarations on disk. With several packages, start their declaration watchers and build dependencies in order before the first consumer check. Packages using compiled runtime exports need a full `tsc --watch` build instead of declaration-only emission.
|
|
41
|
+
|
|
42
|
+
Restart `pnpm dev` after adding a package or changing workspace dependencies, because the server's explicit watch set is calculated at startup. `pnpm build` builds workspace dependencies before typechecking and bundling the application; the one-shot deployment build does not need these watchers.
|
|
43
|
+
|
|
44
|
+
## Verify the consuming application
|
|
45
|
+
|
|
46
|
+
Run `pnpm check:packages` and the application's scoped checks after wiring in the imports. The template check reports any selected internal package without a non-empty `check` script before running any package checks; an empty `packages/` layout succeeds. To verify a changed exported type, add a required field to `Greeting`, update `greet`, wait for declaration generation, and confirm an application assignment that omits the new field fails typechecking. Repair the consumer before continuing.
|
|
47
|
+
|
|
48
|
+
For runtime acceptance, exercise a real frontend use and server response before and after editing `greet`, then build with `pnpm build --tar` and run the extracted archive outside the source workspace with the original sources unavailable. Verify the consuming feature there as well as the health endpoint. Follow the deployment Skill for configuration and database isolation; a successful health response alone cannot prove the internal package was included.
|
|
@@ -4,7 +4,7 @@ Read this before registering, updating, customizing or removing a plugin, and be
|
|
|
4
4
|
|
|
5
5
|
## Read a plugin's Skill before building what it already does
|
|
6
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:
|
|
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/*` and `@scope/app-plugin-*` dependencies and registered plugins into `.agents/skills/`. Before implementing a feature, check whether an installed and registered plugin already covers it:
|
|
8
8
|
|
|
9
9
|
| The requirement sounds like | Read the Skill for |
|
|
10
10
|
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -26,10 +26,28 @@ Building a permission system, a notification sender, or a job scheduler by hand
|
|
|
26
26
|
|
|
27
27
|
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.
|
|
28
28
|
|
|
29
|
-
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
|
+
Skills synchronization reads direct `@nocobase/*` and `@scope/app-plugin-*` 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.
|
|
30
30
|
|
|
31
31
|
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.
|
|
32
32
|
|
|
33
|
+
## Creating an application-local plugin
|
|
34
|
+
|
|
35
|
+
Keep ordinary application code in the application. Use an internal shared package for code consumed through imports alone; use a plugin for a capability with explicit Client, Server or CLI contributions. Both may live in the application's `packages/` workspace without an npm release. See [internal packages](internal-package-example.md) for the ordinary shared-package workflow.
|
|
36
|
+
|
|
37
|
+
Use `@nocobase/create-plugin` from this installed application, not a NocoBase source checkout. Select only the required capabilities and inspect the plan before applying it:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pnpm dlx @nocobase/create-plugin demo-tools --with cli --dry-run --json
|
|
41
|
+
pnpm dlx @nocobase/create-plugin demo-tools --with cli
|
|
42
|
+
pnpm --filter @nocobase/app-plugin-demo-tools check
|
|
43
|
+
pnpm nocobase plugin register @nocobase/app-plugin-demo-tools --no-install
|
|
44
|
+
pnpm nocobase demo-tools info --json
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The App-aware generator identifies `nocobase.templateKind: app`, writes `packages/app-plugin-demo-tools/`, preserves workspace configuration and adds a `workspace:*` application dependency. It resolves external dependency versions from the installed application and makes the local plugin private. A dry run also reports project-file edits and resolved dependency versions; no files are written or dependencies installed. If the installed generator still points at `packages/plugins/` or `app-template-default`, use a release that supports application workspaces rather than moving files and rewriting dependency protocols manually.
|
|
48
|
+
|
|
49
|
+
A full package name such as `@my-company/app-plugin-demo-tools` keeps the chosen scope; use that full name for registration with a compatible App CLI. Runtime registration remains separate from generation and installation. `--no-install` postpones installation; run `pnpm install` before registration. Missing or incompatible dependencies must be resolved in the application first. Read the generated plugin's `AGENTS.md`, implement and test its behavior, preserve the application's existing registrations, and verify its real use in the application as well as `pnpm build`.
|
|
50
|
+
|
|
33
51
|
## Installing and updating
|
|
34
52
|
|
|
35
53
|
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.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
|
|
4
|
+
// Run from an installed application. Resolve tooling versions before creating anything.
|
|
5
|
+
const root = process.cwd();
|
|
6
|
+
const tooling = [
|
|
7
|
+
'@nocobase/dev-config',
|
|
8
|
+
'@types/node',
|
|
9
|
+
'typescript',
|
|
10
|
+
'eslint',
|
|
11
|
+
'prettier',
|
|
12
|
+
'vitest',
|
|
13
|
+
];
|
|
14
|
+
const devDependencies = Object.fromEntries(
|
|
15
|
+
tooling.map((name) => {
|
|
16
|
+
const manifest = JSON.parse(
|
|
17
|
+
readFileSync(
|
|
18
|
+
path.join(root, 'node_modules', name, 'package.json'),
|
|
19
|
+
'utf8',
|
|
20
|
+
),
|
|
21
|
+
);
|
|
22
|
+
return [name, manifest.version];
|
|
23
|
+
}),
|
|
24
|
+
);
|
|
25
|
+
const directory = path.join(root, 'packages/shared');
|
|
26
|
+
mkdirSync(path.dirname(directory), { recursive: true });
|
|
27
|
+
// Refuse to replace an existing package, even an empty directory.
|
|
28
|
+
mkdirSync(directory);
|
|
29
|
+
const files = {
|
|
30
|
+
'package.json': {
|
|
31
|
+
name: '@my-app/shared',
|
|
32
|
+
version: '0.0.1',
|
|
33
|
+
private: true,
|
|
34
|
+
type: 'module',
|
|
35
|
+
files: ['dist'],
|
|
36
|
+
exports: { '.': { types: './dist/index.d.ts', import: './src/index.ts' } },
|
|
37
|
+
publishConfig: {
|
|
38
|
+
exports: {
|
|
39
|
+
'.': { types: './dist/index.d.ts', import: './dist/index.js' },
|
|
40
|
+
},
|
|
41
|
+
},
|
|
42
|
+
prettier: '@nocobase/dev-config/prettier',
|
|
43
|
+
scripts: {
|
|
44
|
+
build: 'tsc -p tsconfig.json',
|
|
45
|
+
'dev:types':
|
|
46
|
+
'tsc -p tsconfig.json --emitDeclarationOnly --watch --preserveWatchOutput',
|
|
47
|
+
typecheck: 'tsc -p tsconfig.json --noEmit',
|
|
48
|
+
lint: 'eslint . --max-warnings 0',
|
|
49
|
+
'lint:fix': 'eslint . --fix --max-warnings 0',
|
|
50
|
+
format: 'prettier . --write',
|
|
51
|
+
'format:check': 'prettier . --check',
|
|
52
|
+
test: 'vitest run',
|
|
53
|
+
check:
|
|
54
|
+
'pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build',
|
|
55
|
+
fix: 'pnpm lint:fix && pnpm format',
|
|
56
|
+
},
|
|
57
|
+
devDependencies,
|
|
58
|
+
},
|
|
59
|
+
'tsconfig.json': {
|
|
60
|
+
extends: '@nocobase/dev-config/tsconfig/server-library.json',
|
|
61
|
+
compilerOptions: { rootDir: 'src', outDir: 'dist' },
|
|
62
|
+
include: ['src'],
|
|
63
|
+
},
|
|
64
|
+
'eslint.config.js':
|
|
65
|
+
"import { createNodeLibraryConfig } from '@nocobase/dev-config/eslint';\nexport default createNodeLibraryConfig();\n",
|
|
66
|
+
'vitest.config.ts':
|
|
67
|
+
"import { createNodeVitestConfig } from '@nocobase/dev-config/vitest/node';\nexport default createNodeVitestConfig();\n",
|
|
68
|
+
'.prettierignore': 'dist/\nnode_modules/\ncoverage/\n',
|
|
69
|
+
'.gitignore': 'dist/\nnode_modules/\ncoverage/\n',
|
|
70
|
+
'src/index.ts':
|
|
71
|
+
'export interface Greeting {\n message: string;\n}\n\nexport function greet(name: string): Greeting {\n return { message: `Hello, ${name}!` };\n}\n',
|
|
72
|
+
'tests/greet.test.ts':
|
|
73
|
+
"import { expect, it } from 'vitest';\nimport { greet } from '../src/index.ts';\n\nit('greets the requested person', () => {\n expect(greet('Ada')).toEqual({ message: 'Hello, Ada!' });\n});\n",
|
|
74
|
+
};
|
|
75
|
+
for (const [relative, contents] of Object.entries(files)) {
|
|
76
|
+
const file = path.join(directory, relative);
|
|
77
|
+
mkdirSync(path.dirname(file), { recursive: true });
|
|
78
|
+
writeFileSync(
|
|
79
|
+
file,
|
|
80
|
+
typeof contents === 'string'
|
|
81
|
+
? contents
|
|
82
|
+
: `${JSON.stringify(contents, null, 2)}\n`,
|
|
83
|
+
);
|
|
84
|
+
}
|
|
85
|
+
console.log(
|
|
86
|
+
'Created packages/shared. Add @my-app/shared: workspace:* to the application dependencies, then run pnpm install and pnpm --filter @my-app/shared fix.',
|
|
87
|
+
);
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: nocobase-app-plugin-development
|
|
3
|
+
description: Create and maintain NocoBase 3 plugins inside an existing App or a NocoBase 3 source workspace, including Client, Server, CLI, database resources, UI Library integration, Plugin Skills, and registration. Use for App-local plugins under packages/ and source-workspace plugins or examples. Not for creating an App, application-only feature work, or legacy NocoBase 2 plugins.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# NocoBase Plugin Development
|
|
7
|
+
|
|
8
|
+
Use this Skill to develop a plugin in the user’s existing NocoBase 3 App. Read that App’s `AGENTS.md`, relevant installed Skills, and the plugin before editing. An App created by create-app identifies itself with `nocobase.templateKind: "app"` in `package.json`; its local plugins belong in `packages/`. Start from an installed App with working dependencies. If no App exists, use the available `nocobase-create-app` Skill first, then return here. Do not download the NocoBase source repository as a prerequisite.
|
|
9
|
+
|
|
10
|
+
This Skill ships with the App's installed `@nocobase/app-skills`; update it through a compatible App upgrade and `pnpm nocobase skills sync`, not by editing the generated copy or installing a global copy. Read it by its project path when an older global entry has the same name. The upgrade Skill describes retiring that global installation after a project replacement is verified.
|
|
11
|
+
|
|
12
|
+
For work explicitly in the NocoBase source repository, the repository links this same maintained Skill locally. Read `.agents/rules/plugin-development.md` from that repository root for source-only creation, registration and validation commands. An App does not need those repository files. Source paths in references are optional lookup locations; use installed exports, declarations and synchronized Skills to verify APIs for the App's version. Do not apply the legacy `Plugin` class, `src/client-v2/` or `nb scaffold plugin` protocol. If the creation tool or App CLI lacks App-workspace support, report the incompatible packages instead of hand-building a scaffold or downloading the source repository.
|
|
13
|
+
|
|
14
|
+
## Choose the relevant references
|
|
15
|
+
|
|
16
|
+
These English references adapt the plugin development guide into task-specific instructions. Read the rows relevant to the task; do not load the entire reference set by default.
|
|
17
|
+
|
|
18
|
+
| Task | Read |
|
|
19
|
+
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
|
|
20
|
+
| Create a plugin, choose capabilities, change declarations, exports, dependencies, or public contracts | [Scaffolding and package contracts](references/plugin-foundation.md) |
|
|
21
|
+
| Register, configure, upgrade, disable, unregister, or diagnose plugin integration | [Registration and lifecycle](references/registration.md) |
|
|
22
|
+
| Choose Client components, ServiceProviders, React Providers, configuration, or API access | [Client architecture](references/client.md) |
|
|
23
|
+
| Define Server configuration defaults, environment mappings, validation, or browser-visible fields | [Plugin configuration](references/configuration.md) |
|
|
24
|
+
| Build or change any plugin UI | [shadcn components and styling](references/client-components.md) |
|
|
25
|
+
| Add business pages, menus, Tabs, route dialogs/drawers, child routes, or page overrides | [Client routing](references/client-routing.md) |
|
|
26
|
+
| Design configuration entities, settings permissions, routed editors and safe saves | [System settings](references/system-settings.md) |
|
|
27
|
+
| Define service contracts, Tokens, dependency injection, or lifecycle | [Services and Providers](references/services.md) |
|
|
28
|
+
| Add HTTP endpoints, authorization, Repository operations, background jobs, or queues | [Server development](references/server.md) |
|
|
29
|
+
| Name an `/api` path, choose its method, shape its response or error, or validate its input | [HTTP API rules](references/http-api.md) |
|
|
30
|
+
| Add migrations, seeds, or package resource/checksum handling | [Database resources](references/database.md) |
|
|
31
|
+
| Add or change text, locale resources, translated errors, or recipient-language messages | [Internationalization](references/i18n.md) |
|
|
32
|
+
| Author, publish, install, upgrade, or remove App-owned editable Client source | [UI Library ownership](references/registry.md) |
|
|
33
|
+
| Expose a plugin's capabilities to the App Agent | [Plugin Skills](references/plugin-skills.md) |
|
|
34
|
+
| Add commands, CLI exports, or CLI registration | [CLI plugins](references/cli.md) |
|
|
35
|
+
| Use `@nocobase/app-testing` for database, Server, Client or CLI tests and verify App integration | [Testing and delivery](references/testing.md) |
|
|
36
|
+
| Follow one executable plugin through migrations, protected API, Client, configuration and CLI tests | [Complete testing example](references/testing-example.md) |
|
|
37
|
+
|
|
38
|
+
For Realtime changes, check whether the target workspace or application provides a version-matched `nocobase-realtime` Skill from `@nocobase/realtime`; read it alongside the installed API declarations. Package integration guidance must match the target runtime version.
|
|
39
|
+
|
|
40
|
+
For worked implementations and tests, read the matching [Server Route examples](references/server-route-examples.md), [ServiceToken and Provider examples](references/service-examples.md), [Client examples](references/client-examples.md), or [Repository examples](references/repository-examples.md). These supplement the topic references with concrete code and point to maintained source fixtures; adapt their explicit example access policies to the requested product.
|
|
41
|
+
|
|
42
|
+
## Rules that apply before implementation
|
|
43
|
+
|
|
44
|
+
When creating a page or writing a page component, refer to [Pages, routes, and menus](references/client-pages-and-routes.md) for page component structure and route declarations. For nested pages, page-level navigation Tabs, route dialogs/drawers, or navigation groups, also read [Child routes, Tabs, overlays, navigation groups, and Outlet](references/client-child-routes.md). Before using the page and overlay examples, [copy the required component source into the plugin](references/client-components.md#copy-page-and-route-components-into-the-plugin). The examples import these plugin-owned copies through relative `.js` paths; the host's private breadcrumb component is excluded. For route overlay component availability and hook context boundaries, read [route dialogs and drawers](references/client-routing.md#route-dialogs-and-drawers).
|
|
45
|
+
|
|
46
|
+
- Use shadcn components for interactive UI primitives such as buttons, inputs, dialogs, selects, and Tabs. Read the component reference before UI work. Keep plugin-owned components in the plugin and align `components.json` with its package-local `#` imports and published `dist` mappings. Use the shared theme tokens for color, typography, spacing, size, radius, and shadow.
|
|
47
|
+
- Use child routes for page-level navigation Tabs by default, even when the user does not mention routing. Declare each Tab's content as a child route, render `Outlet` in the parent page component, and derive the active Tab from the URL. When the parent URL is opened without a child route, redirect to the default accessible Tab by replacing the current history entry and preserving query parameters. Opening an explicit Tab URL must retain that Tab's selection. Follow an explicit user request for a different interaction.
|
|
48
|
+
- In an existing App, create plugins with `pnpm create @nocobase/plugin@beta` and explicit capabilities, including `cli` when needed. In a source checkout, follow its repository-local creation instructions. Preview with `--dry-run --json`, check the target and project edits, then apply the same capability selection. Keep the generated runtime-aware shared development configuration; see [scaffolding](references/plugin-foundation.md).
|
|
49
|
+
- Keep declarations static and free of startup side effects. Lazy-load page components, locale messages, heavy SDKs, and genuinely optional features at their leaf boundaries. Pages are Routes, components are public/source exports, and neither is a separate runtime loader.
|
|
50
|
+
- Translate all plugin copy into the ten [supported languages](references/i18n.md#ship-all-ten-supported-languages) (`en-US`, `zh-CN`, `zh-TW`, `ja-JP`, `es-ES`, `pt-BR`, `fr-FR`, `de-DE`, `vi-VN`, `id-ID`) in every Client and Server locale manifest, typed with the complete `en-US` resource. Libraries the plugin depends on that ship translations, such as `@nocobase/i18n` for `@nocobase/app-plugin-i18n`, are completed to all ten as well. A new or changed key is translated into all ten in the same change; application templates are exempt.
|
|
51
|
+
- Reuse the host's API client through `useApiClient()` or `apiClientToken`; do not construct another application API client. Define shared service contracts and owner-created Tokens before implementations; consumers import the original Token.
|
|
52
|
+
- A plugin contributes no settings or dev pages; `defineAppRoutes()` is the only Client route API. Expose administration as settings items and APIs, grouped by management area (for example, Automation contains Workflow and Schedules), and leave any page over them to the application. See [System settings](references/system-settings.md) for declarations and server operation boundaries.
|
|
53
|
+
- Every `/api` route follows the [HTTP API rules](references/http-api.md): camelCase paths under the plugin's namespace, standard methods, `{ data }` responses, `ApiError` for every failure (clients branch on `reason`), zod input validated through `apiValidator()`, and a `describeRoute()` declaration on every route for the application's OpenAPI document at `/api/swagger/docs`. Data endpoints are `POST /api/{name}/{action}` with camelCase exposure names and are documented without a declaration.
|
|
54
|
+
- Each Server Route owns and tests its authentication and authorization, or its explicit public protocol boundary. Another contribution's middleware or registration order is not protection. Test the production contribution through `createRouter()`.
|
|
55
|
+
- Every Server plugin declares an absolute `baseDir`. Migrations, seeds, and Jobs resolve relative to it so compiled plugins use compiled resources. Migrations are explicit, self-contained, immutable after merge, and tested against a real database.
|
|
56
|
+
- Plugin test fixtures come from `@nocobase/app-testing/server`, `/client` or `/cli`, declared in `devDependencies`. Use the [test directory and fixture guide](references/testing.md#use-app-testing-in-a-plugin) to select the environment, register the production plugin and keep databases and storage isolated.
|
|
57
|
+
- Register Client, Server, and CLI exports explicitly in the corresponding target App composition roots. Installation, registration, Skills synchronization, and runtime behavior are separate facts; legacy manifest metadata is not runtime discovery.
|
|
58
|
+
- Plugin integration knowledge is authored in `<plugin>/skills/`; the target App's `.agents/skills/` is generated output. Editable UI is maintained in the UI Library; source installed into an App belongs to that App. This development Skill is maintained in `@nocobase/app-skills`, distinct from a plugin's own integration Skills.
|
|
59
|
+
- Follow the target project’s dependency rules: shared runtimes and client value imports are peers, ordinary server runtime imports are dependencies, and development-only imports are devDependencies. A type reference retained in published declarations needs a consumer-resolvable contract.
|
|
60
|
+
|
|
61
|
+
## Implementation workflow
|
|
62
|
+
|
|
63
|
+
1. Inspect working-tree changes, plugin manifests, declarations, exports, tests, and the target App. Identify the requested behavior and who owns its data, UI, services, and integration code.
|
|
64
|
+
2. Select capabilities and define the smallest public contracts: Client options/exports, Server Tokens/APIs, CLI commands, permission/error boundaries, and observable results. Use only the relevant references above.
|
|
65
|
+
3. Implement in the owning plugin. Put domain behavior in Services, HTTP boundaries in Routes, asynchronous orchestration in Jobs, React context in React Providers, and application integration instructions in Plugin Skills.
|
|
66
|
+
4. Keep declarations, source/publish exports, dependencies, published files, tests, README, and Plugin Skills consistent. Remove unused scaffold examples and drafts. Write each Markdown prose paragraph on one physical line, without manual line wrapping.
|
|
67
|
+
5. When integration is part of the request, preview and apply registration to the chosen App, synchronize applicable Skills, and validate the resulting behavior. Do not run creation, registration, migration, or other stateful commands merely because this Skill applies.
|
|
68
|
+
6. Follow [testing and delivery](references/testing.md): run the modified plugin's checks and relevant consumer checks, then verify the requested runtime workflow. `plugin inspect` is an optional read-only registration diagnostic, not a test or completion gate. Report results, skipped checks, and remaining limitations accurately.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
interface:
|
|
2
|
+
display_name: 'NocoBase Plugin Development'
|
|
3
|
+
short_description: 'Develop NocoBase v3 plugins'
|
|
4
|
+
default_prompt: 'Use $nocobase-app-plugin-development to plan or implement a NocoBase v3 plugin in this App or source workspace.'
|
|
5
|
+
policy:
|
|
6
|
+
allow_implicit_invocation: true
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { AppCommand } from '@nocobase/app-cli';
|
|
2
|
+
|
|
3
|
+
export default class CountEntries extends AppCommand {
|
|
4
|
+
static override summary = 'Count reading list entries.';
|
|
5
|
+
|
|
6
|
+
public async run(): Promise<{ count: number }> {
|
|
7
|
+
await this.parse(CountEntries);
|
|
8
|
+
const { readingListToken } = await import('../server/service.js');
|
|
9
|
+
return this.withApp(async ({ app }) => {
|
|
10
|
+
await app.start();
|
|
11
|
+
return { count: await app.container.resolve(readingListToken).count() };
|
|
12
|
+
});
|
|
13
|
+
}
|
|
14
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { defineCliPlugin, type AppCliPlugin } from '@nocobase/app-cli';
|
|
2
|
+
|
|
3
|
+
import CountEntries from './count.js';
|
|
4
|
+
|
|
5
|
+
const plugin: AppCliPlugin = defineCliPlugin({
|
|
6
|
+
packageName: '@example/app-plugin-reading-list',
|
|
7
|
+
commands: { count: CountEntries },
|
|
8
|
+
});
|
|
9
|
+
|
|
10
|
+
export default plugin;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import {
|
|
2
|
+
defineClientPlugin,
|
|
3
|
+
type AppClientPluginFactory,
|
|
4
|
+
} from '@nocobase/app-client/plugins';
|
|
5
|
+
|
|
6
|
+
import metadata from '../package.json' with { type: 'json' };
|
|
7
|
+
import locales from './locales/index.js';
|
|
8
|
+
|
|
9
|
+
const readingList: AppClientPluginFactory = defineClientPlugin({
|
|
10
|
+
packageName: metadata.name,
|
|
11
|
+
locales,
|
|
12
|
+
});
|
|
13
|
+
|
|
14
|
+
export default readingList;
|
|
15
|
+
export { ReadingList } from './reading-list.js';
|
|
16
|
+
export { readingListPageSize } from './public-config.js';
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { ReadingListResource } from './en-US.js';
|
|
2
|
+
|
|
3
|
+
const deDE: ReadingListResource = {
|
|
4
|
+
title: 'Leseliste',
|
|
5
|
+
loading: 'Einträge werden geladen…',
|
|
6
|
+
failed: 'Die Leseliste konnte nicht geladen werden.',
|
|
7
|
+
empty: 'Noch keine Einträge.',
|
|
8
|
+
};
|
|
9
|
+
|
|
10
|
+
export default deDE;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { LocaleResource } from '@nocobase/i18n';
|
|
2
|
+
|
|
3
|
+
const enUS = {
|
|
4
|
+
title: 'Reading list',
|
|
5
|
+
loading: 'Loading entries…',
|
|
6
|
+
failed: 'The reading list could not be loaded.',
|
|
7
|
+
empty: 'No entries yet.',
|
|
8
|
+
};
|
|
9
|
+
|
|
10
|
+
export type ReadingListResource = LocaleResource<typeof enUS>;
|
|
11
|
+
export default enUS;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { ReadingListResource } from './en-US.js';
|
|
2
|
+
|
|
3
|
+
const esES: ReadingListResource = {
|
|
4
|
+
title: 'Lista de lectura',
|
|
5
|
+
loading: 'Cargando entradas…',
|
|
6
|
+
failed: 'No se ha podido cargar la lista de lectura.',
|
|
7
|
+
empty: 'Todavía no hay entradas.',
|
|
8
|
+
};
|
|
9
|
+
|
|
10
|
+
export default esES;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { ReadingListResource } from './en-US.js';
|
|
2
|
+
|
|
3
|
+
const frFR: ReadingListResource = {
|
|
4
|
+
title: 'Liste de lecture',
|
|
5
|
+
loading: 'Chargement des entrées…',
|
|
6
|
+
failed: 'Impossible de charger la liste de lecture.',
|
|
7
|
+
empty: 'Aucune entrée pour le moment.',
|
|
8
|
+
};
|
|
9
|
+
|
|
10
|
+
export default frFR;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { LocaleLoaders } from '@nocobase/i18n';
|
|
2
|
+
|
|
3
|
+
const locales: LocaleLoaders = {
|
|
4
|
+
'en-US': () => import('./en-US.js'),
|
|
5
|
+
'zh-CN': () => import('./zh-CN.js'),
|
|
6
|
+
'zh-TW': () => import('./zh-TW.js'),
|
|
7
|
+
'ja-JP': () => import('./ja-JP.js'),
|
|
8
|
+
'es-ES': () => import('./es-ES.js'),
|
|
9
|
+
'pt-BR': () => import('./pt-BR.js'),
|
|
10
|
+
'fr-FR': () => import('./fr-FR.js'),
|
|
11
|
+
'de-DE': () => import('./de-DE.js'),
|
|
12
|
+
'vi-VN': () => import('./vi-VN.js'),
|
|
13
|
+
'id-ID': () => import('./id-ID.js'),
|
|
14
|
+
};
|
|
15
|
+
|
|
16
|
+
export default locales;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { ReadingListResource } from './en-US.js';
|
|
2
|
+
|
|
3
|
+
const ptBR: ReadingListResource = {
|
|
4
|
+
title: 'Lista de leitura',
|
|
5
|
+
loading: 'Carregando itens…',
|
|
6
|
+
failed: 'Não foi possível carregar a lista de leitura.',
|
|
7
|
+
empty: 'Nenhum item ainda.',
|
|
8
|
+
};
|
|
9
|
+
|
|
10
|
+
export default ptBR;
|