kist is a lightweight, plugin-based package pipeline processor for modern JavaScript/TypeScript projects. It provides a modular framework for automating build workflows with support for live reload, parallel execution, and extensible actions.

• Plugin Architecture - Extend functionality with official and community plugins
• Pipeline System - Define stages and steps in YAML configuration
• Core Actions - Built-in actions for common tasks (copy, clean, compile, etc.)
• Live Reload - Watch mode with automatic rebuilds
• TypeScript - Full TypeScript support with type definitions
• Self-Hosting - kist builds itself using its own pipeline
• Caching - Smart build caching for faster rebuilds
• Parallel Execution - Run stages and steps concurrently

npm install kist --save-dev

Create a kist.yml file in your project root:

stages:
    - name: build
      steps:
          - name: clean
            action: DirectoryCleanAction
            options:
                dirPath: "./dist"

          - name: copy-files
            action: FileCopyAction
            options:
                srcFile: "./README.md"
                destDir: "./dist"

          - name: compile
            action: TypeScriptCompilerAction
            options:
                tsConfigPath: "./tsconfig.json"
                outputDir: "./dist/js"

npx kist
# or with a specific config
npx kist --config kist.production.yml
# see what it would do without doing it
npx kist --dry-run

Or let kist write the file for you:

npm create kist          # scaffold a starter chosen to fit the project
npx kist init            # the same, from an already-installed kist
npx kist init -t package # a pipeline for publishing an npm package

kist includes these built-in actions:

Extend kist with official action plugins:

Install plugins via npm (packages are published under the @getkist scope):

npm install @getkist/action-sass --save-dev

options:
    mode: development
    logLevel: debug
    live:
        enabled: true
        port: 3000
        watchPaths:
            - src/**
    cache:
        enabled: true
        cacheDir: ".kist-cache"
    performance:
        parallelProcessing: true
        maxConcurrentStages: 4

stages:
    - name: Preprocessing
      parallel: false
      steps:
          - name: Clean
            action: DirectoryCleanAction
            options:
                dirPath: "./dist"

          - name: CopyAssets
            action: DirectoryCopyAction
            options:
                srcDir: "./src/assets"
                destDir: "./dist/assets"

    - name: Compile
      parallel: true
      steps:
          - name: CompileTS
            action: TypeScriptCompilerAction
            options:
                tsConfigPath: "./tsconfig.json"
                outputDir: "./dist/js"

          - name: CompileSASS
            action: StyleProcessingAction
            options:
                inputFile: "./src/scss/main.scss"
                outputFile: "./dist/css/main.css"

Create reusable base configurations:

# kist.base.yml
stages:
    - name: build
      steps:
          - name: compile
            action: TypeScriptCompilerAction
            options:
                tsConfigPath: "./tsconfig.json"

# kist.production.yml
extends: ./kist.base.yml
options:
    mode: production

kist [options] [command]

Commands:
  run              Run the pipeline (default; you can omit it)
  init [dir]       Create a starter kist.yml
  validate         Check the config and that every action it names exists
  schema           Print the JSON Schema for kist.yml
  clear-cache      Delete cached step results

Options:
  -c, --config <path>      Config file (default: kist.yaml or kist.yml)
  -l, --log-level <level>  debug | info | warn | error
  -v, --verbose            Shorthand for --log-level debug
      --live               Serve the output and rebuild on file changes
      --no-cache           Ignore cached results and run every step
      --dry-run            Print the execution plan instead of running it
      --dry <format>       Print the plan as text or json
      --graph [format]     Print the stage dependency graph (dot or mermaid)
  -V, --version            Print the kist version
  -h, --help               Show help for any command

Inspect a pipeline before running it:

kist --dry-run          # what would run, in what order
kist --dry json         # the same plan as JSON, for CI and tooling
kist --graph mermaid    # the stage graph, ready to paste into Markdown

--dry-run fails if the configuration names an action that is not registered, so a missing plugin surfaces before the build starts rather than midway through it.

kist publishes a JSON Schema for kist.yml. With the YAML extension installed, editors give you completion, hover documentation, and inline validation with no further setup — kist init writes the reference for you:

# yaml-language-server: $schema=https://www.getkist.com/schema.json

The same schema validates the file at load time, so what your editor accepts and what kist accepts cannot drift apart. kist schema prints it, which is also the quickest way to hand it to a tool or an AI assistant.

A step that declares inputs is skipped when every file matching them is unchanged since the last run. Its recorded outputs are restored and its log output is replayed, so a cached run reads the same as a real one:

options:
    cache:
        enabled: true

stages:
    - name: build
      steps:
          - name: compile
            action: TypeScriptCompilerAction
            inputs:
                - "src/**/*.ts"
                - "tsconfig.json"
            outputs:
                - "dist/**"
            env:
                - NODE_ENV
            options:
                tsConfigPath: "./tsconfig.json"
                outputDir: "./dist"

The cache key covers the action, its options, the contents of every input file, the values of any environment variables listed in env, and the Node major version. A step that declares no inputs always runs: kist will not guess what a step reads.

Set cacheEnabled: false on a stage to opt it out, pass --no-cache to ignore the cache for one run, or run kist clear-cache to discard it.

git clone https://github.com/getkist/kist.git
cd kist
npm install
npm run build

kist uses a self-hosting build process:

1. tsc compiles TypeScript (bootstrap)
2. kist runs its own pipeline for packaging

kist/
├── src/ts/
│   ├── actions/      # Built-in action implementations
│   ├── core/         # Pipeline engine, config, plugins
│   ├── interface/    # TypeScript interfaces
│   ├── live/         # Live reload server
│   ├── cli.ts        # CLI entry point
│   └── kist.ts       # Main Kist class
├── dist/             # Compiled output
├── kist.yml          # Build configuration
└── package.json

Full documentation available at getkist.com

• Getting Started
• Configuration Guide
• Core Actions
• Plugin Development
• API Reference

Contributions are welcome! See CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch
3. Make changes and add tests
4. Submit a pull request

MIT License - see LICENSE for details.

Copyright © 2024-2026 Scape Press

Made with ❤️ by Scape Press