#Build and Package

After plugin development is complete, you need to go through two steps — build (compile source code) and package (generate .tar.gz) — before distributing it to other NocoBase applications.

#Build Plugin

Building compiles the TypeScript source code under src/ into JavaScript — client-side code is bundled by Rsbuild, and server-side code is bundled by tsup:

yarn build @my-project/plugin-hello

Build artifacts are output to the dist/ directory under the plugin root.

#Package Plugin

Packaging compresses the build artifacts into a .tar.gz file for easy upload to other environments:

yarn nocobase tar @my-project/plugin-hello

The package file is output to storage/tar/@my-project/plugin-hello.tar.gz by default.

You can also combine build and package into one step using the --tar flag:

yarn build @my-project/plugin-hello --tar

#Upload to Other NocoBase Applications

Upload and extract the .tar.gz file to the target application's ./storage/plugins directory. For detailed steps, see Install and Upgrade Plugins.

#Enable a Plugin by Default

After uploading, the plugin is not activated automatically — it appears in the Plugin Manager and must be enabled manually. If you are maintaining your own NocoBase application and want the plugin to be enabled by default along with the application, you can use the APPEND_PRESET_BUILT_IN_PLUGINS (append built-in plugins) environment variable. See Make a Plugin Preset or Built-in by Default for usage.

#Custom Build Configuration

In most cases, the default build configuration is sufficient. If you need to customize it — such as modifying the bundle entry, adding aliases, adjusting compression options, etc. — you can create a build.config.ts file in the plugin root directory:

import { defineConfig } from '@nocobase/build';

export default defineConfig({
  modifyRsbuildConfig: (config) => {
    // Modify client-side (src/client-v2) Rsbuild bundling configuration
    // Reference: https://rsbuild.rs/guide/configuration/rsbuild
    return config;
  },
  modifyTsupConfig: (config) => {
    // Modify server-side (src/server) tsup bundling configuration
    // Reference: https://tsup.egoist.dev/#using-custom-configuration
    return config;
  },
  beforeBuild: (log) => {
    // Callback before build starts, e.g., cleaning temporary files, generating code, etc.
  },
  afterBuild: (log) => {
    // Callback after build completes, e.g., copying extra resources, outputting statistics, etc.
  },
});

Key points:

• modifyRsbuildConfig — Used to adjust client-side bundling, such as adding Rsbuild plugins, modifying resolve aliases, adjusting code splitting strategies, etc. See the Rsbuild documentation for configuration options.
• modifyTsupConfig — Used to adjust server-side bundling, such as modifying target, externals, entry, etc. See the tsup documentation for configuration options.
• beforeBuild / afterBuild — Hooks before and after the build, receiving a log function for output. For example, generate code files in beforeBuild, or copy static resources to the output directory in afterBuild.

#Related Links

• Write Your First Plugin — Create a plugin from scratch, including the complete build and package workflow
• Project Structure — Understand the role of directories like packages/plugins, storage/tar, etc.
• Dependency Management — Plugin dependency declarations and global dependencies
• Plugin Development Overview — Overall introduction to plugin development
• Install and Upgrade Plugins — Upload packaged files to target environments
• Environment Variables — Environment variable configuration for preset and built-in plugins