ElizaOS Plugin

This is an ElizaOS plugin built with the official plugin starter template.

Development

# Install deps with bun
bun install

# Start development with hot-reloading
npm run dev

# Build the plugin
npm run build

# Test the plugin
npm run test

Testing

ElizaOS provides a comprehensive testing structure for plugins:

Test Structure

• Component Tests (__tests__/ directory):

  • Unit Tests: Test individual functions/classes in isolation
  • Integration Tests: Test how components work together
  • Run with: npm run test:component

• End-to-End Tests (e2e/ directory):

  • Test the plugin within a full ElizaOS runtime
  • Run with: npm run test:e2e

• Running All Tests:

  • npm run test runs both component and e2e tests

Writing Tests

Component tests use Vitest:

// Unit test example (__tests__/plugin.test.ts)
describe('Plugin Configuration', () => {
  it('should have correct plugin metadata', () => {
    expect(starterPlugin.name).toBe('plugin-nuggets');
  });
});

// Integration test example (__tests__/integration.test.ts)
describe('Integration: HelloWorld Action with StarterService', () => {
  it('should handle HelloWorld action with StarterService', async () => {
    // Test interactions between components
  });
});

E2E tests use ElizaOS test interface:

// E2E test example (e2e/starter-plugin.test.ts)
export class StarterPluginTestSuite implements TestSuite {
  name = 'plugin_starter_test_suite';
  tests = [
    {
      name: 'example_test',
      fn: async (runtime) => {
        // Test plugin in a real runtime
      },
    },
  ];
}

export default new StarterPluginTestSuite();

The test utilities in __tests__/test-utils.ts provide mock objects and setup functions to simplify writing tests.

Publishing & Continuous Development

Initial Setup

Before publishing your plugin, ensure you meet these requirements:

1. npm Authentication

   npm login

2. GitHub Repository

   • Create a public GitHub repository for this plugin
   • Add the 'elizaos-plugins' topic to the repository
   • Use 'main' as the default branch

3. Required Assets

   • Add images to the images/ directory:
     • logo.jpg (400x400px square, <500KB)
     • banner.jpg (1280x640px, <1MB)

Initial Publishing

# Test your plugin meets all requirements
elizaos publish --test

# Publish to npm + GitHub + registry (recommended)
elizaos publish

This command will:

• Publish your plugin to npm for easy installation
• Create/update your GitHub repository
• Submit your plugin to the ElizaOS registry for discoverability

Continuous Development & Updates

Important: After your initial publish with elizaos publish, all future updates should be done using standard npm and git workflows, not the ElizaOS CLI.

Standard Update Workflow

1. Make Changes

   # Edit your plugin code
   npm run dev  # Test locally with hot-reload

2. Test Your Changes

   # Run all tests
   elizaos test
   
   # Run specific test types if needed
   elizaos test component  # Component tests only
   elizaos test e2e       # E2E tests only

3. Update Version

   # Patch version (bug fixes): 1.0.0 → 1.0.1
   npm version patch
   
   # Minor version (new features): 1.0.1 → 1.1.0
   npm version minor
   
   # Major version (breaking changes): 1.1.0 → 2.0.0
   npm version major

4. Publish to npm

   npm publish

5. Push to GitHub

   git push origin main
   git push --tags  # Push version tags

Why Use Standard Workflows?

• npm publish: Directly updates your package on npm registry
• git push: Updates your GitHub repository with latest code
• Automatic registry updates: The ElizaOS registry automatically syncs with npm, so no manual registry updates needed
• Standard tooling: Uses familiar npm/git commands that work with all development tools

Alternative Publishing Options (Initial Only)

# Publish to npm only (skip GitHub and registry)
elizaos publish --npm

# Publish but skip registry submission
elizaos publish --skip-registry

# Generate registry files locally without publishing
elizaos publish --dry-run

Configuration

The agentConfig section in package.json defines the parameters your plugin requires:

"agentConfig": {
  "pluginType": "elizaos:plugin:1.0.0",
  "pluginParameters": {
    "API_KEY": {
      "type": "string",
      "description": "API key for the service"
    }
  }
}

Customize this section to match your plugin's requirements.

Documentation

Provide clear documentation about:

• What your plugin does
• How to use it
• Required API keys or credentials
• Example usage
• Version history and changelog