From 00dc22d812a4a6e6021ada38401fe2b295eec852 Mon Sep 17 00:00:00 2001 From: Josh <37798644+joshuaellis@users.noreply.github.com> Date: Tue, 20 Feb 2024 13:35:19 +0000 Subject: [PATCH] feat: add plugin cli docs page (#1965) * feat: add plugin cli docs page * chore: edit create-a-plugin page * Fix unwanted line indentation changes * Split content into a guide and a reference * Add guide to plugins development intro. * Add Plugin CLI docs to TOC * Fix capitalization * Fix SEO for reference page --------- Co-authored-by: Pierre Wizla --- .../dev-docs/plugins/developing-plugins.md | 1 + .../plugins/development/create-a-plugin.md | 53 +++-- .../plugins/development/plugin-cli.md | 87 ++++++++ .../plugins/guides/use-the-plugin-cli.md | 185 ++++++++++++++++++ docusaurus/sidebars.js | 8 + 5 files changed, 307 insertions(+), 27 deletions(-) create mode 100644 docusaurus/docs/dev-docs/plugins/development/plugin-cli.md create mode 100644 docusaurus/docs/dev-docs/plugins/guides/use-the-plugin-cli.md diff --git a/docusaurus/docs/dev-docs/plugins/developing-plugins.md b/docusaurus/docs/dev-docs/plugins/developing-plugins.md index 822166d003..a1bd5e7e3f 100644 --- a/docusaurus/docs/dev-docs/plugins/developing-plugins.md +++ b/docusaurus/docs/dev-docs/plugins/developing-plugins.md @@ -41,6 +41,7 @@ Plugins can also be used to add [custom fields](/dev-docs/custom-fields) to Stra +
diff --git a/docusaurus/docs/dev-docs/plugins/development/create-a-plugin.md b/docusaurus/docs/dev-docs/plugins/development/create-a-plugin.md index e930d30809..5137f58fa2 100644 --- a/docusaurus/docs/dev-docs/plugins/development/create-a-plugin.md +++ b/docusaurus/docs/dev-docs/plugins/development/create-a-plugin.md @@ -14,6 +14,7 @@ To start developing a Strapi plugin, you need to: :::prerequisites You created a Strapi project. +
Use the CLI to create a project: @@ -40,6 +41,7 @@ npx create-strapi-app@latest my-project --quickstart More details can be found in the [CLI installation guide](/dev-docs/installation/cli). +
::: @@ -51,21 +53,21 @@ The fastest way to create a Strapi plugin is to use the CLI generator. To do so: 2. Run the following command in a terminal window to start the interactive CLI: - + ```sh - yarn strapi generate plugin + yarn strapi generate plugin ``` - + - + ```sh npm run strapi generate plugin ``` - + 4. Choose either `JavaScript` or `TypeScript` for the plugin language. @@ -80,22 +82,23 @@ To enable a plugin: 2. Enable the plugin by adding the following code to the plugins configuration file: - + - ```js title="./config/plugins.js" - module.exports = { - // ... - "my-plugin": { // name of your plugin, kebab-cased - enabled: true, - resolve: "./src/plugins/my-plugin", // path to the plugin folder - }, - // ... - }; - ``` + ```js title="./config/plugins.js" + module.exports = { + // ... + "my-plugin": { + // name of your plugin, kebab-cased + enabled: true, + resolve: "./src/plugins/my-plugin", // path to the plugin folder + }, + // ... + }; + ``` - + - + ```js title=./config/plugins.ts export default { @@ -108,7 +111,7 @@ To enable a plugin: }; ``` - + :::tip @@ -146,10 +149,10 @@ Once the plugin code has been generated and the plugin is enabled, the next step 3. Navigate back to the Strapi project root with `cd ../../..` and run the following command to build the admin panel and start the server(s): - + - + ```sh yarn develop ``` @@ -157,7 +160,7 @@ Once the plugin code has been generated and the plugin is enabled, the next step - + ```sh npm run develop ``` @@ -225,7 +228,7 @@ Once the plugin code has been generated and the plugin is enabled, the next step - + ```sh npm run develop ``` @@ -242,10 +245,6 @@ You should now be ready to start developing your plugin. You can either jump to the [plugin structure](/dev-docs/plugins/development/plugin-structure) documentation or read the [servers and hot reloading](#servers-and-hot-reloading) section to learn more about different ways to start the server. ::: -:::info Did you know? -The admin panel needs to be rebuilt after its code has been modified. Rebuilding the admin panel is done by running the `build` command. The `strapi generate plugin` generates code that injects some plugin components (menu link, plugin homepage) into the admin panel. That's why we run the `build` command after the plugin code has been generated and before starting the server. -::: - ### Servers and hot reloading Strapi itself is **headless** . The admin panel is completely separate from the server. diff --git a/docusaurus/docs/dev-docs/plugins/development/plugin-cli.md b/docusaurus/docs/dev-docs/plugins/development/plugin-cli.md new file mode 100644 index 0000000000..7726a84d79 --- /dev/null +++ b/docusaurus/docs/dev-docs/plugins/development/plugin-cli.md @@ -0,0 +1,87 @@ +--- +title: Plugin CLI +description: Reference documentation for Strapi's Plugin CLI commands +displayed_sidebar: devDocsSidebar +--- + +# Plugin CLI reference + +:::caution +The Plugin CLI is currently experimental. +::: + +The Plugin CLI is set of commands orientated around developing plugins to use them as local plugins or to publish them on NPM and/or submit them to the Marketplace. + +The present documentation lists the available Plugin CLI commands. The [associated guide](/dev-docs/plugins/guides/use-the-plugin-cli) illustrates how to use these commands to create a plugin from scratch, link it to an existing project, and publish it. + +## strapi plugin:init + +Create a new plugin at a given path. + +```bash +strapi plugin:init +``` + +| Arguments | Type | Description | Default | +| --------- | :----: | --------------------| ------------------------- | +| `path` | string | Path to the plugin | `./src/plugins/my-plugin` | + +| Option | Type | Description | Default | +| ------------- | :--: | ---------------------------------------- |---------| +| `-d, --debug` | - | Enable debugging mode with verbose logs | false | +| `--silent` | - | Do not log anything | false | + +## strapi plugin:build + +Bundle the strapi plugin for publishing. + +```bash +strapi plugin:build +``` + +| Option | Type | Description | Default | +| -------------- | :----: | ----------------------------------------------------------------------------------------------------------------- | --------| +| `--force` | string | Automatically answer "yes" to all prompts, including potentially destructive requests, and run non-interactively. | - | +| `-d, --debug` | - | Enable debugging mode with verbose logs | false | +| `--silent` | - | Do not log anything | false | +| `--minify` | - | Minify the output | true | +| `--sourcemaps` | - | Produce sourcemaps | false | + +## strapi plugin:link-watch + +Recompiles the plugin automatically on changes and runs `yalc push --publish`. + +```bash +strapi plugin:link-watch +``` + +| Option | Type | Description | Default | +| ------------- | :--: | -------------------------------------------------------- | --------| +| `-d, --debug` | - | Enable debugging mode with verbose logs | false | +| `--silent` | - | Do not log anything | false | + +## strapi plugin:watch + +Watch and compile the Strapi plugin for local development. + +```bash +strapi plugin:watch +``` + +| Option | Type | Description | Default | +| ------------- | :--: | -------------------------------------------------------- |---------| +| `-d, --debug` | - | Enable debugging mode with verbose logs | false | +| `--silent` | - | Do not log anything | false | + +## strapi plugin:verify + +Verify the output of the plugin before publishing it. + +```bash +strapi plugin:verify +``` + +| Option | Type | Description | Default | +| ------------- | :--: | -------------------------------------------------------- | --------| +| `-d, --debug` | - | Enable debugging mode with verbose logs | false | +| `--silent` | - | Do not log anything | false | diff --git a/docusaurus/docs/dev-docs/plugins/guides/use-the-plugin-cli.md b/docusaurus/docs/dev-docs/plugins/guides/use-the-plugin-cli.md new file mode 100644 index 0000000000..a26e79ba4e --- /dev/null +++ b/docusaurus/docs/dev-docs/plugins/guides/use-the-plugin-cli.md @@ -0,0 +1,185 @@ +--- +title: How to use the Plugin CLI to build and publish a Strapi plugin +description: Learn how to use the Plugin CLI to build and publish a Strapi plugin +sidebar_label: Use the Plugin CLI +displayed_sidebar: devDocsSidebar +--- + +# How to use the Plugin CLI to create and publish a Strapi plugin + +:::caution +The Plugin CLI is currently experimental. +::: + +The Plugin CLI is set of commands orientated around developing plugins to use them as local plugins or to publish them on NPM and/or submit them to the Marketplace. + +As opposed to the `strapi generate plugin` command (see [plugin creation and setup](/dev-docs/plugins/development/create-a-plugin)) you do not need to set up a Strapi project to use the Plugin CLI. + +The present guide covers creating a plugin from scratch, linking it to an existing Strapi project, and publishing the plugin. If you already have an existing plugin, you can instead retrofit the plugin setup to utilise the Plugin CLI commands (please refer to the [Plugin CLI reference](/dev-docs/plugins/development/plugin-cli) for a full list of available commands). + +## Getting started with the Plugin CLI + +:::note +This guide assumes you want to develop a plugin external to your Strapi project. However, the steps largely remain the same if you want to develop a plugin within your existing project. If you are not [using a monorepo](#working-with-the-plugin-cli-in-a-monorepo-environment) the steps are exactly the same. +::: + +### Creating the plugin + +To create your plugin, ensure you are in the parent directory of where you want it to be created and run the following command: + + + + + +```bash +yarn dlx @strapi/strapi plugin:init my-strapi-plugin +``` + + + + + +```bash +npx @strapi/strapi plugin:init my-strapi-plugin +``` + + + + + +The path `my-strapi-plugin` can be replaced with whatever you want to call your plugin, including the path to where it should be created (e.g., `code/strapi-plugins/my-new-strapi-plugin`). + +You will be ran through a series of prompts to help you setup your plugin. If you selected yes to all options the final structure will be similar to the default [plugin structure](/dev-docs/plugins/development/plugin-structure). + +### Linking the plugin to your project + +Once you created your plugin, you will want to register it with the [yalc](https://github.com/wclr/yalc) repository (it's local to your machine). To do this, run the following command: + + + + + +```bash +cd my-strapi-plugin +yarn install +yarn link-watch +``` + + + + + +```bash +cd my-strapi-plugin +npm install +npm run link-watch +``` + + + + + +This will then produce an output explaing how to link your plugin to your Strapi project. Open a new terminal window to do the next steps: + + + + + +```bash +cd /path/to/strapi/project +yarn dlx yalc add --link my-strapi-plugin && yarn install +``` + + + + + +```bash +cd /path/to/strapi/project +npx yalc add --link my-strapi-plugin && npm run install +``` + + + + + +:::note +In the above examples we use the name of the plugin when linking it to the project. This is the name of the package, not the name of the folder. +::: + +Because this plugin is installed via `node_modules` you won't need to explicity add it to your `plugins` [configuration file](/dev-docs/configurations/plugins), so running the [`develop command`](../../cli.md#strapi-develop) will automatically pick up your plugin. However, to improve your experience we recommend you run Strapi with the `--watch-admin` flag so that your admin panel is automatically rebuilt when you make changes to your plugin: + + + + + +```bash +yarn develop --watch-admin +``` + + + + + +```bash +npm run develop --watch-admin +``` + + + + + +You are now ready to develop your plugin how you see fit! If you are making server changes, you will need to restart your server for them to take effect. + +### Building the plugin for publishing + +When you are ready to publish your plugin, you will need to build it. To do this, run the following command: + + + + + +```bash +yarn build && yarn verify +``` + + + + + +```bash +npm run build && npm run verify +``` + + + + + +The above commands will not only build the plugin, but also verify that the output is valid and ready to be published. You can then publish your plugin to NPM as you would any other package. + +## Working with the plugin CLI in a monorepo environment + +If you are working with a monorepo environment to develop your plugin, you don't need to use the `link-watch` command because the monorepo workspace setup will handle the symlink. You can use the `watch` command instead. + +However, if you are writing admin code, you might add an `alias` that targets the source code of your plugin to make it easier to work with within the context of the admin panel: + +```ts +import path from "node:path"; + +export default (config, webpack) => { + config.resolve.alias = { + ...config.resolve.alias, + "my-strapi-plugin": path.resolve( + __dirname, + // We've assumed the plugin is local. + "../plugins/my-strapi-plugin/admin/src" + ), + }; + + return config; +}; +``` + +:::caution +Because the server looks at the `strapi-server.js` file to import your plugin code, you must use the `watch` command otherwise the code will not be transpiled and the server will not be able to find your plugin. +::: diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index fcccf27a3c..bec0c5d7e3 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -447,6 +447,7 @@ const sidebars = { id: 'dev-docs/api/plugins/server-api', label: 'Server API', }, + 'dev-docs/plugins/development/plugin-cli', 'dev-docs/custom-fields', 'dev-docs/plugins-extension', { @@ -459,6 +460,13 @@ const sidebars = { items: [ 'dev-docs/plugins/guides/store-and-access-data', 'dev-docs/plugins/guides/pass-data-from-server-to-admin', + { + type: 'doc', + id: 'dev-docs/plugins/guides/use-the-plugin-cli', + customProps: { + new: true, + } + } ] } ]