A lightweight toolkit for managing persistent Turborepo pipelines in monorepos. Turbo Stoplight acts as a "stoplight" indicator for build processes, helping you optimize CI workflows by detecting cached builds and controlling when builds should proceed.
Turbo Stoplight consists of two main packages that work together:
- @turbo-stoplight/server: A CLI tool that starts a temporary TCP server when a Turbo task is not cached, acting as a stoplight for your build process
- @turbo-stoplight/vite-plugin: A Vite plugin that notifies the server when builds complete, allowing you to chain build processes efficiently
- 🚀 CI-Optimized: Skip unnecessary builds when Turborepo cache hits
- 🔌 Easy Integration: Simple Vite plugin and CLI server
- 📦 Monorepo-Friendly: Built specifically for Turborepo workflows
- 🎯 Persistent Pipelines: Keep builds running until notified of completion
- 🔧 Package Manager Agnostic: Works with npm, yarn, and pnpm
# Install both packages as dev dependencies
pnpm add -D @turbo-stoplight/server @turbo-stoplight/vite-plugin- Configure your Vite project to use the plugin:
// vite.config.ts
import { defineConfig } from 'vite';
import { turboStoplight } from '@turbo-stoplight/vite-plugin';
export default defineConfig({
plugins: [
turboStoplight({ port: 4000 })
]
});- Start the server in your pipeline:
npx turbo-stoplight-server --task_id build --port 4000The server will:
- Check if the specified Turbo task is cached
- Exit immediately if cached (cache HIT)
- Stay running if not cached (cache MISS), waiting for build completion notification
- Exit when it receives a notification from the Vite plugin
| Package | Version | Description |
|---|---|---|
| @turbo-stoplight/server |  |
CLI server for managing persistent pipelines |
| @turbo-stoplight/vite-plugin |  |
Vite plugin for notifying build completion |
- Node.js 16+
- Turborepo 2.4.4 or later
- Vite (for the plugin)
This repository includes a sandbox example demonstrating the integration in a React + TypeScript + Vite application.
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit) and follow the commit message prompt - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Alexandre Stapenhorst (@alexandreh92)