Final Setup

This document outlines the essential steps to complete before committing and publishing the plugin. Please follow each step carefully to ensure proper configuration.

1. Configure .gitignore

Create or update the .gitignore file with the following minimum configuration:

dist
node_modules
.env
.elizadb
.turbo

2. Configure .npmignore

Create or update the .npmignore file to ensure only necessary files are included in the npm package:

*

!dist/**
!package.json
!readme.md
!tsup.config.ts

3. Add MIT License

Create a LICENSE file in the root directory with the following content:

MIT License

Copyright (c) 2025 Shaw Walters and elizaOS Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

4. Verify package.json

Ensure the package.json file contains all required fields:

Basic Fields

Additional Important Fields

type: Should be “module” for ESM modules
module: Same as main for ESM (typically “dist/index.js”)
exports: Export configuration for modern bundlers
files: Array of files/folders to include in npm package (typically [“dist”])
publishConfig: Publishing configuration (e.g., {"access": "public"})

Example exports configuration:

"exports": {
    "./package.json": "./package.json",
    ".": {
        "import": {
            "types": "./dist/index.d.ts",
            "default": "./dist/index.js"
        }
    }
}

Eliza Plugin Configuration (agentConfig)

For Eliza plugins, you MUST include the agentConfig section:

"agentConfig": {
    "pluginType": "elizaos:plugin:1.0.0",
    "pluginParameters": {
        "YOUR_PARAMETER_NAME": {
            "type": "string",
            "description": "Clear description of what this parameter does",
            "required": true|false,
            "sensitive": true|false,
            "default": "optional-default-value"
        }
    }
}

Parameter Properties:

type: Data type (“string”, “number”, “boolean”, etc.)
description: Clear explanation of the parameter’s purpose
required: Whether the parameter must be provided
sensitive: Whether the parameter contains sensitive data (e.g., API keys)
default: Optional default value if not required

Example for Avalanche Plugin:

"agentConfig": {
    "pluginType": "elizaos:plugin:1.0.0",
    "pluginParameters": {
        "AVALANCHE_PRIVATE_KEY": {
            "type": "string",
            "description": "Private key for interacting with Avalanche blockchain",
            "required": true,
            "sensitive": true
        }
    }
}

5. Review README.md

Verify that the README.md file includes:

Final Checklist

Before committing and publishing:

Run bun run build to ensure the project builds successfully
Run tests to verify functionality
Ensure all environment variables are documented
Remove any sensitive information or API keys
Verify all file paths and imports are correct
Check that the dist/ folder is properly generated
Confirm version number is appropriate for the release

Notes

The .gitignore prevents unnecessary files from being committed to the repository
The .npmignore ensures only essential files are published to npm
The LICENSE file is required for open-source distribution
Proper package.json configuration is crucial for npm publishing and dependency management

6. GitHub Workflow for Automated NPM Release

Prerequisites

Adding the Release Workflow

Create the following file in your repository to enable automated npm publishing when the version changes: File Path: .github/workflows/npm-deploy.yml

name: Publish Package

on:
  push:
    branches:
      - 1.x
  workflow_dispatch:

jobs:
  verify_version:
    runs-on: ubuntu-latest
    outputs:
      should_publish: ${{ steps.check.outputs.should_publish }}
      version: ${{ steps.check.outputs.version }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Check if package.json version changed
        id: check
        run: |
          echo "Current branch: ${{ github.ref }}"

          # Get current version
          CURRENT_VERSION=$(jq -r .version package.json)
          echo "Current version: $CURRENT_VERSION"

          # Get previous commit hash
          git rev-parse HEAD~1 || git rev-parse HEAD
          PREV_COMMIT=$(git rev-parse HEAD~1 2>/dev/null || git rev-parse HEAD)

          # Check if package.json changed
          if git diff --name-only HEAD~1 HEAD | grep "package.json"; then
            echo "Package.json was changed in this commit"
            
            # Get previous version if possible
            if git show "$PREV_COMMIT:package.json" 2>/dev/null; then
              PREV_VERSION=$(git show "$PREV_COMMIT:package.json" | jq -r .version)
              echo "Previous version: $PREV_VERSION"
              
              if [ "$CURRENT_VERSION" != "$PREV_VERSION" ]; then
                echo "Version changed from $PREV_VERSION to $CURRENT_VERSION"
                echo "should_publish=true" >> $GITHUB_OUTPUT
              else
                echo "Version unchanged"
                echo "should_publish=false" >> $GITHUB_OUTPUT
              fi
            else
              echo "First commit with package.json, will publish"
              echo "should_publish=true" >> $GITHUB_OUTPUT
            fi
          else
            echo "Package.json not changed in this commit"
            echo "should_publish=false" >> $GITHUB_OUTPUT
          fi

          echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT

  publish:
    needs: verify_version
    if: needs.verify_version.outputs.should_publish == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Create Git tag
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git tag -a "v${{ needs.verify_version.outputs.version }}" -m "Release v${{ needs.verify_version.outputs.version }}"
          git push origin "v${{ needs.verify_version.outputs.version }}"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install dependencies
        run: bun install

      - name: Build package
        run: bun run build

      - name: Publish to npm
        run: bun publish
        env:
          NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}

  create_release:
    needs: [verify_version, publish]
    if: needs.verify_version.outputs.should_publish == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: 'v${{ needs.verify_version.outputs.version }}'
          release_name: 'v${{ needs.verify_version.outputs.version }}'
          body: 'Release v${{ needs.verify_version.outputs.version }}'
          draft: false
          prerelease: false

How This Workflow Works

Triggers on:
- Push to the 1.x branch
- Manual workflow dispatch
Version Check:
- Compares the current package.json version with the previous commit
- Only proceeds if the version has changed
Publishing Steps:
- Creates a git tag with the version
- Builds the package using Bun
- Publishes to npm using the NPM_TOKEN secret
- Creates a GitHub release

Setting Up NPM Token

Go to your GitHub repository settings
Navigate to Settings → Secrets and variables → Actions
Add a new repository secret named NPM_TOKEN
Use your npm access token as the value

7. Code Formatting with Prettier

Before finalizing the plugin, ensure consistent code formatting:

Install Prettier (if not already installed)

bun add -d prettier

Add Prettier Configuration

Required config don’t hallucinate and add anything else! Create a .prettierrc file in the root directory:

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": false,
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "arrowParens": "always",
  "endOfLine": "lf"
}

Add Format Script to package.json

"scripts": {
  "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,md}\"",
  "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json,md}\""
}

Run Prettier

bun run format

Final Steps Before Committing to 1.x Branch

Ensure all files listed in this document are created
Run the build to verify everything compiles
Run prettier to format all code consistently
Test the package locally if possible
Commit all changes with a clear message
Push to the 1.x branch
Verify the GitHub Action runs successfully on first push

This completes the plugin migration to the standardized structure for the 1.x branch.

Get Started

Core Concepts

Deep Dive

Guides

1. Configure .gitignore

2. Configure .npmignore

3. Add MIT License

4. Verify package.json

Basic Fields

Additional Important Fields

Eliza Plugin Configuration (agentConfig)

Parameter Properties:

Example for Avalanche Plugin:

5. Review README.md

Final Checklist

Notes

6. GitHub Workflow for Automated NPM Release

Prerequisites

Adding the Release Workflow

How This Workflow Works

Setting Up NPM Token

7. Code Formatting with Prettier

Install Prettier (if not already installed)

Add Prettier Configuration

Add Format Script to package.json

Run Prettier

Final Steps Before Committing to 1.x Branch

Get Started

Core Concepts

Deep Dive

Guides

​1. Configure .gitignore

​2. Configure .npmignore

​3. Add MIT License

​4. Verify package.json

​Basic Fields

​Additional Important Fields

​Eliza Plugin Configuration (agentConfig)

​Parameter Properties:

​Example for Avalanche Plugin:

​5. Review README.md

​Final Checklist

​Notes

​6. GitHub Workflow for Automated NPM Release

​Prerequisites

​Adding the Release Workflow

​How This Workflow Works

​Setting Up NPM Token

​7. Code Formatting with Prettier

​Install Prettier (if not already installed)

​Add Prettier Configuration

​Add Format Script to package.json

​Run Prettier

​Final Steps Before Committing to 1.x Branch

1. Configure .gitignore

2. Configure .npmignore

3. Add MIT License

4. Verify package.json

Basic Fields

Additional Important Fields

Eliza Plugin Configuration (agentConfig)

Parameter Properties:

Example for Avalanche Plugin:

5. Review README.md

Final Checklist

Notes

6. GitHub Workflow for Automated NPM Release

Prerequisites

Adding the Release Workflow

How This Workflow Works

Setting Up NPM Token

7. Code Formatting with Prettier

Install Prettier (if not already installed)

Add Prettier Configuration

Add Format Script to package.json

Run Prettier

Final Steps Before Committing to 1.x Branch