Use the NocoBase 3 Repository API example plugin to demonstrate array and streamed findMany queries, CRM and order CRUD, relation reads and writes, optimistic locking, atomic numeric updates, and aggr
1---2name: nocobase-app-plugin-repository-example3description: Use the NocoBase 3 Repository API example plugin to demonstrate array and streamed findMany queries, CRM and…4---56# packages/examples/app-plugin-repository-example/skills/nocobase-app-plugin-repository-example/SKILL.md
N
SKILL.mdAgent skill
Transport
File
Status
Listed
SKILL.md
Install
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
shterminal
1npx skills add nocobase/nocobase --skill nocobase-app-plugin-repository-example -a cursor -y
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
shterminal
1npx skills add nocobase/nocobase --skill nocobase-app-plugin-repository-example -a grok -y
Send the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
txtGrok Bot chat
1Install this skill: https://github.com/nocobase/nocobase/tree/HEAD/packages/examples/app-plugin-repository-example/skills/nocobase-app-plugin-repository-example
Use the NocoBase 3 Repository API example plugin to demonstrate array and streamed findMany queries, CRM and order CRUD, relation reads and writes, optimistic locking, atomic numeric updates, and aggregate queries.
How do I install nocobase-app-plugin-repository-example?
Download packages/examples/app-plugin-repository-example/skills/nocobase-app-plugin-repository-example/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does nocobase-app-plugin-repository-example live?
The publisher keeps it at https://github.com/nocobase/nocobase.
Which agents can use nocobase-app-plugin-repository-example?
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.
From the publisher
SKILL.md
name
nocobase-app-plugin-repository-example
description
Use the NocoBase 3 Repository API example plugin to demonstrate array and streamed findMany queries, CRM and order CRUD, relation reads and writes, optimistic locking, atomic numeric updates, and aggregate queries.
Repository example
This plugin owns thirteen isolated example collections, five authenticated list pages, and four API example pages in three sidebar groups, each CRUD entity having a detail child route. Use it when explaining or trying the Repository HTTP adapter. Do not use it as a production CRM or modify its tables to store unrelated application data.
Prerequisites and registration
The application must register @nocobase/app-plugin-authentication and this plugin on the Server, and this plugin's Client factory. It needs the normal apiClientToken and a working database. Apply application migrations and seeds before opening the pages. In this repository:
Server definition: @nocobase/app-plugin-repository-example/server.
CRM group: customers at /repository-example/crm, contacts at /repository-example/crm/contacts.
Orders group: orders at /repository-example/orders, items at /repository-example/orders/items, products at /repository-example/orders/products. Paths are relative to the application mount point; each entity has its own URL.
Detail routes append /details/:recordId to the list path. New and Edit use a right-side drawer; errors preserve input, and successful saves refresh the current page.
Relationship-write page: /repository-example/relation-mutations, in the Repository examples group. Seven independent cards each provide preparation, a form, a target table, a request preview and the last executed response for create/connect/disconnect/set/update/upsert/delete. Choose hasOne profile, hasMany tasks or belongsToMany tags; set is to-many only (20 supported combinations). Preparation creates a fresh project and four isolated targets, requires migrations but no seeds, and retains old records when repeated. Page load performs no writes. Target tables distinguish association state from record existence, retain absent rows after delete and show through.role. Tag create/connect/set expose a role input. Upsert can update the same target on repeated execution; set checkboxes may all be cleared. Each root HTTP mutation is transactional; multi-request preparation is not. Write failures preserve inputs; refresh failures after a successful write require a read-only table refresh. The page calls only through authenticated routes. See .
api.repository(name)
client/relation-lab.ts
findMany page: /repository-example/find-many, in the Repository examples group. It queries repositoryExampleFindManyRecords, initialized with 24 deterministic records. The two panels execute identical sorted queries: await repository.findMany(options) requests JSON and returns an array, while for await (const record of repository.findMany(options)) requests framed NDJSON and yields records as they arrive. Create a new query for each consumption mode; one query cannot mix modes.
Atomic update page: /repository-example/atomic, in the Repository examples group. It uses repositoryExampleAtomicCounters, initialized by a separate migration and seed with stock, wallet, points and visits records. It demonstrates increment, guarded decrement, multiply and ten concurrent increments. Mutations use numeric operation objects; never read and send an absolute replacement value. Concurrent requests commit independently, and failed requests are not automatically retried.
Aggregate page: /repository-example/aggregate, in the Repository examples group. It reuses existing seeds and shows item COUNT/SUM/AVG/MIN/MAX, status-filtered order counts, product groupBy with HAVING and sorting, and customer relation counts (first 50 customers, including zero). The status filter affects every panel; minimum quantity affects only grouped products. It calls api.repository(name).aggregate() and .groupBy() using JSON ASTs through authenticated defineRepositoryApiRoutes actions. The example-specific GET endpoint has been removed. The actual requests are in client/aggregate.ts, with product lookup batches of 100. Enum status counts use one groupBy query with exact member identity, including case and trailing spaces. Enum field sorting remains unsupported; the page uses aggregate sorting and explicit presentation order. Prices are cents; AVG is unweighted; empty-set sums and price metrics are NULL; separate panel queries are not a single snapshot.
Additional groupBy panels on the Aggregate page: customer order ranking (customerId), customer × enum status (customerId, status), and product × snapshot price (productId, unitPriceCents). The status filter applies before grouping; a separate minimum row count applies HAVING to each group in these three panels. Existing minimum quantity affects only the original product summary. Show friendly names and detail links, plus each panel's actual AST and raw results. With seed data, minimum count 2 retains Ada in ranking and USB-C Dock in product/price while customer/status is empty. Implementation is in client/group-by.ts; no new schema or seeds are needed.
Select combine page: /repository-example/select-combine in Repository examples. Five read-only cards run real findMany JSON ASTs: order preview/count/status branches, item records and COUNT/SUM/AVG/MIN/MAX, nested orders/items/product includes, shared draft-task filtering plus branch-local null filtering, and many-to-many tag records/counts. Requests are visible before execution; results show field-path columns and nested tables for record branches, with raw JSON in a collapsible panel. NULL, zero and empty relations are displayed distinctly. Queries show the first 10 roots by ID; branch limits apply per parent. Empty relations retain empty lists and zero counts, with null non-count aggregates. Reuses existing CRM and relationship seeds. Definitions live in client/select-combine.ts.
Sort page: /repository-example/sort under Repository examples. Fifteen read-only cards cover default/ascending/descending/multi-field order, automatic primary-key ties, NULL placement, to-one paths, count/sum/avg/min/max relation sorting, independent include order, and two expected INVALID_SORT cases (duplicate targets and direct to-many paths). Builder snippets and actual serialized JSON AST requests accompany response-order tables and raw JSON. Relation aggregates are selected explicitly; filtered projections do not change sort scope. Empty sort SUM is 0 while selected SUM is NULL. Reuses existing seeds, with at most 10 root records. See client/sort.ts.
Actions: findMany, findOne, count, exists, createOne, updateOne, deleteOne, aggregate, groupBy, through the injected API client's repository(name).
Create customers and products first, then contacts and orders. The new-order drawer supports item rows with product selection, default product prices, editable quantity/prices, and totals. Submit the order and items.create rows through one atomic createOne request. Detail reads include items.product to display product name and SKU alongside snapshot prices. Use the separate Order items page to manage existing items. Relations support connect: { id }; detail reads use JSON select AST includes. Related records use singular/plural headings matching the relation cardinality and link to their detail pages. Customer cards display name, company and email. Prices are integer cents. The UI shows request/result examples in Repository calls.
Every signed-in user can manage all example records. The API has no per-role or tenant rules. A production adaptation must explicitly design its own authorization boundary. Orders use optimistic locking: preserve version when editing and send ifVersion, handling 409 by refreshing rather than overwriting. Deletes cascade contacts/items but refuse to remove customers with orders or products with items.
Ownership and verification
The plugin owns its migrations, components, routes and locale strings. An application reaches it through public package exports; do not import private source paths. The plugin seed inserts 4 customers, 5 contacts, 6 products, 4 orders and 8 order items with stable demo IDs, plus 4 numeric counters, 24 findMany records and the prefixed relationship baseline from separate seeds. Completed seeds are skipped; user edits and deletions remain intact. All inserts are transactional, and existing identities are never overwritten. For schema changes create a new self-contained migration after the existing one has shipped.
Verify migration success, authenticated navigation, a customer/product/order/item lifecycle, relation details, and conflict handling. The plugin's check runs lint, formatting, typecheck, real database/HTTP/page tests and build. The README documents the complete API and schema.
Repository route actions use configuration objects (findMany: { maxLimit: 100 },
findOne: {}) and say only which endpoints exist. What they may do is the
exposure's policy, which is required: a Repository Policy with read,
create, update and delete, written out or built with
buildRepositoryPolicy, where a node never mentioned is denied. Nested task
create/update/upsert branches have separate field rules; task creation
explicitly permits assignee.connect. Many-to-many tag operations permit only
the role through field. Prefer relation connect when the Policy grants it;
direct foreign-key fields are not implicitly writable. Keep Policies on the
server and never include them in client request options — a request carrying
policy or scope is rejected. New demos need their own Policy and route
tests. Authentication guards every endpoint. Internal db.repository calls bind
no Policy, so a custom HTTP handler is responsible for its own.