kist
Version:
Lightweight Package Pipeline Processor with Plugin Architecture
284 lines (212 loc) • 8.33 kB
Markdown
<p align="center">
<img src="https://raw.githubusercontent.com/getkist/brand/master/src/logo/kist.png" width="20%" alt="kist logo"></p>
<h1 align="center" style='border-bottom: none;'>kist</h1>
<h3 align="center">Lightweight Package Pipeline Processor</h3>
<br/>
<div align="center">
[](https://www.getkist.com)
[](https://www.npmjs.com/package/kist)
[](https://github.com/getkist/kist/blob/main/LICENSE)
</div>
<div align="center">
[](https://github.com/getkist/kist/issues/new?template=bug_report.yml)
[](https://github.com/getkist/kist/issues/new?template=feature_request.yml)
[](https://github.com/getkist/kist/discussions)
</div>
**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
```bash
npm install kist --save-dev
```
### Create Configuration
Create a `kist.yml` file in your project root:
```yaml
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"
```
### Run Pipeline
```bash
npx kist
# or with a specific config
npx kist --config kist.production.yml
```
## 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 |
| --------------------------------------------------------------------------- | ------------------------------- |
| [kist-action-sass](https://github.com/getkist/kist-action-sass) | Compile SASS/SCSS to CSS |
| [kist-action-typescript](https://github.com/getkist/kist-action-typescript) | Advanced TypeScript compilation |
| [kist-action-jinja](https://github.com/getkist/kist-action-jinja) | Process Jinja2 templates |
| [kist-action-svg](https://github.com/getkist/kist-action-svg) | Optimize and package SVGs |
| [kist-action-test](https://github.com/getkist/kist-action-test) | Run tests with Jest/Vitest |
Install plugins via npm:
```bash
npm install kist-action-sass --save-dev
```
## Configuration
### Full Example
```yaml
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"
```
### Config Inheritance
Create reusable base configurations:
```yaml
# kist.base.yml
stages:
- name: build
steps:
- name: compile
action: TypeScriptCompilerAction
options:
tsConfigPath: "./tsconfig.json"
```
```yaml
# kist.production.yml
extends: ./kist.base.yml
options:
mode: production
```
## CLI Options
```bash
kist [options]
Options:
--config, -c Path to config file (default: kist.yml)
--live, -l Enable live reload mode
--verbose, -v Enable verbose logging
--help, -h Show help
--version Show version
```
## Development
### Build from Source
```bash
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](https://www.getkist.com)**
- [Getting Started](https://www.getkist.com/guide/getting-started)
- [Configuration Guide](https://www.getkist.com/guide/configuration)
- [Core Actions](https://www.getkist.com/guide/core-actions)
- [Plugin Development](https://www.getkist.com/guide/plugin-development)
- [API Reference](https://www.getkist.com/api/)
## Contributing
Contributions are welcome! See [CONTRIBUTING.md](.github/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](LICENSE) for details.
Copyright © 2024-2026 [Scape Agency](https://www.scape.agency)
<p align="center">
<b>Made with ❤️ by <a href="https://www.scape.agency" target="_blank">Scape Agency</a></b>
</p>