To create a custom plugin, begin with boilerplate code that can be used for any kind of plugin. This doc describes the boilerplate code and how to get started with your custom plugin.
First, create a directory for your custom plugin.
mkdir my-custom-plugin
cd my-custom-pluginCreate a package.json file and fill it with the following contents.
{
"name": "custom-plugins",
"version": "1.0.0",
"description": "",
"entry": "plugin",
"output": "plugin.system.js",
"main": "dist/plugin.system.js",
"files": [
"dist"
],
"scripts": {
"build": "webpack --mode production",
"start": "webpack-dev-server --mode development"
},
"author": "",
"license": "ISC",
"devDependencies": {
"@babel/preset-react": "^7.18.6",
"@builder.io/app-context": "^1.0.0",
"@builder.io/react": "^2.0.13",
"@emotion/core": "^11.0.0",
"babel-loader": "^8.2.5",
"webpack": "^5.74.0",
"webpack-cli": "^4.10.0",
"webpack-dev-server": "^4.10.0"
}
}
There are several key aspects of this file which aid in creating a custom plugin.
The entry, output, main, and files keys describe where the final compiled files of your plugin can be found. If you choose to edit these values, you must make adjustments to your webpack.config.js file.
There are two scripts within this file:
- The build script compiles your plugin to a smaller, more performant script. This script lives in the
dist/directory. - The start script runs the compiled plugin from your
dist/directory, making it accessible locally. This is required to develop and test your plugin locally.
Keep in mind that, while using the start script, you still need to refresh your Builder page to access the latest version of your custom plugin.
There are several key packages that are required as part of the development process for your custom plugin.
| Package | Description |
|---|---|
| Exposes certain APIs to interact with Builder |
| Enables you to use React to create your plugin |
| Module bundler for JavaScript |
| Development server with live reloading |
| Supports |
| Transpiles modern and superset JavaScript, such as |
All of these packages can be listed as developer dependencies in your package.json file, since Builder provides any necessary ones for your custom plugin.
If your plugin requires an external library outside of these, install it as a regular dependency.
Create a .babelrc file and fill it with the following contents.
// contents of .babelrc
// use preset-react to support JSX
{
"presets": ["@babel/preset-react"],
"env": {
"development": {
"presets": [["@babel/preset-react", { "development": true }]]
}
}
}
This file supports JSX and React.
Create a webpack.config.js file and fill it with the following contents.
// contents of webpack.config.js
const path = require("path");
const pkg = require("./package.json");
module.exports = {
entry: `./src/${pkg.entry}.jsx`,
externals: {
"@builder.io/react": "@builder.io/react",
"@builder.io/app-context": "@builder.io/app-context",
"@emotion/core": "@emotion/core",
react: "react",
"react-dom": "react-dom",
},
output: {
filename: pkg.output,
path: path.resolve(__dirname, "dist"),
libraryTarget: "system",
},
resolve: {
extensions: [".js", ".jsx"],
},
module: {
rules: [
{
test: /\.(jsx)$/,
exclude: /node_modules/,
use: [
{
loader: "babel-loader",
},
],
},
],
},
devServer: {
port: 1268,
client: {
overlay: false,
},
static: {
directory: path.join(__dirname, "./dist"),
},
headers: {
"Access-Control-Allow-Private-Network": "true",
"Access-Control-Allow-Origin": "*",
},
},
};
This file enables the compilation of your custom plugin. For more details on how this configuration file works, visit webpack's configuration documentation.
Note that the port key for the development server is set to 1268. This is important for connecting your development process to your Builder Space.
First, create a src/ directory and create a plugin.jsx file within that directory.
mkdir src
touch src/plugin.jsxFill your plugin.jsx file with the following contents:
// The jsx pragma and import replace React.createElement with Emotion's jsx factory,
// enabling the css prop for inline Emotion styling on JSX elements.
/** @jsx jsx */
import { jsx } from "@emotion/core";
// Import the Builder SDK, which provides the Builder global and APIs for registering plugins.
import { Builder } from "@builder.io/react";
// Register your plugin here.
alert("Hello from your plugin!");
This file launches an alert box when it is successfully loaded. Use this as a check that your plugin has been loaded successfully.
To enable custom plugins within your Builder Space:
- Go to your Space Settings.
- Find where it says Plugins within the Integrations section of the Space tab.
- Click the Edit button.
Add custom plugins through this interface. Builder requires a path to your custom plugin, which can either be a direct URL or an npm package.
Assuming you have not changed any of the values above, add the following URL as a new plugin:
http://localhost:1268/plugin.system.jsWithin your application's directory run npm start. This enables your plugin in development mode.
To check that the example plugin.jsx file detailed above is working, navigate to any page within your Builder Space. A pop-up appears, as dictated by the code.