From 00c90de97f192128f78a7ee7b236f205d30be59f Mon Sep 17 00:00:00 2001 From: PiEgg Date: Fri, 29 May 2026 21:40:51 +0800 Subject: [PATCH] docs: update docs about enabling plugins by default (#9625) --- docs/docs/cn/get-started/installation/env.md | 8 +-- docs/docs/cn/plugin-development/build.md | 5 ++ .../write-your-first-plugin.md | 30 ++++++++++- docs/docs/de/get-started/installation/env.md | 4 ++ docs/docs/de/plugin-development/build.md | 13 +++++ .../write-your-first-plugin.md | 42 ++++++++++++++- docs/docs/en/get-started/installation/env.md | 8 ++- docs/docs/en/plugin-development/build.md | 5 ++ .../write-your-first-plugin.md | 28 ++++++++++ docs/docs/es/get-started/installation/env.md | 8 +-- docs/docs/es/plugin-development/build.md | 53 ++++++++++++++++++- .../write-your-first-plugin.md | 42 ++++++++++++++- docs/docs/fr/get-started/installation/env.md | 4 ++ docs/docs/fr/plugin-development/build.md | 5 ++ .../write-your-first-plugin.md | 28 ++++++++++ docs/docs/id/get-started/installation/env.md | 12 +++-- docs/docs/id/plugin-development/build.md | 5 ++ .../write-your-first-plugin.md | 30 ++++++++++- docs/docs/ja/get-started/installation/env.md | 6 ++- docs/docs/ja/plugin-development/build.md | 5 ++ .../write-your-first-plugin.md | 28 ++++++++++ docs/docs/pt/get-started/installation/env.md | 4 ++ docs/docs/pt/plugin-development/build.md | 51 ++++++++++++++++++ .../write-your-first-plugin.md | 42 ++++++++++++++- docs/docs/ru/get-started/installation/env.md | 4 ++ docs/docs/ru/plugin-development/build.md | 13 +++++ .../write-your-first-plugin.md | 42 ++++++++++++++- docs/docs/vi/get-started/installation/env.md | 6 ++- docs/docs/vi/plugin-development/build.md | 5 ++ .../write-your-first-plugin.md | 28 ++++++++++ 30 files changed, 540 insertions(+), 24 deletions(-) diff --git a/docs/docs/cn/get-started/installation/env.md b/docs/docs/cn/get-started/installation/env.md index 7fed6e216e6..0e94fe1cfee 100644 --- a/docs/docs/cn/get-started/installation/env.md +++ b/docs/docs/cn/get-started/installation/env.md @@ -388,7 +388,8 @@ SERVER_REQUEST_WHITELIST=1.2.3.4,10.0.0.0/8,api.example.com,*.trusted.com 1. 需要确保插件已经下载到本地，并且在 `node_modules` 目录里可以找到，更多内容查看 [插件的组织方式](/plugin-development/project-structure)。 2. 添加了环境变量后，需要在初始化安装 `nocobase install` 或升级 `nocobase upgrade` 后才会在插件管理器页面里显示。 - ::: + +::: ```bash APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar @@ -402,7 +403,8 @@ APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar 1. 需要确保插件已经下载到本地，并且在 `node_modules` 目录里可以找到，更多内容查看 [插件的组织方式](/plugin-development/project-structure)。 2. 添加了环境变量后，需要在初始化安装 `nocobase install` 或升级 `nocobase upgrade` 时会自动安装或升级插件。 - ::: + +::: ```bash APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar @@ -484,7 +486,7 @@ yarn cross-env \ ### WORKFLOW_SCRIPT_MODULES -工作流 JavaScript 节点可用的模块列表，详情查看「[JavaScript 节点：使用外部模块](/workflow/nodes/javascript#使用外部模块)」。 +工作流 JavaScript 节点可用的模块列表，详情查看「[JavaScript 节点：使用外部模块](/workflow/nodes/javascript#非安全模式需要模块支持)」。 ### WORKFLOW_LOOP_LIMIT diff --git a/docs/docs/cn/plugin-development/build.md b/docs/docs/cn/plugin-development/build.md index 0939decdf4c..8f93de253a8 100644 --- a/docs/docs/cn/plugin-development/build.md +++ b/docs/docs/cn/plugin-development/build.md @@ -44,6 +44,10 @@ yarn build @my-project/plugin-hello --tar 把 `.tar.gz` 文件上传并解压到目标应用的 `./storage/plugins` 目录即可。详细步骤见 [安装与升级插件](../get-started/install-upgrade-plugins.mdx)。 +### 默认启用插件 + +上传后插件默认不会自动激活——它会出现在「插件管理器」里，需要手动开启。如果你在维护自己的 NocoBase 应用，希望插件随应用一起默认启用，可以用 `APPEND_PRESET_BUILT_IN_PLUGINS`（追加默认内置插件）环境变量控制，用法见[让插件默认预置或默认启用](./write-your-first-plugin.md#让插件默认预置或默认启用可选)。 + ## 自定义构建配置 通常来说默认的构建配置就够用了。如果你需要自定义——比如修改打包入口、添加别名、调整压缩选项等——可以在插件根目录下创建 `build.config.ts` 文件： @@ -84,3 +88,4 @@ export default defineConfig({ - [依赖管理](./dependency-management.md) — 插件的依赖声明与全局依赖 - [插件开发概述](./index.md) — 插件开发整体介绍 - [安装与升级插件](../get-started/install-upgrade-plugins.mdx) — 把打包文件上传到目标环境 +- [环境变量](../get-started/installation/env.md) — 预置、内置插件等环境变量配置 diff --git a/docs/docs/cn/plugin-development/write-your-first-plugin.md b/docs/docs/cn/plugin-development/write-your-first-plugin.md index 3b3529f46e4..346eae5ce6e 100644 --- a/docs/docs/cn/plugin-development/write-your-first-plugin.md +++ b/docs/docs/cn/plugin-development/write-your-first-plugin.md @@ -118,6 +118,33 @@ export default { ![20250928174529](https://static-docs.nocobase.com/20250928174529.png) +### 让插件默认预置或默认启用（可选） + +上面讲的是手动开启单个插件。如果你在维护自己的 NocoBase 应用，希望某些插件在执行 `nocobase install`（首次安装）或 `nocobase upgrade`（升级）后就自动准备好，可以用两个环境变量来控制插件的默认状态： + +- **`APPEND_PRESET_LOCAL_PLUGINS`（追加默认预置插件）** — 把插件加入预置的本地插件列表，安装后出现在「插件管理器」里，但默认不激活，需要你手动开启 +- **`APPEND_PRESET_BUILT_IN_PLUGINS`（追加默认内置插件）** — 把插件加入内置插件列表，安装时自动激活，而且作为内置插件，**在「插件管理器」里不能被停用或删除** + +两个变量的值都是插件包名（`package.json` 里的 `name`），多个插件用英文逗号分隔。在 `.env` 里这样配置： + +```bash +# 默认预置：出现在插件管理器列表，但不自动激活 +APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world + +# 默认启用：自动安装并激活，且不能在界面停用 +APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world +``` + +通常来说，本地开发调试用前面的 `yarn pm enable` 就够了。这两个变量更适合「开箱即用」的发行场景——比如你打包了一套带固定插件的 NocoBase 应用，想让插件在初始化后直接可用。 + +:::tip 提示 + +- 插件要已经下载到本地、能在 `node_modules` 里被解析到，参考[项目目录结构](./project-structure.md) +- 配置后需要重新执行 `nocobase install` 或 `nocobase upgrade` 才会生效 +- 完整的环境变量说明见[环境变量](../get-started/installation/env.md#append_preset_local_plugins) + +::: + ## 第 4 步：构建与打包 当你准备把插件分发到其他环境时，需要先构建再打包： @@ -157,4 +184,5 @@ yarn nocobase tar @my-project/plugin-hello - [Test 测试](./server/test.md) — 编写服务端插件测试用例 - [使用 create-nocobase-app 安装](../get-started/installation/create-nocobase-app) — NocoBase 安装方式之一 - [从 Git 源码安装](../get-started/installation/git) — 从源码安装 NocoBase -- [安装与升级插件](../get-started/install-upgrade-plugins.mdx) — 把打包后的插件上传到其他环境 \ No newline at end of file +- [安装与升级插件](../get-started/install-upgrade-plugins.mdx) — 把打包后的插件上传到其他环境 +- [环境变量](../get-started/installation/env.md) — 预置、内置插件等环境变量配置 \ No newline at end of file diff --git a/docs/docs/de/get-started/installation/env.md b/docs/docs/de/get-started/installation/env.md index 14bb4628b63..dc4b60e3ea4 100644 --- a/docs/docs/de/get-started/installation/env.md +++ b/docs/docs/de/get-started/installation/env.md @@ -374,8 +374,10 @@ Unterstützte Formate: Dient zum Anhängen vordefinierter, nicht aktivierter **Plugins**. Der Wert ist der Paketname (der `name`-Parameter in `package.json`), wobei mehrere **Plugins** durch Kommas getrennt werden. :::info + 1. Stellen Sie sicher, dass das **Plugin** lokal heruntergeladen wurde und im Verzeichnis `node_modules` gefunden werden kann. Weitere Details finden Sie unter [**Plugin**-Organisation](/plugin-development/project-structure). 2. Nachdem Sie die Umgebungsvariable hinzugefügt haben, wird das **Plugin** auf der **Plugin**-Manager-Seite erst nach einer Erstinstallation (`nocobase install`) oder einem Upgrade (`nocobase upgrade`) angezeigt. + ::: ```bash @@ -387,8 +389,10 @@ APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar Dient zum Anhängen integrierter **Plugins**, die standardmäßig installiert werden. Der Wert ist der Paketname (der `name`-Parameter in `package.json`), wobei mehrere **Plugins** durch Kommas getrennt werden. :::info + 1. Stellen Sie sicher, dass das **Plugin** lokal heruntergeladen wurde und im Verzeichnis `node_modules` gefunden werden kann. Weitere Details finden Sie unter [**Plugin**-Organisation](/plugin-development/project-structure). 2. Nachdem Sie die Umgebungsvariable hinzugefügt haben, wird das **Plugin** bei der Erstinstallation (`nocobase install`) oder einem Upgrade (`nocobase upgrade`) automatisch installiert oder aktualisiert. + ::: ```bash diff --git a/docs/docs/de/plugin-development/build.md b/docs/docs/de/plugin-development/build.md index 3e8d4ed24dd..6f39f82904a 100644 --- a/docs/docs/de/plugin-development/build.md +++ b/docs/docs/de/plugin-development/build.md @@ -1,5 +1,18 @@ # Build +### Plugin standardmäßig aktivieren + +Nach dem Hochladen wird ein Plugin nicht automatisch aktiviert – es erscheint im „Plugin-Manager" und muss manuell eingeschaltet werden. Wenn Sie Ihre eigene NocoBase-Anwendung pflegen und möchten, dass das Plugin zusammen mit der Anwendung standardmäßig aktiviert wird, können Sie die Umgebungsvariable `APPEND_PRESET_BUILT_IN_PLUGINS` (Standard-Built-in-Plugins hinzufügen) verwenden. Die Verwendung wird unter [Plugin standardmäßig vorinstallieren oder aktivieren](./write-your-first-plugin.md#plugin-standardmäßig-vorinstallieren-oder-aktivieren-optional) beschrieben. + +## Verwandte Links + +- [Ersten Plugin entwickeln](./write-your-first-plugin.md) — Plugin von Grund auf erstellen, einschließlich vollständigem Build- und Paketierungsprozess +- [Projektverzeichnisstruktur](./project-structure.md) — Zweck der Verzeichnisse `packages/plugins`, `storage/tar` und weiterer +- [Abhängigkeitsverwaltung](./dependency-management.md) — Abhängigkeitsdeklaration und globale Abhängigkeiten von Plugins +- [Plugin-Entwicklung Übersicht](./index.md) — Gesamtübersicht der Plugin-Entwicklung +- [Plugins installieren und aktualisieren](../get-started/install-upgrade-plugins.mdx) — Gepackte Dateien in die Zielumgebung hochladen +- [Umgebungsvariablen](../get-started/installation/env.md) — Konfiguration von Umgebungsvariablen für Preset- und Built-in-Plugins + ## Benutzerdefinierte Build-Konfiguration Wenn Sie die Build-Konfiguration anpassen möchten, können Sie im Stammverzeichnis Ihres Plugins eine `build.config.ts`-Datei mit folgendem Inhalt erstellen: diff --git a/docs/docs/de/plugin-development/write-your-first-plugin.md b/docs/docs/de/plugin-development/write-your-first-plugin.md index 7da905c6a89..26bc4e3a333 100644 --- a/docs/docs/de/plugin-development/write-your-first-plugin.md +++ b/docs/docs/de/plugin-development/write-your-first-plugin.md @@ -112,6 +112,33 @@ Nach der Aktivierung erstellen Sie eine neue Seite „Modern page (v2)“. Beim ![20250928174529](https://static-docs.nocobase.com/20250928174529.png) +### Plugin standardmäßig vorinstallieren oder aktivieren (optional) + +Das obige Verfahren beschreibt das manuelle Aktivieren eines einzelnen Plugins. Wenn Sie Ihre eigene NocoBase-Anwendung pflegen und möchten, dass bestimmte Plugins nach `nocobase install` (Erstinstallation) oder `nocobase upgrade` (Upgrade) automatisch bereitstehen, können Sie zwei Umgebungsvariablen verwenden, um den Standardzustand von Plugins zu steuern: + +- **`APPEND_PRESET_LOCAL_PLUGINS` (Standard-Preset-Plugins hinzufügen)** — Fügt das Plugin zur Liste der voreingestellten lokalen Plugins hinzu; nach der Installation erscheint es im „Plugin-Manager", ist aber standardmäßig nicht aktiviert und muss manuell eingeschaltet werden +- **`APPEND_PRESET_BUILT_IN_PLUGINS` (Standard-Built-in-Plugins hinzufügen)** — Fügt das Plugin zur Liste der integrierten Plugins hinzu; es wird bei der Installation automatisch aktiviert und kann als integriertes Plugin **im „Plugin-Manager" nicht deaktiviert oder gelöscht werden** + +Beide Variablen nehmen als Wert den Plugin-Paketnamen (`name` in `package.json`), mehrere Plugins werden durch Kommas getrennt. In der `.env`-Datei konfigurieren Sie sie wie folgt: + +```bash +# Standard-Preset: erscheint in der Plugin-Manager-Liste, wird aber nicht automatisch aktiviert +APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world + +# Standard-aktiviert: wird automatisch installiert und aktiviert und kann über die Oberfläche nicht deaktiviert werden +APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world +``` + +Für die lokale Entwicklung und Fehlersuche genügt in der Regel das bereits beschriebene `yarn pm enable`. Diese beiden Variablen eignen sich besonders für „out-of-the-box"-Distributionsszenarien – zum Beispiel wenn Sie eine NocoBase-Anwendung mit fest integrierten Plugins bündeln und die Plugins nach der Initialisierung direkt verfügbar haben möchten. + +:::tip Hinweis + +- Das Plugin muss lokal heruntergeladen sein und in `node_modules` aufgelöst werden können, siehe [Projektverzeichnisstruktur](./project-structure.md) +- Nach der Konfiguration muss `nocobase install` oder `nocobase upgrade` erneut ausgeführt werden, damit die Änderungen wirksam werden +- Eine vollständige Beschreibung der Umgebungsvariablen finden Sie unter [Umgebungsvariablen](../get-started/installation/env.md#append_preset_local_plugins) + +::: + ## Schritt 4: Erstellen und Packen Wenn Sie das Plugin in anderen Umgebungen verteilen möchten, müssen Sie es zuerst erstellen und dann packen: @@ -129,4 +156,17 @@ Nach Abschluss des Builds befindet sich die Paketdatei standardmäßig unter `st ## Schritt 5: In eine andere NocoBase-Anwendung hochladen -Laden Sie das Plugin hoch und entpacken Sie es in das Verzeichnis `./storage/plugins` der Zielanwendung. Details finden Sie unter [Plugins installieren und aktualisieren](../get-started/install-upgrade-plugins.mdx). \ No newline at end of file +Laden Sie das Plugin hoch und entpacken Sie es in das Verzeichnis `./storage/plugins` der Zielanwendung. Details finden Sie unter [Plugins installieren und aktualisieren](../get-started/install-upgrade-plugins.mdx). + +## Verwandte Links + +- [Plugin-Entwicklung Übersicht](./index.md) — NocoBase-Mikrokernel-Architektur und Plugin-Lebenszyklus kennenlernen +- [Projektverzeichnisstruktur](./project-structure.md) — Konventionen für das Projektverzeichnis, Plugin-Ladepfade und Prioritäten +- [Server-Entwicklung Übersicht](./server/index.md) — Gesamtübersicht und Kernkonzepte der serverseitigen Plugin-Entwicklung +- [Client-Entwicklung Übersicht](./client/index.md) — Gesamtübersicht und Kernkonzepte der clientseitigen Plugin-Entwicklung +- [Erstellen und Packen](./build.md) — Build-, Paketierungs- und Distributionsprozess für Plugins +- [Test](./server/test.md) — Testfälle für serverseitige Plugins schreiben +- [Installation mit create-nocobase-app](../get-started/installation/create-nocobase-app) — Eine der NocoBase-Installationsmethoden +- [Installation aus dem Git-Quellcode](../get-started/installation/git) — NocoBase aus dem Quellcode installieren +- [Plugins installieren und aktualisieren](../get-started/install-upgrade-plugins.mdx) — Gepackte Plugins in andere Umgebungen hochladen +- [Umgebungsvariablen](../get-started/installation/env.md) — Konfiguration von Umgebungsvariablen für Preset- und Built-in-Plugins \ No newline at end of file diff --git a/docs/docs/en/get-started/installation/env.md b/docs/docs/en/get-started/installation/env.md index 2f8731f4735..2c8648a8a27 100644 --- a/docs/docs/en/get-started/installation/env.md +++ b/docs/docs/en/get-started/installation/env.md @@ -294,7 +294,7 @@ Log print format. Default is `console` in development and `json` in production. LOGGER_FORMAT=json ``` -Reference: [Log Format](/log-and-monitor/logger/index.md#log-format) +Reference: [Log Format](/log-and-monitor/logger/index.md#log-formats) ### CACHE_DEFAULT_STORE @@ -375,8 +375,10 @@ Supported formats: Used to append preset local plugins. The value is the package name (the `name` parameter in `package.json`), with multiple plugins separated by commas. :::info + 1. Ensure the plugin is downloaded locally and can be found in the `node_modules` directory. For more details, see [Plugin Organization](/plugin-development/project-structure). 2. After adding the environment variable, the plugin will appear on the plugin manager page only after an initial installation (`nocobase install`) or upgrade (`nocobase upgrade`). + ::: ```bash @@ -388,8 +390,10 @@ APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar Used to append built-in plugins that are installed by default. The value is the package name (the `name` parameter in `package.json`), with multiple plugins separated by commas. :::info + 1. Ensure the plugin is downloaded locally and can be found in the `node_modules` directory. For more details, see [Plugin Organization](/plugin-development/project-structure). 2. After adding the environment variable, the plugin will be automatically installed or upgraded during the initial installation (`nocobase install`) or upgrade (`nocobase upgrade`). + ::: ```bash @@ -472,7 +476,7 @@ yarn cross-env \ ### WORKFLOW_SCRIPT_MODULES -Workflow JavaScript node available modules list. For details, see "[JavaScript Node: Using External Modules](/workflow/nodes/javascript#using-external-modules)". +Workflow JavaScript node available modules list. For details, see "[JavaScript Node: Using External Modules](/workflow/nodes/javascript#unsafe-mode-module-support)". ### WORKFLOW_LOOP_LIMIT diff --git a/docs/docs/en/plugin-development/build.md b/docs/docs/en/plugin-development/build.md index 2ad2157b557..665664f76a7 100644 --- a/docs/docs/en/plugin-development/build.md +++ b/docs/docs/en/plugin-development/build.md @@ -44,6 +44,10 @@ yarn build @my-project/plugin-hello --tar Upload and extract the `.tar.gz` file to the target application's `./storage/plugins` directory. For detailed steps, see [Install and Upgrade Plugins](../get-started/install-upgrade-plugins.mdx). +### 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](./write-your-first-plugin.md#make-a-plugin-preset-or-built-in-by-default-optional) 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: @@ -84,3 +88,4 @@ Key points: - [Dependency Management](./dependency-management.md) — Plugin dependency declarations and global dependencies - [Plugin Development Overview](./index.md) — Overall introduction to plugin development - [Install and Upgrade Plugins](../get-started/install-upgrade-plugins.mdx) — Upload packaged files to target environments +- [Environment Variables](../get-started/installation/env.md) — Environment variable configuration for preset and built-in plugins diff --git a/docs/docs/en/plugin-development/write-your-first-plugin.md b/docs/docs/en/plugin-development/write-your-first-plugin.md index 40c240a6669..5b673bf3450 100644 --- a/docs/docs/en/plugin-development/write-your-first-plugin.md +++ b/docs/docs/en/plugin-development/write-your-first-plugin.md @@ -118,6 +118,33 @@ After activation, create a new "Modern page (v2)" page. When adding blocks, you' ![20250928174529](https://static-docs.nocobase.com/20250928174529.png) +### Make a Plugin Preset or Built-in by Default (Optional) + +The steps above describe manually enabling a single plugin. If you are maintaining your own NocoBase application and want certain plugins to be automatically ready after running `nocobase install` (first-time installation) or `nocobase upgrade` (upgrade), you can use two environment variables to control a plugin's default state: + +- **`APPEND_PRESET_LOCAL_PLUGINS` (append preset local plugins)** — Adds the plugin to the preset local plugin list. After installation it appears in the Plugin Manager but is not activated by default; you need to enable it manually. +- **`APPEND_PRESET_BUILT_IN_PLUGINS` (append built-in plugins)** — Adds the plugin to the built-in plugin list. It is automatically activated on installation and, as a built-in plugin, **cannot be disabled or deleted from the Plugin Manager**. + +The value for both variables is the plugin package name (the `name` field in `package.json`); separate multiple plugins with commas. Configure them in `.env` like this: + +```bash +# Preset: appears in the Plugin Manager list but is not activated automatically +APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world + +# Built-in: automatically installed and activated, and cannot be disabled from the UI +APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world +``` + +For day-to-day local development and debugging, `yarn pm enable` (described above) is usually sufficient. These two variables are better suited for "out-of-the-box" distribution scenarios — for example, when you are shipping a NocoBase application bundled with a fixed set of plugins and want those plugins to be ready immediately after initialization. + +:::tip Note + +- The plugin must already be downloaded locally and resolvable in `node_modules`. See [Project Structure](./project-structure.md) for details. +- After configuring, you need to re-run `nocobase install` or `nocobase upgrade` for the changes to take effect. +- For the full list of environment variable options, see [Environment Variables](../get-started/installation/env.md#append_preset_local_plugins). + +::: + ## Step 4: Build and Package When you're ready to distribute the plugin to other environments, you need to build and package it first: @@ -158,4 +185,5 @@ Upload and extract the package file to the target application's `./storage/plugi - [Install using create-nocobase-app](../get-started/installation/create-nocobase-app) — One of the NocoBase installation methods - [Install from Git source](../get-started/installation/git) — Install NocoBase from source code - [Install and Upgrade Plugins](../get-started/install-upgrade-plugins.mdx) — Upload packaged plugins to other environments +- [Environment Variables](../get-started/installation/env.md) — Environment variable configuration for preset and built-in plugins diff --git a/docs/docs/es/get-started/installation/env.md b/docs/docs/es/get-started/installation/env.md index d42612d37d9..7f62aa0e701 100644 --- a/docs/docs/es/get-started/installation/env.md +++ b/docs/docs/es/get-started/installation/env.md @@ -302,7 +302,7 @@ Formato de impresión de los registros. El valor predeterminado es `console` en LOGGER_FORMAT=json ``` -Referencia: [Formato de Registros](/log-and-monitor/logger/index.md#日志格式) +Referencia: [Formato de Registros](/log-and-monitor/logger/index.md#formatos-de-registro) ### CACHE_DEFAULT_STORE @@ -386,7 +386,8 @@ Se utiliza para añadir **plugins** locales preestablecidos no activados. El val 1. Asegúrese de que el **plugin** esté descargado localmente y pueda encontrarse en el directorio `node_modules`. Para más detalles, consulte [Estructura del proyecto de **plugins**](/plugin-development/project-structure). 2. Después de añadir la variable de entorno, el **plugin** solo aparecerá en la página del gestor de **plugins** tras una instalación inicial (`nocobase install`) o una actualización (`nocobase upgrade`). - ::: + +::: ```bash APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar @@ -400,7 +401,8 @@ Se utiliza para añadir **plugins** integrados que se instalan por defecto. El v 1. Asegúrese de que el **plugin** esté descargado localmente y pueda encontrarse en el directorio `node_modules`. Para más detalles, consulte [Estructura del proyecto de **plugins**](/plugin-development/project-structure). 2. Después de añadir la variable de entorno, el **plugin** se instalará o actualizará automáticamente durante la instalación inicial (`nocobase install`) o la actualización (`nocobase upgrade`). - ::: + +::: ```bash APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar diff --git a/docs/docs/es/plugin-development/build.md b/docs/docs/es/plugin-development/build.md index 9198187f7c2..9c8ec93df65 100644 --- a/docs/docs/es/plugin-development/build.md +++ b/docs/docs/es/plugin-development/build.md @@ -1,4 +1,46 @@ -# Compilación +# Compilación y empaquetado + +Una vez finalizado el desarrollo del plugin, son necesarios dos pasos — compilación (transpilación del código fuente) y empaquetado (generación del archivo `.tar.gz`) — antes de poder distribuirlo a otras aplicaciones NocoBase. + +## Compilar el plugin + +La compilación transpila el código TypeScript de `src/` a JavaScript: el código del cliente se empaqueta con Rsbuild y el código del servidor con tsup: + +```bash +yarn build @my-project/plugin-hello +``` + +Los artefactos de compilación se generan en el directorio `dist/` dentro de la raíz del plugin. + +:::tip Nota + +Si el plugin se crea en el repositorio de código fuente, la primera compilación activará una comprobación de tipos de todo el repositorio, lo que puede llevar algún tiempo. Se recomienda asegurarse de que las dependencias estén instaladas y de que el repositorio se encuentre en un estado compilable. + +::: + +## Empaquetar el plugin + +El empaquetado comprime los artefactos de compilación en un archivo `.tar.gz` para facilitar su subida a otros entornos: + +```bash +yarn nocobase tar @my-project/plugin-hello +``` + +El archivo empaquetado se genera por defecto en `storage/tar/@my-project/plugin-hello.tar.gz`. + +También puede usar el parámetro `--tar` para combinar la compilación y el empaquetado en un solo paso: + +```bash +yarn build @my-project/plugin-hello --tar +``` + +## Subir a otra aplicación de NocoBase + +Suba el archivo `.tar.gz` y descomprímalo en el directorio `./storage/plugins` de la aplicación de destino. Para más detalles, consulte [Instalar y actualizar plugins](../get-started/install-upgrade-plugins.mdx). + +### Habilitar plugins por defecto + +Tras subir el plugin, este no se activa automáticamente — aparecerá en el «Administrador de complementos» y deberá habilitarlo manualmente. Si está manteniendo su propia aplicación NocoBase y desea que el plugin se habilite por defecto junto con la aplicación, puede controlarlo con la variable de entorno `APPEND_PRESET_BUILT_IN_PLUGINS` (añadir plugins integrados por defecto); consulte [Hacer que el plugin esté predefinido o habilitado por defecto (opcional)](./write-your-first-plugin.md#hacer-que-el-plugin-esté-predefinido-o-habilitado-por-defecto-opcional). ## Personalizar la Configuración de Compilación @@ -28,3 +70,12 @@ export default defineConfig({ }; }); ``` + +## Enlaces relacionados + +- [Escriba su primer plugin](./write-your-first-plugin.md) — Cree un plugin desde cero, con el flujo completo de compilación y empaquetado +- [Estructura del proyecto](./project-structure.md) — Conozca el propósito de los directorios `packages/plugins`, `storage/tar` y otros +- [Gestión de dependencias](./dependency-management.md) — Declaración de dependencias del plugin y dependencias globales +- [Descripción general del desarrollo de plugins](./index.md) — Introducción general al desarrollo de plugins +- [Instalar y actualizar plugins](../get-started/install-upgrade-plugins.mdx) — Subir el archivo empaquetado al entorno de destino +- [Variables de Entorno](../get-started/installation/env.md) — Configuración de variables de entorno para plugins predefinidos, integrados y otros diff --git a/docs/docs/es/plugin-development/write-your-first-plugin.md b/docs/docs/es/plugin-development/write-your-first-plugin.md index 95007773d6c..e5b0ebac88d 100644 --- a/docs/docs/es/plugin-development/write-your-first-plugin.md +++ b/docs/docs/es/plugin-development/write-your-first-plugin.md @@ -112,6 +112,33 @@ Después de la activación, cree una nueva página "Modern page (v2)". Al añadi ![20250928174529](https://static-docs.nocobase.com/20250928174529.png) +### Hacer que el plugin esté predefinido o habilitado por defecto (opcional) + +Lo anterior describe cómo activar un plugin de forma manual. Si está manteniendo su propia aplicación NocoBase y desea que ciertos plugins estén listos automáticamente tras ejecutar `nocobase install` (instalación inicial) o `nocobase upgrade` (actualización), puede usar dos variables de entorno para controlar el estado predeterminado de los plugins: + +- **`APPEND_PRESET_LOCAL_PLUGINS` (añadir plugins locales predefinidos por defecto)** — Agrega el plugin a la lista de plugins locales predefinidos; tras la instalación aparecerá en el «Administrador de complementos», pero no estará activado por defecto y deberá habilitarlo manualmente. +- **`APPEND_PRESET_BUILT_IN_PLUGINS` (añadir plugins integrados por defecto)** — Agrega el plugin a la lista de plugins integrados; se activa automáticamente durante la instalación y, al ser un plugin integrado, **no puede desactivarse ni eliminarse desde el «Administrador de complementos»**. + +El valor de ambas variables es el nombre del paquete del plugin (el campo `name` en `package.json`); si son varios plugins, sepárelos con comas. Configure así en el archivo `.env`: + +```bash +# Predefinido por defecto: aparece en la lista del Administrador de complementos, pero no se activa automáticamente +APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world + +# Habilitado por defecto: se instala y activa automáticamente, y no puede desactivarse desde la interfaz +APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world +``` + +En general, `yarn pm enable` es suficiente para el desarrollo y la depuración local. Estas dos variables son más adecuadas para escenarios de distribución «listas para usar», por ejemplo, cuando empaqueta una aplicación NocoBase con un conjunto fijo de plugins y desea que estén disponibles directamente tras la inicialización. + +:::tip Nota + +- El plugin debe estar descargado localmente y poder resolverse en `node_modules`; consulte [Estructura del proyecto](./project-structure.md). +- Tras configurar las variables, deberá volver a ejecutar `nocobase install` o `nocobase upgrade` para que surtan efecto. +- Consulte la descripción completa de variables de entorno en [Variables de Entorno](../get-started/installation/env.md#append_preset_local_plugins). + +::: + ## Paso 4: Compile y empaquete Cuando esté listo para distribuir el **plugin** a otros entornos, primero deberá compilarlo y empaquetarlo: @@ -129,4 +156,17 @@ Una vez completada la compilación, el archivo del paquete se encuentra por defe ## Paso 5: Suba a otra aplicación de NocoBase -Suba y descomprima el archivo en el directorio `./storage/plugins` de la aplicación de destino. Para más detalles, consulte [Instalar y actualizar plugins](../get-started/install-upgrade-plugins.mdx). \ No newline at end of file +Suba y descomprima el archivo en el directorio `./storage/plugins` de la aplicación de destino. Para más detalles, consulte [Instalar y actualizar plugins](../get-started/install-upgrade-plugins.mdx). + +## Enlaces relacionados + +- [Descripción general del desarrollo de plugins](./index.md) — Conozca la arquitectura de micronúcleo de NocoBase y el ciclo de vida de los plugins +- [Estructura del proyecto](./project-structure.md) — Convenciones de directorios, rutas de carga y prioridades de los plugins +- [Descripción general del desarrollo en el servidor](./server/index.md) — Introducción general y conceptos clave de los plugins del lado del servidor +- [Descripción general del desarrollo en el cliente](./client/index.md) — Introducción general y conceptos clave de los plugins del lado del cliente +- [Compilación y empaquetado](./build.md) — Proceso de compilación, empaquetado y distribución de plugins +- [Tests](./server/test.md) — Cómo escribir casos de prueba para plugins del lado del servidor +- [Instalar usando create-nocobase-app](../get-started/installation/create-nocobase-app) — Una de las formas de instalar NocoBase +- [Instalar desde el código fuente de Git](../get-started/installation/git) — Instalar NocoBase desde el código fuente +- [Instalar y actualizar plugins](../get-started/install-upgrade-plugins.mdx) — Subir plugins empaquetados a otros entornos +- [Variables de Entorno](../get-started/installation/env.md) — Configuración de variables de entorno para plugins predefinidos, integrados y otros \ No newline at end of file diff --git a/docs/docs/fr/get-started/installation/env.md b/docs/docs/fr/get-started/installation/env.md index a2722b400c4..6f5577e290f 100644 --- a/docs/docs/fr/get-started/installation/env.md +++ b/docs/docs/fr/get-started/installation/env.md @@ -375,8 +375,10 @@ Formats pris en charge : Utilisée pour ajouter des `plugins` locaux prédéfinis et non activés. La valeur est le nom du package du `plugin` (le paramètre `name` dans `package.json`), avec plusieurs `plugins` séparés par des virgules. :::info + 1. Assurez-vous que le `plugin` est téléchargé localement et qu'il se trouve dans le répertoire `node_modules`. Pour plus de détails, consultez l'« [Organisation des plugins](/plugin-development/project-structure) ». 2. Après avoir ajouté la variable d'environnement, le `plugin` n'apparaîtra sur la page du gestionnaire de `plugins` qu'après une installation initiale (`nocobase install`) ou une mise à jour (`nocobase upgrade`). + ::: ```bash @@ -388,8 +390,10 @@ APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar Utilisée pour ajouter des `plugins` intégrés et installés par défaut. La valeur est le nom du package du `plugin` (le paramètre `name` dans `package.json`), avec plusieurs `plugins` séparés par des virgules. :::info + 1. Assurez-vous que le `plugin` est téléchargé localement et qu'il se trouve dans le répertoire `node_modules`. Pour plus de détails, consultez l'« [Organisation des plugins](/plugin-development/project-structure) ». 2. Après avoir ajouté la variable d'environnement, le `plugin` sera automatiquement installé ou mis à jour lors de l'installation initiale (`nocobase install`) ou de la mise à jour (`nocobase upgrade`). + ::: ```bash diff --git a/docs/docs/fr/plugin-development/build.md b/docs/docs/fr/plugin-development/build.md index cee43c34d94..a38540450b3 100644 --- a/docs/docs/fr/plugin-development/build.md +++ b/docs/docs/fr/plugin-development/build.md @@ -44,6 +44,10 @@ yarn build @my-project/plugin-hello --tar Téléversez et décompressez le fichier `.tar.gz` dans le répertoire `./storage/plugins` de l'application cible. Voir [Installer et mettre à niveau les plugins](../get-started/install-upgrade-plugins.mdx) pour les détails. +### Activer le plugin par défaut + +Après le téléversement, le plugin n'est pas automatiquement activé — il apparaît dans le «Gestionnaire de plugins» et doit être activé manuellement. Si vous maintenez votre propre application NocoBase et souhaitez que le plugin soit activé par défaut avec l'application, vous pouvez utiliser la variable d'environnement `APPEND_PRESET_BUILT_IN_PLUGINS` (ajouter aux plugins intégrés par défaut) pour le contrôler. Consultez [Rendre le plugin préinstallé ou activé par défaut](./write-your-first-plugin.md#rendre-le-plugin-préinstallé-ou-activé-par-défaut-optionnel) pour plus de détails. + ## Configuration de construction personnalisée En général, la configuration de construction par défaut suffit. Si vous avez besoin de personnaliser — par exemple modifier le point d'entrée du package, ajouter des alias ou ajuster les options de compression — vous pouvez créer un fichier `build.config.ts` à la racine du plugin : @@ -84,3 +88,4 @@ Quelques points clés : - [Gestion des dépendances](./dependency-management.md) — Déclaration des dépendances de plugin et dépendances globales - [Vue d'ensemble du développement de plugins](./index.md) — Présentation générale du développement de plugin - [Installer et mettre à niveau les plugins](../get-started/install-upgrade-plugins.mdx) — Téléverser le fichier package dans l'environnement cible +- [Variables d'environnement](../get-started/installation/env.md) — Configuration des variables d'environnement pour les plugins préinstallés et intégrés diff --git a/docs/docs/fr/plugin-development/write-your-first-plugin.md b/docs/docs/fr/plugin-development/write-your-first-plugin.md index e942ac099dd..7a5cc145b26 100644 --- a/docs/docs/fr/plugin-development/write-your-first-plugin.md +++ b/docs/docs/fr/plugin-development/write-your-first-plugin.md @@ -118,6 +118,33 @@ Après l'activation, créez une nouvelle page «Modern page (v2)». Lors de l'aj ![20250928174529](https://static-docs.nocobase.com/20250928174529.png) +### Rendre le plugin préinstallé ou activé par défaut (optionnel) + +Ce qui précède décrit l'activation manuelle d'un plugin individuel. Si vous maintenez votre propre application NocoBase et souhaitez que certains plugins soient automatiquement disponibles après l'exécution de `nocobase install` (première installation) ou `nocobase upgrade` (mise à niveau), vous pouvez utiliser deux variables d'environnement pour contrôler l'état par défaut des plugins : + +- **`APPEND_PRESET_LOCAL_PLUGINS` (ajouter aux plugins locaux préinstallés par défaut)** — ajoute le plugin à la liste des plugins locaux préinstallés ; il apparaît dans le «Gestionnaire de plugins» après l'installation, mais n'est pas activé par défaut et doit être activé manuellement +- **`APPEND_PRESET_BUILT_IN_PLUGINS` (ajouter aux plugins intégrés par défaut)** — ajoute le plugin à la liste des plugins intégrés, qui sont automatiquement activés lors de l'installation ; en tant que plugins intégrés, **ils ne peuvent pas être désactivés ni supprimés dans le «Gestionnaire de plugins»** + +La valeur de ces deux variables est le nom du package du plugin (le champ `name` dans `package.json`), avec plusieurs plugins séparés par des virgules. Configurez-les dans le fichier `.env` : + +```bash +# Préinstallé par défaut : apparaît dans la liste du Gestionnaire de plugins, mais n'est pas activé automatiquement +APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world + +# Activé par défaut : installé et activé automatiquement, et ne peut pas être désactivé depuis l'interface +APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world +``` + +En règle générale, `yarn pm enable` suffit pour le développement et le débogage en local. Ces deux variables sont davantage adaptées aux scénarios de distribution «prêts à l'emploi» — par exemple, si vous avez empaqueté une application NocoBase avec un ensemble fixe de plugins et souhaitez que ces plugins soient directement disponibles après l'initialisation. + +:::tip Astuce + +- Le plugin doit être téléchargé localement et pouvoir être résolu dans `node_modules` ; voir [Structure du projet](./project-structure.md) +- Après configuration, il faut réexécuter `nocobase install` ou `nocobase upgrade` pour que les changements prennent effet +- La description complète des variables d'environnement est disponible dans [Variables d'environnement](../get-started/installation/env.md#append_preset_local_plugins) + +::: + ## Étape 4 : compiler et empaqueter Lorsque vous êtes prêt à distribuer votre plugin vers d'autres environnements, vous devez d'abord le compiler, puis l'empaqueter : @@ -158,3 +185,4 @@ Téléversez et décompressez le fichier dans le répertoire `./storage/plugins` - [Installer avec create-nocobase-app](../get-started/installation/create-nocobase-app) — l'une des méthodes d'installation de NocoBase - [Installer depuis les sources Git](../get-started/installation/git) — installer NocoBase depuis le code source - [Installer et mettre à niveau les plugins](../get-started/install-upgrade-plugins.mdx) — téléverser le plugin empaqueté vers d'autres environnements +- [Variables d'environnement](../get-started/installation/env.md) — configuration des variables d'environnement pour les plugins préinstallés et intégrés diff --git a/docs/docs/id/get-started/installation/env.md b/docs/docs/id/get-started/installation/env.md index f0ba69ddb3e..0fcc0e0292a 100644 --- a/docs/docs/id/get-started/installation/env.md +++ b/docs/docs/id/get-started/installation/env.md @@ -300,7 +300,7 @@ Format pencetakan log, environment development default-nya `console`, environmen LOGGER_FORMAT=json ``` -Referensi: [Format Log](/log-and-monitor/logger/index.md#日志格式) +Referensi: [Format Log](/log-and-monitor/logger/index.md#format-log) ### CACHE_DEFAULT_STORE @@ -355,7 +355,7 @@ TELEMETRY_TRACE_PROCESSOR=console ### WORKER_MODE -Digunakan untuk mengonfigurasi mode kerja node yang berbeda saat melakukan service splitting di mode cluster. Untuk detailnya lihat "[Service Splitting: Cara Membagi Service](/cluster-mode/services-splitting#如何拆分服务)". +Digunakan untuk mengonfigurasi mode kerja node yang berbeda saat melakukan service splitting di mode cluster. Untuk detailnya lihat "[Service Splitting: Cara Membagi Service](/cluster-mode/services-splitting#cara-memisahkan-service)". ### SERVER_REQUEST_WHITELIST @@ -388,7 +388,8 @@ Digunakan untuk menambahkan plugin preset yang belum diaktifkan, nilainya adalah 1. Pastikan plugin sudah diunduh ke lokal dan dapat ditemukan di direktori `node_modules`. Untuk informasi lebih lanjut lihat [Cara Pengorganisasian Plugin](/plugin-development/project-structure). 2. Setelah menambahkan environment variable, plugin akan tampil di halaman plugin manager setelah instalasi awal `nocobase install` atau upgrade `nocobase upgrade`. - ::: + +::: ```bash APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar @@ -402,7 +403,8 @@ Digunakan untuk menambahkan plugin built-in yang diinstal secara default, nilain 1. Pastikan plugin sudah diunduh ke lokal dan dapat ditemukan di direktori `node_modules`. Untuk informasi lebih lanjut lihat [Cara Pengorganisasian Plugin](/plugin-development/project-structure). 2. Setelah menambahkan environment variable, plugin akan diinstal atau di-upgrade secara otomatis saat instalasi awal `nocobase install` atau upgrade `nocobase upgrade`. - ::: + +::: ```bash APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar @@ -484,7 +486,7 @@ yarn cross-env \ ### WORKFLOW_SCRIPT_MODULES -Daftar modul yang dapat digunakan oleh node JavaScript pada workflow. Untuk detailnya lihat "[Node JavaScript: Menggunakan Modul Eksternal](/workflow/nodes/javascript#使用外部模块)". +Daftar modul yang dapat digunakan oleh node JavaScript pada workflow. Untuk detailnya lihat "[Node JavaScript: Menggunakan Modul Eksternal](/workflow/nodes/javascript#mode-tidak-aman-membutuhkan-dukungan-modul)". ### WORKFLOW_LOOP_LIMIT diff --git a/docs/docs/id/plugin-development/build.md b/docs/docs/id/plugin-development/build.md index c377b1acc19..9a26343bfd8 100644 --- a/docs/docs/id/plugin-development/build.md +++ b/docs/docs/id/plugin-development/build.md @@ -44,6 +44,10 @@ yarn build @my-project/plugin-hello --tar Cukup upload dan ekstrak file `.tar.gz` ke direktori `./storage/plugins` aplikasi target. Untuk langkah detail, lihat [Instalasi & Upgrade Plugin](../get-started/install-upgrade-plugins.mdx). +### Plugin Default Aktif + +Setelah diupload, plugin tidak akan diaktifkan secara otomatis — plugin akan muncul di "Plugin Manager" dan perlu diaktifkan secara manual. Jika Anda memelihara aplikasi NocoBase sendiri dan ingin plugin ikut aktif secara default bersama aplikasi, Anda dapat menggunakan environment variable `APPEND_PRESET_BUILT_IN_PLUGINS` (tambahkan plugin built-in default) untuk mengontrolnya. Untuk cara penggunaannya, lihat [Membuat Plugin Default Preset atau Default Aktif](./write-your-first-plugin.md#membuat-plugin-default-preset-atau-default-aktif-opsional). + ## Konfigurasi Build Kustom Umumnya konfigurasi build default sudah cukup. Jika Anda perlu melakukan kustomisasi — misalnya mengubah entry packaging, menambah alias, mengatur opsi kompresi, dan sebagainya — Anda dapat membuat file `build.config.ts` di root direktori plugin: @@ -84,3 +88,4 @@ Beberapa poin kunci: - [Manajemen Dependensi](./dependency-management.md) — Deklarasi dependensi plugin dan dependensi global - [Ikhtisar Plugin Development](./index.md) — Pengantar menyeluruh tentang plugin development - [Instalasi & Upgrade Plugin](../get-started/install-upgrade-plugins.mdx) — Upload file hasil packaging ke environment target +- [Environment Variable](../get-started/installation/env.md) — Konfigurasi environment variable untuk plugin preset dan built-in diff --git a/docs/docs/id/plugin-development/write-your-first-plugin.md b/docs/docs/id/plugin-development/write-your-first-plugin.md index 8e867fa5791..253080bd701 100644 --- a/docs/docs/id/plugin-development/write-your-first-plugin.md +++ b/docs/docs/id/plugin-development/write-your-first-plugin.md @@ -118,6 +118,33 @@ Setelah diaktifkan, buat halaman "Modern page (v2)" baru, saat menambahkan Block ![20250928174529](https://static-docs.nocobase.com/20250928174529.png) +### Membuat Plugin Default Preset atau Default Aktif (Opsional) + +Di atas dijelaskan cara mengaktifkan plugin secara manual satu per satu. Jika Anda memelihara aplikasi NocoBase sendiri dan ingin beberapa plugin sudah siap secara otomatis setelah menjalankan `nocobase install` (instalasi pertama) atau `nocobase upgrade` (upgrade), Anda dapat menggunakan dua environment variable untuk mengontrol status default plugin: + +- **`APPEND_PRESET_LOCAL_PLUGINS` (tambahkan plugin preset lokal default)** — Menambahkan plugin ke daftar plugin preset lokal; setelah instalasi akan muncul di "Plugin Manager", tetapi tidak aktif secara default dan perlu diaktifkan secara manual +- **`APPEND_PRESET_BUILT_IN_PLUGINS` (tambahkan plugin built-in default)** — Menambahkan plugin ke daftar plugin built-in; saat instalasi plugin diaktifkan secara otomatis, dan sebagai plugin built-in, **tidak dapat dinonaktifkan atau dihapus di "Plugin Manager"** + +Nilai kedua variable ini adalah nama paket plugin (field `name` di `package.json`), pisahkan beberapa plugin dengan koma. Konfigurasi di file `.env` seperti berikut: + +```bash +# Default preset: muncul di daftar Plugin Manager, tetapi tidak diaktifkan secara otomatis +APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world + +# Default aktif: diinstal dan diaktifkan secara otomatis, serta tidak dapat dinonaktifkan melalui antarmuka +APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world +``` + +Pada umumnya, untuk pengembangan dan debugging lokal, `yarn pm enable` sudah cukup. Kedua variable ini lebih cocok untuk skenario distribusi "siap pakai" — misalnya Anda mengemas aplikasi NocoBase dengan plugin tertentu dan ingin plugin langsung tersedia setelah inisialisasi. + +:::tip Tips + +- Plugin harus sudah diunduh ke lokal dan dapat ditemukan di `node_modules`, lihat [Struktur Direktori Proyek](./project-structure.md) +- Setelah dikonfigurasi, perlu menjalankan ulang `nocobase install` atau `nocobase upgrade` agar perubahan berlaku +- Penjelasan lengkap environment variable lihat [Environment Variable](../get-started/installation/env.md#append_preset_local_plugins) + +::: + ## Langkah 4: Build & Packaging Ketika Anda siap mendistribusikan plugin ke environment lain, Anda perlu build kemudian packaging: @@ -157,4 +184,5 @@ Upload dan ekstrak file packaging ke direktori `./storage/plugins` aplikasi targ - [Test Pengujian](./server/test.md) — Menulis test case plugin server - [Instalasi menggunakan create-nocobase-app](../get-started/installation/create-nocobase-app) — Salah satu cara instalasi NocoBase - [Instalasi dari source code Git](../get-started/installation/git) — Instalasi NocoBase dari source code -- [Instalasi & Upgrade Plugin](../get-started/install-upgrade-plugins.mdx) — Upload plugin yang sudah di-package ke environment lain \ No newline at end of file +- [Instalasi & Upgrade Plugin](../get-started/install-upgrade-plugins.mdx) — Upload plugin yang sudah di-package ke environment lain +- [Environment Variable](../get-started/installation/env.md) — Konfigurasi environment variable untuk plugin preset dan built-in \ No newline at end of file diff --git a/docs/docs/ja/get-started/installation/env.md b/docs/docs/ja/get-started/installation/env.md index 4dd94beeea9..63a6027cc55 100644 --- a/docs/docs/ja/get-started/installation/env.md +++ b/docs/docs/ja/get-started/installation/env.md @@ -378,7 +378,8 @@ SERVER_REQUEST_WHITELIST=1.2.3.4,10.0.0.0/8,api.example.com,*.trusted.com 1. プラグインがローカルにダウンロードされ、`node_modules` ディレクトリ内に存在することを確認してください。詳細は[プラグインの構成](/plugin-development/project-structure)を参照してください。 2. 環境変数を追加した後、初期インストール `nocobase install` またはアップグレード `nocobase upgrade` を実行すると、プラグイン管理ページに表示されるようになります。 - ::: + +::: ```bash APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar @@ -392,7 +393,8 @@ APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar 1. プラグインがローカルにダウンロードされ、`node_modules` ディレクトリ内に存在することを確認してください。詳細は[プラグインの構成](/plugin-development/project-structure)を参照してください。 2. 環境変数を追加した後、初期インストール `nocobase install` またはアップグレード `nocobase upgrade` 時にプラグインが自動的にインストールまたはアップグレードされます。 - ::: + +::: ```bash APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar diff --git a/docs/docs/ja/plugin-development/build.md b/docs/docs/ja/plugin-development/build.md index 5f4acc9da10..7c20b4d34d2 100644 --- a/docs/docs/ja/plugin-development/build.md +++ b/docs/docs/ja/plugin-development/build.md @@ -44,6 +44,10 @@ yarn build @my-project/plugin-hello --tar `.tar.gz` ファイルをターゲットアプリケーションの `./storage/plugins` ディレクトリにアップロードして解凍するだけです。詳細な手順は [プラグインのインストールとアップグレード](../get-started/install-upgrade-plugins.mdx) をご覧ください。 +### デフォルトでプラグインを有効化する + +アップロード後、プラグインはデフォルトでは自動的に有効化されません——「プラグインマネージャー」に表示されるため、手動で有効化する必要があります。自分の NocoBase アプリケーションを管理していて、プラグインをアプリケーションと一緒にデフォルトで有効化したい場合は、`APPEND_PRESET_BUILT_IN_PLUGINS`（デフォルト内蔵プラグインの追加）環境変数で制御できます。使い方は[プラグインをデフォルトでプリセットまたはデフォルトで有効化する](./write-your-first-plugin.md#プラグインをデフォルトでプリセットまたはデフォルトで有効化するオプション)を参照してください。 + ## カスタムビルド設定 通常、デフォルトのビルド設定で十分です。カスタマイズが必要な場合 -- 例えばバンドルエントリの変更、エイリアスの追加、圧縮オプションの調整など -- プラグインのルートディレクトリに `build.config.ts` ファイルを作成してください： @@ -84,3 +88,4 @@ export default defineConfig({ - [依存関係の管理](./dependency-management.md) -- プラグインの依存関係宣言とグローバル依存関係 - [プラグイン開発の概要](./index.md) -- プラグイン開発の全体的な紹介 - [プラグインのインストールとアップグレード](../get-started/install-upgrade-plugins.mdx) -- パッケージファイルをターゲット環境にアップロードする +- [環境変数](../get-started/installation/env.md) -- プリセット・内蔵プラグインなどの環境変数設定 diff --git a/docs/docs/ja/plugin-development/write-your-first-plugin.md b/docs/docs/ja/plugin-development/write-your-first-plugin.md index 3a917938937..91f65517332 100644 --- a/docs/docs/ja/plugin-development/write-your-first-plugin.md +++ b/docs/docs/ja/plugin-development/write-your-first-plugin.md @@ -118,6 +118,33 @@ export default { ![20250928174529](https://static-docs.nocobase.com/20250928174529.png) +### プラグインをデフォルトでプリセットまたはデフォルトで有効化する（オプション） + +上記では単一プラグインを手動で有効化する方法を説明しました。自分の NocoBase アプリケーションを管理していて、`nocobase install`（初回インストール）や `nocobase upgrade`（アップグレード）の実行後に特定のプラグインを自動的に準備しておきたい場合は、2 つの環境変数でプラグインのデフォルト状態を制御できます： + +- **`APPEND_PRESET_LOCAL_PLUGINS`（デフォルトプリセットプラグインの追加）** — プラグインをプリセット済みのローカルプラグインリストに追加します。インストール後に「プラグインマネージャー」に表示されますが、デフォルトでは無効であり、手動で有効化する必要があります +- **`APPEND_PRESET_BUILT_IN_PLUGINS`（デフォルト内蔵プラグインの追加）** — プラグインを内蔵プラグインリストに追加します。インストール時に自動的に有効化され、内蔵プラグインとして**「プラグインマネージャー」では無効化も削除もできません** + +どちらの変数の値もプラグインのパッケージ名（`package.json` の `name`）で、複数のプラグインは英語のカンマで区切ります。`.env` での設定例： + +```bash +# デフォルトプリセット：プラグインマネージャーのリストに表示されるが、自動的には有効化されない +APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world + +# デフォルト有効化：自動的にインストールして有効化され、画面から無効化できない +APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world +``` + +通常、ローカル開発・デバッグには前述の `yarn pm enable` で十分です。これら 2 つの変数は「すぐに使える」配布シナリオに適しています——たとえば、固定のプラグインセットを含む NocoBase アプリケーションをパッケージングし、初期化後にプラグインをすぐに利用可能にしたい場合などです。 + +:::tip ヒント + +- プラグインがローカルにダウンロードされ、`node_modules` で解決できる状態になっている必要があります。[プロジェクトディレクトリ構造](./project-structure.md)を参照してください +- 設定後、`nocobase install` または `nocobase upgrade` を再実行することで有効になります +- 環境変数の完全な説明は[環境変数](../get-started/installation/env.md#append_preset_local_plugins)を参照してください + +::: + ## ステップ 4：ビルドとパッケージング プラグインを他の環境に配布する準備ができたら、まずビルドしてからパッケージングする必要があります： @@ -158,3 +185,4 @@ yarn nocobase tar @my-project/plugin-hello - [create-nocobase-app を使用したインストール](../get-started/installation/create-nocobase-app) — NocoBase のインストール方法の一つ - [Git ソースからのインストール](../get-started/installation/git) — ソースコードからの NocoBase インストール - [プラグインのインストールとアップグレード](../get-started/install-upgrade-plugins.mdx) — パッケージ済みプラグインを他の環境にアップロード +- [環境変数](../get-started/installation/env.md) — プリセット・内蔵プラグインなどの環境変数設定 diff --git a/docs/docs/pt/get-started/installation/env.md b/docs/docs/pt/get-started/installation/env.md index f6ae066f9cd..06a5961d774 100644 --- a/docs/docs/pt/get-started/installation/env.md +++ b/docs/docs/pt/get-started/installation/env.md @@ -374,8 +374,10 @@ Formatos suportados: Usada para anexar **plugins** locais predefinidos e não ativados. O valor é o nome do pacote do **plugin** (o parâmetro `name` no `package.json`), com múltiplos **plugins** separados por vírgulas. :::info + 1. Certifique-se de que o **plugin** foi baixado localmente e pode ser encontrado no diretório `node_modules`. Para mais detalhes, consulte [Estrutura do Projeto de Plugins](/plugin-development/project-structure). 2. Após adicionar a variável de ambiente, o **plugin** só aparecerá na página do gerenciador de **plugins** após uma instalação inicial (`nocobase install`) ou uma atualização (`nocobase upgrade`). + ::: ```bash @@ -387,8 +389,10 @@ APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar Usada para anexar **plugins** integrados que são instalados por padrão. O valor é o nome do pacote do **plugin** (o parâmetro `name` no `package.json`), com múltiplos **plugins** separados por vírgulas. :::info + 1. Certifique-se de que o **plugin** foi baixado localmente e pode ser encontrado no diretório `node_modules`. Para mais detalhes, consulte [Estrutura do Projeto de Plugins](/plugin-development/project-structure). 2. Após adicionar a variável de ambiente, o **plugin** será automaticamente instalado ou atualizado durante a instalação inicial (`nocobase install`) ou a atualização (`nocobase upgrade`). + ::: ```bash diff --git a/docs/docs/pt/plugin-development/build.md b/docs/docs/pt/plugin-development/build.md index 0a5a3edbd68..c9b807387b9 100644 --- a/docs/docs/pt/plugin-development/build.md +++ b/docs/docs/pt/plugin-development/build.md @@ -1,5 +1,47 @@ # Construção +Após o desenvolvimento do plugin, são necessárias duas etapas — construção (compilar o código-fonte) e empacotamento (gerar o `.tar.gz`) — antes de distribuí-lo para outros aplicativos NocoBase. + +## Construir o Plugin + +A construção compila o código-fonte TypeScript em `src/` para JavaScript — o código do cliente é empacotado pelo Rsbuild e o código do servidor pelo tsup: + +```bash +yarn build @my-project/plugin-hello +``` + +O resultado da construção é gerado no diretório `dist/` da raiz do plugin. + +:::tip Dica + +Se o plugin foi criado no repositório de código-fonte, a primeira construção irá acionar uma verificação de tipo de todo o repositório, o que pode levar algum tempo. Recomenda-se garantir que as dependências estejam instaladas e que o repositório esteja em um estado construível. + +::: + +## Empacotar o Plugin + +O empacotamento comprime o resultado da construção em um arquivo `.tar.gz`, facilitando o upload para outros ambientes: + +```bash +yarn nocobase tar @my-project/plugin-hello +``` + +O arquivo empacotado é gerado por padrão em `storage/tar/@my-project/plugin-hello.tar.gz`. + +Você também pode usar o parâmetro `--tar` para combinar construção e empacotamento em uma única etapa: + +```bash +yarn build @my-project/plugin-hello --tar +``` + +## Fazer Upload para Outros Aplicativos NocoBase + +Faça o upload do arquivo `.tar.gz` e extraia-o para o diretório `./storage/plugins` do aplicativo de destino. Para mais detalhes, consulte [Instalar e Atualizar Plugins](../get-started/install-upgrade-plugins.mdx). + +### Ativar Plugin por Padrão + +Após o upload, o plugin não é ativado automaticamente — ele aparece no "Gerenciador de plugins" e precisa ser ativado manualmente. Se você estiver mantendo seu próprio aplicativo NocoBase e quiser que o plugin seja ativado por padrão junto com o aplicativo, você pode usar a variável de ambiente `APPEND_PRESET_BUILT_IN_PLUGINS` (adicionar plugins integrados padrão) para controlar isso; consulte [Definir Plugin como Padrão ou Ativado por Padrão](./write-your-first-plugin.md#definir-plugin-como-padrão-ou-ativado-por-padrão-opcional) para mais detalhes. + ## Configuração de Construção Personalizada Se você quiser personalizar a configuração de construção, você pode criar um arquivo `build.config.ts` na pasta raiz do **plugin** com o seguinte conteúdo: @@ -28,3 +70,12 @@ export default defineConfig({ }; }); ``` + +## Links Relacionados + +- [Escreva Seu Primeiro Plugin](./write-your-first-plugin.md) — Criando um plugin do zero, incluindo o fluxo completo de construção e empacotamento +- [Estrutura do Projeto de Plugins](./project-structure.md) — Entendendo o papel dos diretórios `packages/plugins`, `storage/tar` e outros +- [Gerenciamento de Dependências](./dependency-management.md) — Declaração de dependências do plugin e dependências globais +- [Visão Geral do Desenvolvimento de Plugins](./index.md) — Introdução geral ao desenvolvimento de plugins +- [Instalar e Atualizar Plugins](../get-started/install-upgrade-plugins.mdx) — Fazendo upload do arquivo empacotado para o ambiente de destino +- [Variáveis de Ambiente](../get-started/installation/env.md) — Configuração de variáveis de ambiente para plugins predefinidos, integrados e outros diff --git a/docs/docs/pt/plugin-development/write-your-first-plugin.md b/docs/docs/pt/plugin-development/write-your-first-plugin.md index 6c45d4f265f..0139fafcbe3 100644 --- a/docs/docs/pt/plugin-development/write-your-first-plugin.md +++ b/docs/docs/pt/plugin-development/write-your-first-plugin.md @@ -112,6 +112,33 @@ Após a ativação, crie uma nova página "Modern page (v2)". Ao adicionar bloco ![20250928174529](https://static-docs.nocobase.com/20250928174529.png) +### Definir Plugin como Padrão ou Ativado por Padrão (Opcional) + +O que foi descrito acima é como ativar um único plugin manualmente. Se você estiver mantendo seu próprio aplicativo NocoBase e quiser que determinados plugins estejam automaticamente prontos após executar `nocobase install` (instalação inicial) ou `nocobase upgrade` (atualização), você pode usar duas variáveis de ambiente para controlar o estado padrão dos plugins: + +- **`APPEND_PRESET_LOCAL_PLUGINS` (adicionar plugins locais predefinidos padrão)** — adiciona o plugin à lista de plugins locais predefinidos; após a instalação, ele aparece no "Gerenciador de plugins", mas não é ativado por padrão — você precisa ativá-lo manualmente +- **`APPEND_PRESET_BUILT_IN_PLUGINS` (adicionar plugins integrados padrão)** — adiciona o plugin à lista de plugins integrados; ele é ativado automaticamente durante a instalação e, como plugin integrado, **não pode ser desativado ou removido no "Gerenciador de plugins"** + +O valor de ambas as variáveis é o nome do pacote do plugin (o campo `name` no `package.json`), com múltiplos plugins separados por vírgulas. Configure assim no `.env`: + +```bash +# Predefinido por padrão: aparece na lista do gerenciador de plugins, mas não é ativado automaticamente +APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world + +# Ativado por padrão: instalado e ativado automaticamente, e não pode ser desativado na interface +APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world +``` + +Em geral, o `yarn pm enable` descrito anteriormente é suficiente para desenvolvimento e depuração local. Essas duas variáveis são mais adequadas para cenários de distribuição "pronto para uso" — por exemplo, quando você empacota um aplicativo NocoBase com plugins fixos e quer que eles estejam disponíveis imediatamente após a inicialização. + +:::tip Dica + +- O plugin precisa ter sido baixado localmente e ser resolvido no `node_modules`; consulte [Estrutura do Projeto de Plugins](./project-structure.md) +- Após a configuração, é necessário executar `nocobase install` ou `nocobase upgrade` novamente para que as alterações tenham efeito +- A descrição completa das variáveis de ambiente está em [Variáveis de Ambiente](../get-started/installation/env.md#append_preset_local_plugins) + +::: + ## Passo 4: Construa e Empacote Quando você estiver pronto para distribuir o plugin para outros ambientes, precisará primeiro construí-lo e depois empacotá-lo: @@ -129,4 +156,17 @@ Após a construção ser concluída, o arquivo empacotado estará localizado por ## Passo 5: Faça o Upload para Outro Aplicativo NocoBase -Faça o upload e extraia para o diretório `./storage/plugins` do aplicativo de destino. Para mais detalhes, consulte [Instalar e Atualizar Plugins](../get-started/install-upgrade-plugins.mdx). \ No newline at end of file +Faça o upload e extraia para o diretório `./storage/plugins` do aplicativo de destino. Para mais detalhes, consulte [Instalar e Atualizar Plugins](../get-started/install-upgrade-plugins.mdx). + +## Links Relacionados + +- [Visão Geral do Desenvolvimento de Plugins](./index.md) — Conheça a arquitetura de micronúcleo do NocoBase e o ciclo de vida dos plugins +- [Estrutura do Projeto de Plugins](./project-structure.md) — Convenções de diretório do projeto, caminhos de carregamento e prioridade dos plugins +- [Visão Geral do Desenvolvimento no Servidor](./server/index.md) — Introdução geral e conceitos centrais dos plugins do lado do servidor +- [Visão Geral do Desenvolvimento no Cliente](./client/index.md) — Introdução geral e conceitos centrais dos plugins do lado do cliente +- [Construção e Empacotamento](./build.md) — Fluxo de construção, empacotamento e distribuição dos plugins +- [Testes](./server/test.md) — Escrevendo casos de teste para plugins do servidor +- [Instalar usando create-nocobase-app](../get-started/installation/create-nocobase-app) — Uma das formas de instalar o NocoBase +- [Instalar a partir do código-fonte Git](../get-started/installation/git) — Instalar o NocoBase a partir do código-fonte +- [Instalar e Atualizar Plugins](../get-started/install-upgrade-plugins.mdx) — Fazer upload do plugin empacotado para outros ambientes +- [Variáveis de Ambiente](../get-started/installation/env.md) — Configuração de variáveis de ambiente para plugins predefinidos, integrados e outros \ No newline at end of file diff --git a/docs/docs/ru/get-started/installation/env.md b/docs/docs/ru/get-started/installation/env.md index 39e2d30051c..dba9702f3b1 100644 --- a/docs/docs/ru/get-started/installation/env.md +++ b/docs/docs/ru/get-started/installation/env.md @@ -375,8 +375,10 @@ SERVER_REQUEST_WHITELIST=1.2.3.4,10.0.0.0/8,api.example.com,*.trusted.com Используется для добавления предустановленных неактивных плагинов. Значением является имя пакета плагина (параметр `name` в `package.json`), несколько плагинов разделяются запятыми. :::info + 1. Убедитесь, что плагин загружен локально и его можно найти в каталоге `node_modules`. Подробнее см. [Структура проекта плагинов](/plugin-development/project-structure). 2. После добавления переменной среды плагин появится на странице менеджера плагинов только после первоначальной установки (`nocobase install`) или обновления (`nocobase upgrade`). + ::: ```bash @@ -388,8 +390,10 @@ APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar Используется для добавления встроенных плагинов, устанавливаемых по умолчанию. Значением является имя пакета плагина (параметр `name` в `package.json`), несколько плагинов разделяются запятыми. :::info + 1. Убедитесь, что плагин загружен локально и его можно найти в каталоге `node_modules`. Подробнее см. [Структура проекта плагинов](/plugin-development/project-structure). 2. После добавления переменной среды плагин будет автоматически установлен или обновлен во время первоначальной установки (`nocobase install`) или обновления (`nocobase upgrade`). + ::: ```bash diff --git a/docs/docs/ru/plugin-development/build.md b/docs/docs/ru/plugin-development/build.md index 5727542086d..4b56c77682d 100644 --- a/docs/docs/ru/plugin-development/build.md +++ b/docs/docs/ru/plugin-development/build.md @@ -1,5 +1,18 @@ # Сборка +### Включение плагина по умолчанию + +После загрузки плагин не активируется автоматически — он появится в «Менеджере плагинов» и его потребуется включить вручную. Если вы поддерживаете собственное приложение NocoBase и хотите, чтобы плагин активировался вместе с приложением по умолчанию, можно использовать переменную среды `APPEND_PRESET_BUILT_IN_PLUGINS` (добавить встроенные плагины). Подробнее см. в разделе [Предустановка и включение плагина по умолчанию](./write-your-first-plugin.md#предустановка-и-включение-плагина-по-умолчанию-необязательно). + +## Связанные ссылки + +- [Написание первого плагина](./write-your-first-plugin.md) — создание плагина с нуля, включая полный процесс сборки и упаковки +- [Структура проекта плагина](./project-structure.md) — назначение каталогов `packages/plugins`, `storage/tar` и других +- [Управление зависимостями](./dependency-management.md) — объявление зависимостей плагина и глобальные зависимости +- [Обзор разработки плагинов](./index.md) — общее введение в разработку плагинов +- [Установка и обновление плагинов](../get-started/install-upgrade-plugins.mdx) — загрузка упакованного плагина в целевую среду +- [Переменные среды](../get-started/installation/env.md) — настройка переменных среды для предустановленных и встроенных плагинов + ## Пользовательская конфигурация сборки Если вы хотите настроить конфигурацию сборки, вы можете создать файл `build.config.ts` в корневом каталоге плагина со следующим содержимым: diff --git a/docs/docs/ru/plugin-development/write-your-first-plugin.md b/docs/docs/ru/plugin-development/write-your-first-plugin.md index e5af723e0a8..1b1fd6f1ec4 100644 --- a/docs/docs/ru/plugin-development/write-your-first-plugin.md +++ b/docs/docs/ru/plugin-development/write-your-first-plugin.md @@ -112,6 +112,33 @@ export default { ![20250928174529](https://static-docs.nocobase.com/20250928174529.png) +### Предустановка и включение плагина по умолчанию (необязательно) + +Выше описан способ вручную включить отдельный плагин. Если вы поддерживаете собственное приложение NocoBase и хотите, чтобы определённые плагины были автоматически готовы к работе после выполнения `nocobase install` (первоначальная установка) или `nocobase upgrade` (обновление), можно использовать две переменные среды для управления состоянием плагинов по умолчанию: + +- **`APPEND_PRESET_LOCAL_PLUGINS` (добавить предустановленные плагины)** — добавляет плагин в список предустановленных локальных плагинов; после установки он появится в «Менеджере плагинов», но по умолчанию не будет активирован — потребуется включить его вручную +- **`APPEND_PRESET_BUILT_IN_PLUGINS` (добавить встроенные плагины)** — добавляет плагин в список встроенных плагинов; при установке он активируется автоматически, и как встроенный плагин **его нельзя отключить или удалить через «Менеджер плагинов»** + +Значением обеих переменных является имя пакета плагина (поле `name` в `package.json`); несколько плагинов разделяются запятыми. В файле `.env` конфигурация выглядит следующим образом: + +```bash +# Предустановка по умолчанию: плагин появляется в списке менеджера плагинов, но не активируется автоматически +APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world + +# Включение по умолчанию: автоматически устанавливается и активируется, отключить через интерфейс невозможно +APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world +``` + +Как правило, для локальной разработки и отладки достаточно команды `yarn pm enable`, описанной выше. Эти две переменные больше подходят для сценариев «готового к использованию» дистрибутива — например, когда вы упаковываете приложение NocoBase с фиксированным набором плагинов и хотите, чтобы они были доступны сразу после инициализации. + +:::tip Подсказка + +- Плагин должен быть загружен локально и доступен для разрешения в каталоге `node_modules`. См. [Структура проекта плагина](./project-structure.md) +- После настройки переменных необходимо повторно выполнить `nocobase install` или `nocobase upgrade`, чтобы изменения вступили в силу +- Полное описание переменных среды см. в разделе [Переменные среды](../get-started/installation/env.md#append_preset_local_plugins) + +::: + ## Шаг 4: Сборка и упаковка Когда вы будете готовы распространить плагин в другие среды, вам сначала потребуется его собрать и упаковать: @@ -129,4 +156,17 @@ yarn nocobase tar @my-project/plugin-hello ## Шаг 5: Загрузка в другое приложение NocoBase -Загрузите и распакуйте плагин в каталог `./storage/plugins` целевого приложения. Подробности см. в разделе [Установка и обновление плагинов](../get-started/install-upgrade-plugins.mdx). \ No newline at end of file +Загрузите и распакуйте плагин в каталог `./storage/plugins` целевого приложения. Подробности см. в разделе [Установка и обновление плагинов](../get-started/install-upgrade-plugins.mdx). + +## Связанные ссылки + +- [Обзор разработки плагинов](./index.md) — микроядерная архитектура NocoBase и жизненный цикл плагина +- [Структура проекта плагина](./project-structure.md) — соглашения о структуре каталогов, пути загрузки и приоритеты плагинов +- [Обзор серверной разработки](./server/index.md) — общее введение в серверные плагины и основные концепции +- [Обзор клиентской разработки](./client/index.md) — общее введение в клиентские плагины и основные концепции +- [Сборка и упаковка](./build.md) — процесс сборки, упаковки и распространения плагина +- [Тестирование](./server/test.md) — написание тестов для серверных плагинов +- [Установка с помощью create-nocobase-app](../get-started/installation/create-nocobase-app) — один из способов установки NocoBase +- [Установка из исходного кода Git](../get-started/installation/git) — установка NocoBase из исходного кода +- [Установка и обновление плагинов](../get-started/install-upgrade-plugins.mdx) — загрузка упакованного плагина в другие среды +- [Переменные среды](../get-started/installation/env.md) — настройка переменных среды для предустановленных и встроенных плагинов \ No newline at end of file diff --git a/docs/docs/vi/get-started/installation/env.md b/docs/docs/vi/get-started/installation/env.md index 3b7053aa7d9..345a44985ff 100644 --- a/docs/docs/vi/get-started/installation/env.md +++ b/docs/docs/vi/get-started/installation/env.md @@ -388,7 +388,8 @@ Dùng để thêm các Plugin được preset chưa được kích hoạt, giá 1. Cần đảm bảo Plugin đã được tải về local, và có thể tìm thấy trong thư mục `node_modules`, xem thêm tại [Cách tổ chức Plugin](/plugin-development/project-structure). 2. Sau khi thêm biến môi trường, cần thực hiện cài đặt khởi tạo `nocobase install` hoặc nâng cấp `nocobase upgrade` thì mới hiển thị trên trang quản lý Plugin. - ::: + +::: ```bash APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar @@ -402,7 +403,8 @@ Dùng để thêm các Plugin được preset và cài đặt mặc định, gi 1. Cần đảm bảo Plugin đã được tải về local, và có thể tìm thấy trong thư mục `node_modules`, xem thêm tại [Cách tổ chức Plugin](/plugin-development/project-structure). 2. Sau khi thêm biến môi trường, sẽ tự động cài đặt hoặc nâng cấp Plugin khi thực hiện cài đặt khởi tạo `nocobase install` hoặc nâng cấp `nocobase upgrade`. - ::: + +::: ```bash APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar diff --git a/docs/docs/vi/plugin-development/build.md b/docs/docs/vi/plugin-development/build.md index 538d4c6039a..fdddb56c77c 100644 --- a/docs/docs/vi/plugin-development/build.md +++ b/docs/docs/vi/plugin-development/build.md @@ -44,6 +44,10 @@ yarn build @my-project/plugin-hello --tar Upload và giải nén file `.tar.gz` vào thư mục `./storage/plugins` của ứng dụng đích. Các bước chi tiết xem tại [Cài đặt và nâng cấp Plugin](../get-started/install-upgrade-plugins.mdx). +### Tự động kích hoạt Plugin sau khi upload + +Sau khi upload, Plugin mặc định sẽ không được tự động kích hoạt — nó sẽ xuất hiện trong "Trình quản lý Plugin" và cần bạn bật thủ công. Nếu bạn đang duy trì ứng dụng NocoBase của riêng mình và muốn Plugin được kích hoạt mặc định cùng với ứng dụng, bạn có thể dùng biến môi trường `APPEND_PRESET_BUILT_IN_PLUGINS` (Thêm Plugin tích hợp mặc định) để kiểm soát, xem cách dùng tại [Đặt Plugin thành mặc định hoặc tự động kích hoạt](./write-your-first-plugin.md#đặt-plugin-thành-mặc-định-hoặc-tự-động-kích-hoạt-tùy-chọn). + ## Cấu hình build tùy chỉnh Thường thì cấu hình build mặc định là đủ dùng. Nếu bạn cần tùy chỉnh — như sửa entry đóng gói, thêm alias, điều chỉnh tùy chọn nén, v.v. — bạn có thể tạo file `build.config.ts` trong thư mục gốc Plugin: @@ -84,3 +88,4 @@ Một vài điểm chính: - [Quản lý dependency](./dependency-management.md) — Khai báo dependency của Plugin và dependency toàn cục - [Tổng quan phát triển Plugin](./index.md) — Giới thiệu tổng thể về phát triển Plugin - [Cài đặt và nâng cấp Plugin](../get-started/install-upgrade-plugins.mdx) — Upload file đóng gói sang môi trường đích +- [Biến môi trường](../get-started/installation/env.md) — Cấu hình biến môi trường cho Plugin preset, Plugin tích hợp, v.v. diff --git a/docs/docs/vi/plugin-development/write-your-first-plugin.md b/docs/docs/vi/plugin-development/write-your-first-plugin.md index de5d413e708..df6e60e3437 100644 --- a/docs/docs/vi/plugin-development/write-your-first-plugin.md +++ b/docs/docs/vi/plugin-development/write-your-first-plugin.md @@ -118,6 +118,33 @@ Sau khi kích hoạt, hãy tạo một trang "Modern page (v2)" mới, khi thêm ![20250928174529](https://static-docs.nocobase.com/20250928174529.png) +### Đặt Plugin thành mặc định hoặc tự động kích hoạt (tùy chọn) + +Ở trên là cách bật từng Plugin thủ công. Nếu bạn đang duy trì ứng dụng NocoBase của riêng mình và muốn một số Plugin tự động sẵn sàng sau khi chạy `nocobase install` (cài đặt lần đầu) hoặc `nocobase upgrade` (nâng cấp), bạn có thể dùng hai biến môi trường để kiểm soát trạng thái mặc định của Plugin: + +- **`APPEND_PRESET_LOCAL_PLUGINS` (Thêm Plugin preset mặc định)** — Thêm Plugin vào danh sách Plugin preset local, sau khi cài đặt Plugin sẽ xuất hiện trong "Trình quản lý Plugin", nhưng mặc định không kích hoạt, cần bạn bật thủ công +- **`APPEND_PRESET_BUILT_IN_PLUGINS` (Thêm Plugin tích hợp mặc định)** — Thêm Plugin vào danh sách Plugin tích hợp, Plugin sẽ được tự động kích hoạt khi cài đặt, và vì là Plugin tích hợp nên **không thể tắt hay xóa trong "Trình quản lý Plugin"** + +Giá trị của cả hai biến là tên package của Plugin (trường `name` trong `package.json`), nhiều Plugin phân tách bằng dấu phẩy tiếng Anh. Cấu hình trong file `.env` như sau: + +```bash +# Preset mặc định: xuất hiện trong danh sách Trình quản lý Plugin, nhưng không tự động kích hoạt +APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world + +# Tự động kích hoạt: tự động cài đặt và kích hoạt, và không thể tắt trên giao diện +APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world +``` + +Thông thường, `yarn pm enable` ở trên là đủ cho phát triển và debug local. Hai biến này phù hợp hơn cho các kịch bản phát hành "mở hộp là dùng được" — ví dụ khi bạn đóng gói một ứng dụng NocoBase kèm theo bộ Plugin cố định và muốn Plugin sẵn sàng ngay sau khi khởi tạo. + +:::tip Mẹo + +- Plugin cần đã được tải về local và có thể tìm thấy trong `node_modules`, xem [Cấu trúc thư mục dự án](./project-structure.md) +- Sau khi cấu hình, cần chạy lại `nocobase install` hoặc `nocobase upgrade` thì mới có hiệu lực +- Xem đầy đủ các biến môi trường tại [Biến môi trường](../get-started/installation/env.md#append_preset_local_plugins) + +::: + ## Bước 4: Build và đóng gói Khi bạn chuẩn bị phân phối Plugin sang môi trường khác, cần build trước rồi đóng gói: @@ -158,3 +185,4 @@ Upload và giải nén file đóng gói vào thư mục `./storage/plugins` củ - [Cài đặt bằng create-nocobase-app](../get-started/installation/create-nocobase-app) — Một trong các cách cài đặt NocoBase - [Cài đặt từ source code Git](../get-started/installation/git) — Cài đặt NocoBase từ source code - [Cài đặt và nâng cấp Plugin](../get-started/install-upgrade-plugins.mdx) — Upload Plugin đã đóng gói sang môi trường khác +- [Biến môi trường](../get-started/installation/env.md) — Cấu hình biến môi trường cho Plugin preset, Plugin tích hợp, v.v.