kist

Lightweight Package Pipeline Processor

---

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.

---

Features

• 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

---

Quick Start

Installation

npm install kist --save-dev

Create Configuration

Create a kist.yml file in your project root:

stages:
- name: buildsteps:
- name: cleanaction: DirectoryCleanActionoptions:
dirPath: "./dist"
- name: copy-filesaction: FileCopyActionoptions:
srcFile: "./README.md"destDir: "./dist"
- name: compileaction: TypeScriptCompilerActionoptions:
tsConfigPath: "./tsconfig.json"outputDir: "./dist/js"

Run Pipeline

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

---

Core Actions

kist includes these built-in actions:

Action	Description
DirectoryCleanAction	Remove directory contents
DirectoryCopyAction	Copy directories recursively
DirectoryCreateAction	Create directories
FileCopyAction	Copy individual files
FileRenameAction	Rename or move files
TypeScriptCompilerAction	Compile TypeScript
PackageManagerAction	Generate package.json
VersionWriteAction	Update version in files
RunScriptAction	Execute npm scripts
DocumentationAction	Generate documentation

---

Official Plugins

Extend kist with official action plugins:

Plugin	Description
@getkist/action-sass	Compile SASS/SCSS to CSS
@getkist/action-typescript	Advanced TypeScript compilation
@getkist/action-nunjucks	Render Nunjucks templates
@getkist/action-svg	Optimize and package SVGs
@getkist/action-postcss	Process CSS with PostCSS
@getkist/action-terser	Minify JavaScript
@getkist/action-eslint	Lint with ESLint
@getkist/action-prettier	Format with Prettier
@getkist/action-jest	Run tests with Jest

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

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

---

Configuration

Full Example

options:
mode: developmentlogLevel: debuglive:
enabled: trueport: 3000watchPaths:
- src/**cache:
enabled: truecacheDir: ".kist-cache"performance:
parallelProcessing: truemaxConcurrentStages: 4stages:
- name: Preprocessingparallel: falsesteps:
- name: Cleanaction: DirectoryCleanActionoptions:
dirPath: "./dist"
- name: CopyAssetsaction: DirectoryCopyActionoptions:
srcDir: "./src/assets"destDir: "./dist/assets"
- name: Compileparallel: truesteps:
- name: CompileTSaction: TypeScriptCompilerActionoptions:
tsConfigPath: "./tsconfig.json"outputDir: "./dist/js"
- name: CompileSASSaction: StyleProcessingActionoptions:
inputFile: "./src/scss/main.scss"outputFile: "./dist/css/main.css"

Config Inheritance

Create reusable base configurations:

# kist.base.ymlstages:
- name: buildsteps:
- name: compileaction: TypeScriptCompilerActionoptions:
tsConfigPath: "./tsconfig.json"

# kist.production.ymlextends: ./kist.base.ymloptions:
mode: production

---

CLI

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 helpfor 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.

---

Editor Support

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.

---

Caching

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: truestages:
- name: buildsteps:
- name: compileaction: TypeScriptCompilerActioninputs:
- "src/**/*.ts"
- "tsconfig.json"outputs:
- "dist/**"env:
- NODE_ENVoptions:
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.

---

Development

Build from Source

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

Project Structure

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

---

Documentation

Full documentation available at getkist.com

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

---

Contributing

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

---

License

MIT License - see LICENSE for details.

Copyright © 2024-2026 Scape Press

---

Made with ❤️ by Scape Press