Using Plugins

Learn how to discover, install, and configure kist plugins.

Installing Plugins

From npm

Most kist plugins are published to npm with the @getkist/ scope:

# Install a single plugin
npm install --save-dev @getkist/action-sass

# Install multiple plugins at once
npm install --save-dev @getkist/action-sass @getkist/action-typescript @getkist/action-eslint

From Source

You can also reference local plugins:

plugins:
  # npm package
  - @getkist/action-sass
  
  # Local plugin (relative path)
  - ./my-plugins/custom-action

Registering Plugins

Declare plugins in your kist.yml:

plugins:
  - @getkist/action-sass
  - @getkist/action-typescript
  - @getkist/action-eslint

pipeline:
  # Your pipeline uses actions from these plugins

Plugins are loaded in order. If two plugins provide the same action name, the later plugin wins.

Default Actions

Some actions are built into kist and don't require plugins:

Action	Description
CopyAction	Copy files
DeleteAction	Delete files
LogAction	Log messages
ShellAction	Run shell commands

Plugin Options

Each plugin's actions accept specific options. See individual plugin docs for details.

Common Patterns

Most plugins follow these conventions:

# File-based actions
- action: SomeAction
  options:
    inputFile: src/input.ext      # Single input file
    outputFile: dist/output.ext   # Single output file

# Directory-based actions
- action: SomeAction
  options:
    inputDir: src/                # Input directory
    outputDir: dist/              # Output directory
    pattern: "**/*.ext"           # Glob pattern

# Multi-file actions
- action: SomeAction
  options:
    files:                        # Array of files
      - src/file1.ext
      - src/file2.ext
    outDir: dist/

Environment Variables

Use environment variables with the ${{ env.VAR }} syntax:

- action: TypeScriptCompilerAction
  options:
    tsconfig: ${{ env.TSCONFIG_PATH }}

Plugin Discovery

Finding Plugins

1. Official plugins: Check the Plugins List
2. npm search: Search for @getkist/action- packages
3. GitHub: Search for kist-plugin-* repositories

Verifying Compatibility

Check the plugin's package.json for peer dependencies:

{
  "peerDependencies": {
    "@getkist/kist": "^0.1.0"
  }
}

Troubleshooting

Plugin Not Found

Error: Plugin '@getkist/action-example' not found

Solutions:

1. Verify the plugin is installed: npm ls @getkist/action-example
2. Check the package name is correct
3. Run npm install to ensure dependencies are installed

Action Not Found

Error: Action 'SomeAction' not found

Solutions:

1. Check the plugin is listed in kist.yml plugins section
2. Verify the action name (case-sensitive)
3. Check the plugin documentation for correct action names

Version Conflicts

If you see peer dependency warnings:

# Check kist version
npx kist --version

# Update plugins to compatible versions
npm update @getkist/action-sass

Best Practices

Organize Large Projects

# For large projects, group related stages
plugins:
  - @getkist/action-sass
  - @getkist/action-postcss
  - @getkist/action-typescript
  - @getkist/action-terser
  - @getkist/action-eslint
  - @getkist/action-prettier
  - @getkist/action-jest

pipeline:
  build:
    stages:
      # Lint stage runs first
      - name: lint
        steps:
          - action: LintAction
          - action: PrettierAction
            options:
              check: true
              
      # Build stages
      - name: styles
        steps:
          - action: StyleProcessingAction
          - action: PostCssAction
          
      - name: scripts
        steps:
          - action: TypeScriptCompilerAction
          - action: JavaScriptMinifyAction
          
      # Test stage runs last
      - name: test
        steps:
          - action: JestAction

Watch Mode

Use the --watch flag for development:

npx kist run build --watch

Many plugins support incremental builds in watch mode.

CI/CD Integration

# .github/workflows/build.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx kist run build

Next Steps

• Plugin Development - Create your own plugin
• Configuration Reference - Full YAML reference
• Browse Individual Plugins for specific documentation