diff --git a/docs/plugins/assets/private-plugins/add-new-plugin.png b/docs/plugins/assets/private-plugins/add-new-plugin.png index ca102670..d5a183a8 100644 Binary files a/docs/plugins/assets/private-plugins/add-new-plugin.png and b/docs/plugins/assets/private-plugins/add-new-plugin.png differ diff --git a/docs/plugins/assets/private-plugins/configure-git-settings.png b/docs/plugins/assets/private-plugins/configure-git-settings.png index 28d15d55..c8f3ce1c 100644 Binary files a/docs/plugins/assets/private-plugins/configure-git-settings.png and b/docs/plugins/assets/private-plugins/configure-git-settings.png differ diff --git a/docs/plugins/assets/private-plugins/configure-plugin.png b/docs/plugins/assets/private-plugins/configure-plugin.png new file mode 100644 index 00000000..0699dccd Binary files /dev/null and b/docs/plugins/assets/private-plugins/configure-plugin.png differ diff --git a/docs/plugins/assets/private-plugins/disable-dev-version.png b/docs/plugins/assets/private-plugins/disable-dev-version.png new file mode 100644 index 00000000..6ddf1f5b Binary files /dev/null and b/docs/plugins/assets/private-plugins/disable-dev-version.png differ diff --git a/docs/plugins/assets/private-plugins/enable-dev-versions.png b/docs/plugins/assets/private-plugins/enable-dev-versions.png new file mode 100644 index 00000000..8bb4d5cd Binary files /dev/null and b/docs/plugins/assets/private-plugins/enable-dev-versions.png differ diff --git a/docs/plugins/private-plugins.md b/docs/plugins/private-plugins.md index 28347bd2..341bdbe9 100644 --- a/docs/plugins/private-plugins.md +++ b/docs/plugins/private-plugins.md @@ -43,17 +43,6 @@ Never use the same repository for private plugins and generated services to avoi ![Publish Your Platform Console Changes](./assets/private-plugins/configure-git-settings.png) -## Add a New Private Plugin - -Next, add a new private plugin to your Platform Console: - -1. In the Private Plugins tab's sidebar, click the `Add Private Plugin` field -2. Enter a unique name using kebab-case (e.g., `acme-corp-authentication`) -3. Set the plugin's **Display Name** and **Description** - these will appear in the UI when selecting plugins -4. Choose the appropriate code generator (Node.js or .NET) that matches your target services - -![Publish Your Platform Console Changes](./assets/private-plugins/add-new-plugin.png) - ## Set Up Your Private Plugin Folder After creating the plugin entry in the Platform Console, set up your development environment. @@ -122,54 +111,72 @@ Follow the steps below to complete this process: mv plugins/dotnet-db-postgres your-plugin-id ``` -## Develop Your Plugin +## Add a New Private Plugin -Now that your plugin structure is set up, it's time to start building your plugin. -We've prepared several resources and reference materials to help guide your plugin development process. +Next, add a new private plugin to your Platform Console: -Core Documentation: +1. In the Private Plugins tab's sidebar, click the `Add Private Plugin` field +2. A modal appears that scans your connected Git repository for private plugins +3. Select your plugin from the list of found plugins -- [Private Plugins Overview](https://docs.amplication.com/plugins/overview/) -- [.NET Plugin Events Reference Guide](https://docs.amplication.com/plugins/dotnet-plugin-events/create-server/) -- [Node.js Plugin Events Reference Guide](https://docs.amplication.com/plugins/plugin-events/create-server/) +:::note +Only plugins that are properly structured within the `plugins` folder of your connected Git repository will be detected. +::: -Community Plugin Examples: +![Publish Your Platform Console Changes](./assets/private-plugins/add-new-plugin.png) -- Browse the [official plugins repository](https://github.com/amplication/plugins/tree/master/plugins) for real-world examples +## Configure Your Plugin -:::note -Study the published Node.js and .NET community plugins for best practices and guidance on how to structure your code effectively. +After adding your plugin, you'll need to configure its settings: + +1. **Plugin ID**: Automatically set based on your plugin's folder name in the Git repository. This can only be modified by renaming the folder and re-adding the plugin. +2. **Display Name**: The human-readable name for your plugin that appears in the UI. By default, it matches the Plugin ID but can be customized for better clarity. +3. **Icon**: Choose from a variety of technology-specific icons to help visually identify your plugin. You can also customize the icon's color to match your categorization system. +4. **Code Generator**: Select the appropriate code generator for your plugin: + - Node.js + - .NET + - Blueprints (for custom blueprint solutions) +5. **Blueprint Compatibility**: Optionally restrict your plugin to work with specific blueprints by selecting them from the dropdown menu. +6. **Description**: Provide a detailed description of your plugin's purpose. A detailed description helps developers quickly understand and choose the right plugin for their needs. + +:::tip +A meaningful display name, icon, and description will help developers quickly identify and understand your plugin's purpose when browsing the plugin list in services and templates. ::: -## Add Versions to Your Plugin +![Configure Your Private Plugin's Settings](./assets/private-plugins/configure-plugin.png) -After developing your plugin, you'll need to version it both in Amplication and your Git repository. -First, let's add a version through the Amplication UI: +## Develop Your Plugin -1. Navigate to the Private Plugins tab and select your plugin -2. Scroll to **Add New Version** and click `Add Version` -3. Note the version number you assign (e.g., `0.1.0`) +Now that your plugin structure is set up, it's time to start building your plugin. -![Publish Your Platform Console Changes](./assets/private-plugins/add-new-version.png) +First, enable dev versions by toggling the `Enable Dev Version` into the on state. -## Tag Your Git Repository +![Enable Dev Versions](./assets/private-plugins/enable-dev-versions.png) -Next, let's add a git tag to your plugin. -Amplication uses Git tags to identify plugin versions during code generation. +Dev Versions streamline the plugin development process by automatically using the latest code from your repository's base branch. +This eliminates the need to publish new versions during development and testing. -Create a tag with your Plugin ID and version from the previous step: +Dev Versions makes the development process much smoother. +The plugin code will be pulled from the base branch set at the Git Settings. +The new changes in your plugin folder are immediately available for testing. -```bash -git tag "your-plugin-id@0.1.0" -``` +Next, we've prepared several resources and reference materials to help guide your plugin development process. -Push the tag to your remote repository: +Core Documentation: -```bash -git push origin "your-plugin-id@0.1.0" -``` +- [Private Plugins Overview](https://docs.amplication.com/plugins/overview/) +- [.NET Plugin Events Reference Guide](https://docs.amplication.com/plugins/dotnet-plugin-events/create-server/) +- [Node.js Plugin Events Reference Guide](https://docs.amplication.com/plugins/plugin-events/create-server/) + +Community Plugin Examples: -## Configure Plugin Settings +- Browse the [official plugins repository](https://github.com/amplication/plugins/tree/master/plugins) for real-world examples + +:::note +Study the published Node.js and .NET community plugins for best practices and guidance on how to structure your code effectively. +::: + +### Add Plugin Settings Plugin settings allow you to define customizable options that users can configure when using your plugin. These settings can include API keys, feature flags, or other configuration values that modify your plugin's behavior. @@ -196,7 +203,45 @@ For a real-world example of using settings in your plugin, see the [Supertokens ## Publish Your Plugin -After adding a version to your plugin, configuring your plugin settings, and tagging your repository, it's time to publish your plugin. Publishing makes your plugin version available for use in services and templates, and sets it as the latest version. +After developing your plugin it's time to get it for release. +To do this, you'll need to add a version to your plugin, tag your repository, and finally publish it through the Amplication UI. + +Publishing makes your plugin version available for use in services and templates, and sets it as the latest version. + +### Add Versions to Your Plugin + +After developing your plugin and to get it ready for release, you'll need to version it in both Amplication and your Git repository. + +First, disable dev versions by toggling the `Enable Dev Version` into the off state. + +![Disable Dev Versions](./assets/private-plugins/disable-dev-version.png) + +Next, let's add a version through the Amplication UI: + +1. Navigate to the Private Plugins tab and select your plugin +2. Scroll to **Add New Version** and click `Add Version` +3. Note the version number you assign (e.g., `0.1.0`) + +![Publish Your Platform Console Changes](./assets/private-plugins/add-new-version.png) + +### Tag Your Git Repository + +Next, let's add a git tag to your plugin. +Amplication uses Git tags to identify plugin versions during code generation. + +Create a tag with your Plugin ID and version from the previous step: + +```bash +git tag "your-plugin-id@0.1.0" +``` + +Push the tag to your remote repository: + +```bash +git push origin "your-plugin-id@0.1.0" +``` + +### Publish Your Plugin 1. Go to your Platform Console 2. Click on "Publish New Version" in your Platform Changes sidebar