@nocobase/app-skills 0.1.0-beta.52 → 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 +2 -0
- package/skills/nocobase-app-development/references/plugins.md +20 -2
- 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 +5 -1
- package/skills/nocobase-app-upgrade/references/edge-cases.md +2 -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.
|
|
@@ -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,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;
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { ClientApplication } from '@nocobase/app-client';
|
|
2
|
+
|
|
3
|
+
declare module '@nocobase/app-client' {
|
|
4
|
+
interface PublicAppConfig {
|
|
5
|
+
readingList: { pageSize?: number };
|
|
6
|
+
}
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
export function readingListPageSize(
|
|
10
|
+
app: Pick<ClientApplication, 'config'>,
|
|
11
|
+
): number {
|
|
12
|
+
return app.config.public.get('readingList.pageSize', 20);
|
|
13
|
+
}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { useApiClient } from '@nocobase/app-client';
|
|
2
|
+
import { useTranslation } from '@nocobase/i18n/client';
|
|
3
|
+
import { useEffect, useState, type ReactElement } from 'react';
|
|
4
|
+
|
|
5
|
+
import metadata from '../package.json' with { type: 'json' };
|
|
6
|
+
|
|
7
|
+
interface Entry {
|
|
8
|
+
readonly id: string;
|
|
9
|
+
readonly title: string;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
type State =
|
|
13
|
+
| { readonly status: 'loading' }
|
|
14
|
+
| { readonly status: 'ready'; readonly entries: readonly Entry[] }
|
|
15
|
+
| { readonly status: 'error' };
|
|
16
|
+
|
|
17
|
+
export function ReadingList(): ReactElement {
|
|
18
|
+
const api = useApiClient();
|
|
19
|
+
// Public components may be rendered outside the plugin's own route subtree.
|
|
20
|
+
const { t } = useTranslation(metadata.name);
|
|
21
|
+
const [state, setState] = useState<State>({ status: 'loading' });
|
|
22
|
+
|
|
23
|
+
useEffect(() => {
|
|
24
|
+
let current = true;
|
|
25
|
+
api.request<{ data: Entry[] }>({ path: 'readingList', method: 'GET' }).then(
|
|
26
|
+
(response) => {
|
|
27
|
+
if (current) setState({ status: 'ready', entries: response.data });
|
|
28
|
+
},
|
|
29
|
+
() => {
|
|
30
|
+
if (current) setState({ status: 'error' });
|
|
31
|
+
},
|
|
32
|
+
);
|
|
33
|
+
return (): void => {
|
|
34
|
+
current = false;
|
|
35
|
+
};
|
|
36
|
+
}, [api]);
|
|
37
|
+
|
|
38
|
+
return (
|
|
39
|
+
<section aria-label={t('title')}>
|
|
40
|
+
<h2>{t('title')}</h2>
|
|
41
|
+
{state.status === 'loading' ? <p role='status'>{t('loading')}</p> : null}
|
|
42
|
+
{state.status === 'error' ? <p role='alert'>{t('failed')}</p> : null}
|
|
43
|
+
{state.status === 'ready' ? (
|
|
44
|
+
state.entries.length === 0 ? (
|
|
45
|
+
<p>{t('empty')}</p>
|
|
46
|
+
) : (
|
|
47
|
+
<ul>
|
|
48
|
+
{state.entries.map((entry) => (
|
|
49
|
+
<li key={entry.id}>{entry.title}</li>
|
|
50
|
+
))}
|
|
51
|
+
</ul>
|
|
52
|
+
)
|
|
53
|
+
) : null}
|
|
54
|
+
</section>
|
|
55
|
+
);
|
|
56
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { defineMigration, type MigrationDefinition } from '@nocobase/db';
|
|
2
|
+
|
|
3
|
+
const migration: MigrationDefinition = defineMigration({
|
|
4
|
+
name: '202610180001_reading_list',
|
|
5
|
+
async up({ builder }) {
|
|
6
|
+
await builder.createCollection('readingListEntries', (collection) => {
|
|
7
|
+
collection.string('id', { primaryKey: true });
|
|
8
|
+
collection.string('title', { nullable: false, length: 255 });
|
|
9
|
+
});
|
|
10
|
+
},
|
|
11
|
+
async down({ builder }) {
|
|
12
|
+
await builder.dropCollection('readingListEntries');
|
|
13
|
+
},
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
export default migration;
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@example/app-plugin-reading-list",
|
|
3
|
+
"private": true,
|
|
4
|
+
"type": "module",
|
|
5
|
+
"prettier": "@nocobase/dev-config/prettier",
|
|
6
|
+
"exports": {
|
|
7
|
+
"./server": "./server/index.ts",
|
|
8
|
+
"./client": "./client/index.ts",
|
|
9
|
+
"./cli": "./cli/index.ts",
|
|
10
|
+
"./config": "./server/config.ts"
|
|
11
|
+
},
|
|
12
|
+
"scripts": {
|
|
13
|
+
"lint": "eslint . --max-warnings 0",
|
|
14
|
+
"typecheck": "tsc --noEmit",
|
|
15
|
+
"test": "vitest run"
|
|
16
|
+
},
|
|
17
|
+
"devDependencies": {
|
|
18
|
+
"@nocobase/app-cli": "workspace:*",
|
|
19
|
+
"@nocobase/app-client": "workspace:*",
|
|
20
|
+
"@nocobase/app-plugin-authentication": "workspace:*",
|
|
21
|
+
"@nocobase/app-plugin-authorization": "workspace:*",
|
|
22
|
+
"@nocobase/app-server": "workspace:*",
|
|
23
|
+
"@nocobase/app-testing": "workspace:*",
|
|
24
|
+
"@nocobase/authorization": "workspace:*",
|
|
25
|
+
"@nocobase/db": "workspace:*",
|
|
26
|
+
"@nocobase/db-sqlite": "workspace:*",
|
|
27
|
+
"@nocobase/dev-config": "workspace:*",
|
|
28
|
+
"@nocobase/i18n": "workspace:*",
|
|
29
|
+
"@nocobase/service-provider": "workspace:*",
|
|
30
|
+
"@oclif/core": "catalog:",
|
|
31
|
+
"@testing-library/jest-dom": "catalog:",
|
|
32
|
+
"@testing-library/react": "catalog:",
|
|
33
|
+
"@types/node": "catalog:",
|
|
34
|
+
"@types/react": "catalog:",
|
|
35
|
+
"@types/react-dom": "catalog:",
|
|
36
|
+
"@vitejs/plugin-react": "catalog:",
|
|
37
|
+
"eslint": "catalog:",
|
|
38
|
+
"hono": "catalog:",
|
|
39
|
+
"jsdom": "catalog:",
|
|
40
|
+
"prettier": "catalog:",
|
|
41
|
+
"react": "catalog:",
|
|
42
|
+
"react-dom": "catalog:",
|
|
43
|
+
"react-router": "catalog:",
|
|
44
|
+
"typescript": "catalog:",
|
|
45
|
+
"vite": "catalog:",
|
|
46
|
+
"vitest": "catalog:",
|
|
47
|
+
"zod": "catalog:"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import {
|
|
2
|
+
defineAppConfig,
|
|
3
|
+
envInteger,
|
|
4
|
+
envString,
|
|
5
|
+
type AppConfigFactory,
|
|
6
|
+
} from '@nocobase/app-server/config';
|
|
7
|
+
|
|
8
|
+
export interface ReadingListConfig {
|
|
9
|
+
readonly pageSize: number;
|
|
10
|
+
readonly integrationKey?: string;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export function defineReadingListConfig(): AppConfigFactory<ReadingListConfig> {
|
|
14
|
+
return defineAppConfig<ReadingListConfig>({
|
|
15
|
+
defaults: { pageSize: 20 },
|
|
16
|
+
env: {
|
|
17
|
+
READING_LIST_PAGE_SIZE: envInteger('pageSize'),
|
|
18
|
+
READING_LIST_INTEGRATION_KEY: envString('integrationKey', {
|
|
19
|
+
secret: true,
|
|
20
|
+
}),
|
|
21
|
+
},
|
|
22
|
+
public: ['pageSize'],
|
|
23
|
+
validate(value, context) {
|
|
24
|
+
if (
|
|
25
|
+
!Number.isInteger(value.pageSize) ||
|
|
26
|
+
value.pageSize < 1 ||
|
|
27
|
+
value.pageSize > 100
|
|
28
|
+
) {
|
|
29
|
+
context.error('pageSize', 'must be an integer from 1 to 100.');
|
|
30
|
+
}
|
|
31
|
+
if (
|
|
32
|
+
value.integrationKey !== undefined &&
|
|
33
|
+
typeof value.integrationKey !== 'string'
|
|
34
|
+
) {
|
|
35
|
+
context.error('integrationKey', 'must be a string.');
|
|
36
|
+
}
|
|
37
|
+
},
|
|
38
|
+
});
|
|
39
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
|
|
3
|
+
import {
|
|
4
|
+
defineServerPlugin,
|
|
5
|
+
type AppServerPlugin,
|
|
6
|
+
} from '@nocobase/app-server/plugins';
|
|
7
|
+
|
|
8
|
+
import metadata from '../package.json' with { type: 'json' };
|
|
9
|
+
import serviceProviders from './providers/index.js';
|
|
10
|
+
import { readingListRoutes } from './routes.js';
|
|
11
|
+
|
|
12
|
+
const plugin: AppServerPlugin = defineServerPlugin({
|
|
13
|
+
packageName: metadata.name,
|
|
14
|
+
baseDir: path.resolve(import.meta.dirname, '..'),
|
|
15
|
+
database: { migrations: './database/migrations' },
|
|
16
|
+
serviceProviders,
|
|
17
|
+
routes: [readingListRoutes],
|
|
18
|
+
});
|
|
19
|
+
|
|
20
|
+
export default plugin;
|
|
21
|
+
export { defineReadingListConfig, type ReadingListConfig } from './config.js';
|
|
22
|
+
export { readingListToken, type ReadingEntry } from './service.js';
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { authorizationToken } from '@nocobase/app-plugin-authorization';
|
|
2
|
+
import type { AppPluginApplication } from '@nocobase/app-server/plugins';
|
|
3
|
+
import { databaseManagerToken } from '@nocobase/db';
|
|
4
|
+
import { ServiceProvider } from '@nocobase/service-provider';
|
|
5
|
+
|
|
6
|
+
import type { ReadingListConfig } from './config.js';
|
|
7
|
+
import { ReadingListService, readingListToken } from './service.js';
|
|
8
|
+
|
|
9
|
+
export class ReadingListProvider extends ServiceProvider<AppPluginApplication> {
|
|
10
|
+
public readonly name: string = '@example/app-plugin-reading-list';
|
|
11
|
+
|
|
12
|
+
public override register(): void {
|
|
13
|
+
this.app.container.singleton(readingListToken, (resolver) => {
|
|
14
|
+
const config = this.app.config.get<ReadingListConfig>('readingList');
|
|
15
|
+
if (!config)
|
|
16
|
+
throw new Error(
|
|
17
|
+
'Register defineReadingListConfig() under readingList.',
|
|
18
|
+
);
|
|
19
|
+
return new ReadingListService(
|
|
20
|
+
resolver.resolve(databaseManagerToken),
|
|
21
|
+
config.pageSize,
|
|
22
|
+
);
|
|
23
|
+
});
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
public override async boot(): Promise<void> {
|
|
27
|
+
const authz = this.app.container.resolve(authorizationToken);
|
|
28
|
+
authz.resourceTypes.add({ type: 'readingList', actions: ['read'] });
|
|
29
|
+
authz.ui.defaultSection('readingList', 'business');
|
|
30
|
+
}
|
|
31
|
+
}
|