Create an Acode Plugin

Plugins are written in JavaScript (or TypeScript) and run inside Acode. This page takes you from an empty folder to a plugin installed on your device and, when you are ready, published.

New to plugins?

Read Understanding Plugins after this page. It explains how Acode loads and runs your code.

Plugin structure

A plugin is a zip file with these files at its root:

File	Required	Purpose
plugin.json	Yes	The manifest: id, name, version and more.
main.js	Yes	The core file with your plugin code. Its name and location are set by main in the manifest.
readme.md	Recommended	Description shown in the plugin store.
icon.png	Recommended	Icon shown in the plugin store (50 KB or smaller).
changelogs.md	No	Release notes. Also list it in files in the manifest.

Templates

Start from one of the official templates. Both come preconfigured with a bundler and build script that creates the zip for you.

Template	Use it when
JavaScript template official	You want the simplest setup.
TypeScript template official	You want type checking and editor autocomplete for the Acode API.

You can also start from scratch or use a different bundler. The only hard requirement is a zip with plugin.json at its root and the file named by main at the path it declares.

Set up the project

1. Clone a template

git clone https://github.com/Acode-Foundation/acode-plugin.git my-plugin
cd my-plugin

Replace the URL with the TypeScript template if you prefer it.

2. Edit plugin.json

Set at least a unique id, a name and a version. Every field is explained in the manifest reference.

3. Install dependencies

npm

$ npm install

pnpm

$ pnpm install

yarn

$ yarn install

bun

$ bun install

4. Start the development server

npm

$ npm run dev

pnpm

$ pnpm dev

yarn

$ yarn dev

bun

$ bun run dev

The server watches your files and rebuilds the plugin zip whenever you save a change.

INFO

The server only rebuilds on file changes. If you start it and change nothing, no zip is created yet.

If you prefer to build by hand, run the production build instead. It creates a smaller zip:

npm

$ npm run build

pnpm

$ pnpm build

yarn

$ yarn build

bun

$ bun run build

5. Install the plugin in Acode

Open Acode's plugin manager from either the Extensions tab in the sidebar or Settings → Plugins, then pick an install source:

• Remote: enter the URL of the zip served by your dev server, for example http://<your-ip>:3000/dist.zip. Use this while developing.
• Local: choose a zip file on your device. Use this if you built by hand.

Reload without reinstalling

Plugins installed from a URL or a local zip get a reload icon in the Extensions tab of the sidebar. After the dev server rebuilds the zip, tap reload to load the new version immediately.

Create a plugin with the CLI community

The community-maintained Acode Plugin CLI scaffolds a project from the official templates with an interactive wizard.

Install it (requires Rust):

$ cargo install acode-plugin-cli

Run it:

$ acode-plugin-cli

The wizard asks for the plugin name, id, version and description, author details, license and keywords, and whether to use the JavaScript or TypeScript template. When it finishes, the project is ready to use.

Build and publish

1. Create a production build. It is smaller than the development build.

   npm

   $ npm run build

   pnpm

   $ pnpm build

   yarn

   $ yarn build

   bun

   $ bun run build

2. Upload the zip to acode.app to publish it in the plugin store. Watch the publishing walkthrough if you have not done it before.

To release an update, increase version in plugin.json, build again and upload the new zip. See Publishing updates.

Publish automatically

Use an API key to publish each release from GitHub Actions or another CI. See Publish from CI.

Video tutorial

How to create Acode plugins

Next steps

• Understanding Plugins: the lifecycle of a plugin
• Core File: what main.js must contain
• Acode API: the API your plugin talks to