@vertesia/plugin

CLI tool to create Vertesia plugins:

• UI Plugins
• Tool Server Plugins.

Usage

# Using pnpm create (recommended)
pnpm create @vertesia/plugin my-project

# Using npm create
npm create @vertesia/plugin my-project

# Using pnpm dlx (runs without installing)
pnpm dlx @vertesia/plugin my-project

# Using npx
npx @vertesia/plugin my-project

# Or install globally
pnpm install -g @vertesia/plugin
create-tool-server my-project

Note: When using pnpm create or npm create, drop the create- prefix from the package name.

Features

• 📦 Downloads template from GitHub - Always get the latest template
• ⚙️ Template-driven configuration - Template defines its own prompts via template.config.json
• 🎨 Interactive prompts - User-friendly CLI with validation
• 🔄 Variable replacement - Automatically replaces {{VARIABLES}} in files
• 🧹 Smart cleanup - Removes meta files after installation
• 📚 Package manager agnostic - Works with npm, pnpm, or yarn

How It Works

1. Downloads the template repository from GitHub using degit
2. Reads template.config.json from the template to determine configuration
3. Prompts the user for values (project name, description, etc.)
4. Replaces variables in specified files (e.g., {{PROJECT_NAME}} → my-project)
5. Cleans up meta files (.git, template.config.json, etc.)
6. Installs dependencies using the configured package manager

Configuration

All configuration is centralized in src/configuration.ts:

export const config = {
  templateRepo: 'vertesiahq/plugin-template',
  templateConfigFile: 'template.config.json',
  packageManager: 'pnpm',
  // ... more options
}

Key Configuration Options

• templateRepo - GitHub repository for the template (format: owner/repo)
• templateConfigFile - Name of the config file in the template
• packageManager - Which package manager to use (npm, pnpm, or yarn)
• useCache - Whether to cache downloaded templates

Template Structure

The template repository should include a template.config.json file:

{
  "version": "1.0",
  "prompts": [
    {
      "type": "text",
      "name": "PROJECT_NAME",
      "message": "Project name",
      "initial": "my-tool-server"
    },
    {
      "type": "text",
      "name": "DESCRIPTION",
      "message": "Project description",
      "initial": "A tool server for LLM integrations"
    }
  ],
  "files": [
    "package.json",
    "README.md",
    "src/server.ts"
  ],
  "removeAfterInstall": [
    ".git",
    "template.config.json"
  ]
}

Template Config Schema

• prompts - Array of prompts using the prompts library format
• files - List of files where variable replacement should occur
• removeAfterInstall - Files/directories to remove after installation
• conditionalRemove - Conditional file removal based on user answers

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Test locally
pnpm test

# Watch mode
pnpm dev

Publishing

# Build and publish
npm publish

After publishing, users can create projects with:

pnpm create @vertesia/plugin my-project

Template Development

To develop a template:

1. Create a GitHub repository with your template files
2. Add a template.config.json file with prompts and configuration
3. Use {{VARIABLES}} in files where you want replacements
4. Update src/configuration.ts to point to your template repo
5. Test with pnpm test or run the built CLI directly

Examples

Create a project with default settings

pnpm create @vertesia/plugin my-project

View help

pnpm dlx @vertesia/plugin --help

License

MIT