Create a plugin

Learn how to create a new plugin with actions.

1. Create a new GitHub repository

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

Steps to create a repository

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.

2. Set up development environment

Open the plugin repository in GitHub Codespaces or clone it on your local machine.

More about GitHub Codespaces

GitHub Codespace is the fastest way to start a development environment 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.

GitHub Codespaces are free of charge for 120 hours per month for personal accounts.

By default, a codespace stops running after 30 minutes of inactivity to safe resources.

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

This command will also create a sample action for you to explore and test.

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 the input and output parameters of the action and implement the logic of the action in the handler function.

Use the sample action as an example and draw inspiration from existing open-source plugins.

Install additional NPM packages if required

During the development, you may need to install additional packages. 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.

7. Start the plugin server

Run the following command to start the plugin server.

npm start

Check the plugin server documentation to learn more.

8. Run the action (optional)

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

Use the following command to run the action from the plugin server. You should receive a response with the result of the action execution. The plugin server must be running to run 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"
  }
}'

Command explanation

In this example, we use the plugin server URL, http://localhost:4201, along with the sample action name, sampleAction, which was generated during initialization.

The action expects input parameters number1 and number2. Additionally, we use the default API Key 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

Make sure you delete all the secrets you might be using during testing before pushing the changes to the repository.