Skip to main content

Create a new plugin

Learn how to create a new plugin with actions and run it locally.

Helpful resources

1. Create a new GitHub repository​

The repository will be used to store the plugin code and configuration.

Open the GitHub repository creation page and follow the instructions below.

  1. Select the Owner of the repository.
  2. Enter the Repository name. This is also the name of your future plugin. We recommend using the snake case naming convention. For example, if you decide to call your plugin My first plugin, the repository name should be my-first-plugin.
  3. Select the Public repository visibility.
  4. Select the Add a README file option to initialize the repository with a README file. It will also create a new default branch for the repository.
  5. Choose the MIT License as the license for the repository.
  6. Please ensure the branch name is main as it is used across the docs. You can use any branch name but must be aware of it when following the docs.
  7. Click the Create repository button.
tip

We sincerely encourage making plugins public and open-source under the MIT license to make them available to the community and grow the plugin ecosystem.

2. Create a codespace​

Codespace development environment is the fastest way to start plugin development without installing additional software on your machine.

Use the green Code button in the top right corner of your repository. Then open the Codespaces tab and click Create codespace on main. It will start the codespace creation process.

info

GitHub Codespaces are free of charge for 120 hours per month for personal accounts. The codespace will stop running after a period of inactivity to safe resources. By default, this period is 30 minutes.

If you prefer a local development environment, skip this step, clone the repository, open it in your favorite IDE, and continue with the next steps. In this case, ensure you have the latest stable version of Node.js installed.

3. Initialize the plugin repository​

Use the connery dev init CLI command to initialize the plugin repository with all the necessary files and configuration.

npx connery@latest dev init

4. Install dependencies​

To continue, you must install all the dependencies defined in the ./package.json file. Run the following command to install the dependencies.

npm install

5. Add a new action to the plugin (optional)​

Use the connery dev add-action CLI command to add a new action to the plugin.

npx connery@latest dev add-action

6. Implement the action (optional)​

Open the ./src/actions directory and find the newly created action file, define input and output parameters of the action and implement the logic of the action in the handler function.

During the development, you may need to install additional dependencies. For example, the axios package to make HTTP requests to external APIs. To install it and add it to the ./package.json file, run the following command:

npm install axios --save

In the same way, you can install any other NPM package.

Helpful resources

7. Start the plugin server​

Run the following command to start the plugin server.

npm start

The plugin server is configured with default values in the .env file generated during the initialization. So you can start the server without any additional configuration.

Once the plugin server is running, you can access its main page at localhost:4201 in your browser.

Check the Plugin server documentation to learn more.

8. Run the action (optional)​

Let's run the sample action from the plugin to see how it works. This is helpful to test the action during the development process.

Use the following command to run the action from the plugin. You should receive a response with the result of the action execution. The plugin server must be running to call the action.

curl -X 'POST' \
  'http://localhost:4201/api/actions/sampleAction/run' \
  -H 'accept: application/json' \
  -H 'x-api-key: 123456' \
  -H 'Content-Type: application/json' \
  -d '{
  "input": {
    "number1": "1",
    "number2": "2"
  }
}'

In this example, we use a default URL of the plugin server http://localhost:4201, the name of the sample action sampleAction generated during the initialization process, and the input parameters expected by the action: number1, number2. Also, we use a default x-api-key value, 123456, to authenticate the request.

9. Commit the files​

Run the following command to commit and push all the files to GitHub.


git add . && git commit -m "Init plugin repository" && git push origin main

caution

Please make sure you delete all the secrets you might be used during testing before pushing the changes to the repository.

Next steps​

Now, when you have a new plugin, let's learn how to use the plugin and its actions using clients.