nocobase-app-plugin-file

Implements file uploads, downloads, and attachment management in NocoBase 3 applications.

9|3|Updated Aug 14, 2026
One-click install
npx skills add https://github.com/nocobase/nocobase3 --skill nocobase-app-plugin-file-nocobase
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: nocobase-app-plugin-file
Source: https://github.com/nocobase/nocobase3/tree/main/packages/plugins/app-plugin-file/skills/nocobase-app-plugin-file
Command: npx skills add https://github.com/nocobase/nocobase3 --skill nocobase-app-plugin-file-nocobase

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Building file handling into a NocoBase 3 App requires wiring together collections, migrations, storage disks, API routes, access policies, and UI components by hand. This Skill guides the complete integration of the app-plugin-file package so uploads, downloads, and business attachments work correctly with the App's own security model. ## Core Features & Use Cases - File Collection & Migration Setup: Creates App-owned migrations defining the fixed file metadata schema (disk, key, filename, mimeType, size, timestamps) on any database connection. - Repository API Routes: Declares upload, query, and delete endpoints with Repository Policies that scope rows per principal and stamp ownership defaults onto uploaded files. - Server & Client Services: Resolves file repository managers from the App container for uploads, URL generation, and CRUD without creating duplicate database or Drive instances. - Registry UI Components: Materializes editable FileUploadField, FileList, thumbnail, and preview components into the App's React workspace. - Use Case: Add an invoice attachments feature where users upload PDFs to a local disk, list them in a form, preview content, and enforce per-user access policies on both API and content routes. ## Quick Start Add file upload and attachment management to my NocoBase App using the app-plugin-file package, with an invoice_files collection, secured upload routes, and editable upload UI components.

Frequently Asked Questions about nocobase-app-plugin-file

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add file upload to a NocoBase 3 App?▼

Register the app-plugin-file server and client plugins, create a migration defining the fixed file collection schema, then declare routes with defineFileRepositoryApiRoutes specifying collection, disk, accessPath, and policy. Uploads generate IDs, storage keys, and timestamps automatically.

How do I restrict file access per user in NocoBase file routes?▼

Pass a policy function of the principal together with a principal(context) resolver to scope rows per caller; without a principal the request is refused with 403. The content route under accessPath is public, so register App-owned authentication on those paths separately.

What fields does a NocoBase file collection require?▼

The schema is fixed: a UUID primary key, disk, key, filename, ext, mimeType, size, createdAt, and updatedAt. Field mapping is unsupported, and extra required columns need defaults because uploads accept no business values.

Why does my NocoBase file upload return BODY_TOO_LARGE?▼

Default upload limits are 5 MiB for a single file and 20 MiB for a batch, covering the entire multipart body including overhead. Reduce the request size or adjust the maxSize values in the route action configuration.

Does NocoBase file plugin support resumable uploads or file cleanup?▼

No. There is no built-in resumable upload, idempotency key, physical object cleanup, Range support, or malware scanning. Metadata deletion retains stored objects, so implement business-owned orphan cleanup and referenced-file deletion policies.