Runtime SDK and types for Acode plugin development. Part of the Axpo ecosystem.

Installation

npm install @axpo/sdk

Quick Start

import { useContext, useSettings } from 'axpo/sdk';

export default function myPlugin() {
  return {
    async init() {
      const { baseUrl, page, pluginId, firstInit } = useContext();
      const settings = useSettings<MySettings>();

      console.log(settings.get('theme'));

      if (firstInit) {
        console.log('First run!');
      }
    },

    async destroy() {
      // cleanup
    },

    settings: [
      {
        key: 'theme',
        text: 'Color Theme',
        type: 'select',
        defaultValue: 'dark',
        options: [['light', 'Light'], ['dark', 'Dark']],
        onChange(value) { applyTheme(value); }
      },
      {
        key: 'fontSize',
        text: 'Font Size',
        type: 'number',
        defaultValue: 14,
        info: 'Size in pixels'
      },
      {
        key: 'enabled',
        text: 'Enable Plugin',
        type: 'checkbox',
        defaultValue: true
      }
    ]
  };
}

Hooks

useContext()

Access the plugin runtime context. Must be called inside init() or destroy() only.

| Property | Type | Description | |----------|------|-------------| | baseUrl | string | Plugin base URL (with trailing slash) | | page | WCPage | Page/UI manager | | pluginId | string | Unique plugin ID | | firstInit | boolean | First time running? | | cacheFile | File | Cache file object | | cacheFileUrl | string | Cache file URL |

useSettings<T>()

Type-safe settings manager. Pass your settings interface as a generic to get full IntelliSense.

| Method | Description | |--------|-------------| | get(key) | Get a single setting value | | getAll() | Get all settings as an object | | set(key, value) | Update a value (triggers onChange) |

Settings

Settings are automatically rendered in Acode's settings UI.

| Type | UI | Value type | |------|----|------------| | checkbox | Toggle | boolean | | text | Text input | string | | number | Number input | number | | select | Dropdown | string |

| Property | Required | Description | |----------|----------|-------------| | key | ✅ | Unique identifier | | text | ✅ | Display label | | type | ✅ | checkbox | text | number | select | | defaultValue | ✅ | Initial value | | info | — | Help text shown below the setting | | icon | — | Icon name | | iconColor | — | Icon color (hex or rgba) | | options | — | For select: [value, label] pairs or plain values | | placeholder | — | For text / number inputs | | required | — | Marks field as required | | match | — | RegExp validation | | test | — | Custom validation (value) => boolean | | onChange | — | Called when value changes (value) => void |

All setting options:

{
  key: string           // required — unique key
  text: string          // required — display label
  type: SettingType     // required — checkbox | text | number | select
  defaultValue: any     // required — default value
  info?: string         // help text
  icon?: string         // icon name
  iconColor?: string    // hex or rgba
  options?: Array<[string, string] | string>  // for select type
  placeholder?: string  // input placeholder
  required?: boolean    
  match?: RegExp        // validation pattern
  test?: (value) => boolean  // custom validation
  onChange?: (value) => void // on change handler
}

Project Structure

After initialization, your project will have this structure:

my-plugin/
├── src/
│   └── main.ts          # Plugin entry point
├── plugin.json          # Plugin manifest
├── axpo.config.ts       # Build configuration
├── tsconfig.json        # TypeScript config
├── package.json
├── readme.md
├── icon.png             # Plugin icon (max 50KB)
└── .gitignore

Configuration

// axpo.config.ts
import { defineConfig } from '@axpo/sdk';

export default defineConfig({
  buildOptions: {
    entryPoints: ['src/main.ts'],
    bundle: true,
    minify: false,
    target: 'es2020',
    alias: { '@': './src' }
  },
  files: ['readme.md', 'icon.png'],
  zipFilename: 'MyPlugin.zip',
  dev: { port: 3000 }
});

plugin.json

{
  "id": "com.example.plugin",
  "name": "Example Plugin",
  "main": "dist/main.js",
  "version": "1.0.0",
  "readme": "readme.md",
  "icon": "icon.png",
  "files": ["worker.js"],
  "minVersionCode": 292,
  "price": 0,
  "license": "MIT",
  "keywords": ["foo","bar"],
  "changelogs": "changelogs.md",
  "author": {
    "name": "Example Author",
    "email": "[email protected]",
    "url": "https://example.com",
    "github": "example"
  }
}

Links

• CLI: @axpo/cli
• GitHub: github.com/MatrixCoder0101/axpo
• Acode Docs: docs.acode.app