Developer Tooling
Relevant source files
The following files were used as context for generating this wiki page:The Kodus Runtime project is a monorepo containing multiple applications and shared packages written in Rust, Node.js (TypeScript), and React. The developer tooling is designed to manage this complexity, providing a unified workflow for building, testing, and running the entire system or its individual components. The tooling leverages yarn as the package manager, Turbo for monorepo task orchestration, Cargo for the Rust ecosystem, and Docker for containerization.
This combination of tools ensures code quality, consistency, and efficient development cycles across the different technology stacks. Custom scripts are provided to simplify common tasks like local development, building for production, and managing containerized environments.
Sources: package.json, README.md:33-43
Monorepo Management
The project uses a combination of yarn workspaces and Turbo to manage the monorepo structure and dependencies. Turbo is the high-performance build system that orchestrates tasks across the different applications and packages.
Sources: package.json:6, README.md:33-43
Task Orchestration with Turbo
Turbo is configured to understand the dependency graph between packages and applications, allowing it to run tasks like build, lint, and test in the correct order and cache the results. The root package.json contains scripts that invoke turbo.
The following diagram illustrates the task dependency flow for a command like yarn build.
This diagram shows that shared packages like @kodus/types and @kodus/config are built before the applications (@kodus/api, @kodus/dashboard) that depend on them.
Sources: package.json:8, apps/api/package.json:16-18, apps/dashboard/package.json:19-22
Local Development Workflow
The project provides a set of yarn scripts to streamline local development. These scripts handle everything from installing dependencies to running development servers with hot-reloading.
Common Scripts
The main scripts for developers are defined in the root package.json.
| Script | Description |
|---|---|
dev | Runs all applications (API and Dashboard) in development mode using turbo. |
dev:api | Runs only the Node.js API server in development mode with hot-reloading. |
dev:dashboard | Runs only the React Dashboard in development mode. |
dev:all | Runs both the API and Dashboard concurrently. |
build | Builds all Node.js/TypeScript packages and applications. |
build:services | Builds the Rust components in release mode using cargo. |
build:all | Builds both Rust and Node.js components. |
check | Runs linting, formatting checks, and type-checking across the monorepo. |
fix | Automatically fixes linting and formatting issues. |
clean | Removes node_modules, target build artifacts, and turbo cache. |
Sources: package.json:7-23, README.md:143-154
Development Flow
The typical local development flow is as follows:
This flow allows developers to get the API and Dashboard running simultaneously with a single command.
Sources: package.json:13,18, README.md:104-111
Rust Tooling
The Rust components, including the core runtime and the Node.js native addon, are managed as a cargo workspace.
Sources: Cargo.toml:2-7
Workspace Structure
The Cargo.toml at the root of the project defines the members of the Rust workspace.
This diagram shows the crates that are part of the cargo workspace.
Sources: Cargo.toml:2-7
Build and Test Commands
Standard cargo commands are used for managing the Rust parts of the project.
| Command | Description |
|---|---|
cargo build --release | Compiles the Rust services for production. This is also triggered by yarn build:services. |
cargo test | Runs all unit and integration tests for the Rust crates. |
cargo bench | Executes benchmarks defined within the Rust crates. |
cargo tarpaulin | Generates a test coverage report. |
Sources: README.md:107, 214-220, package.json:14
Native Addon for Node.js
A key part of the Rust tooling is the ts-addon crate, which exposes the core Rust runtime functionality to Node.js via a N-API native addon. This allows the Node.js API to directly call high-performance Rust code. The kodus-addon package is built as a cdylib to produce a .node file that can be required in JavaScript.
Sources: apps/runtime/crates/ts-addon/src/lib.rs, apps/runtime/crates/ts-addon/Cargo.toml:7
Containerization with Docker
The project includes a comprehensive Docker setup managed via docker-compose to simplify deployment and provide a consistent environment. Scripts in the root package.json act as convenient wrappers around docker-compose commands.
Docker Scripts
| Script | Description |
|---|---|
docker:up | Starts all services (API, Dashboard, Rust runtime) in production mode using pre-built images. |
docker:dev | Starts all services in development mode with hot-reloading for the API and Dashboard. |
docker:down | Stops and removes all running containers. |
docker:build | Builds the Docker images for all services. |
docker:logs | Tails the logs from all running containers. |
docker:status | Shows the status of the containers. |
docker:clean | Stops and removes all containers, volumes, and orphaned images. |
Sources: package.json:24-30, README.md:129-141
Docker Services
The docker-compose.yml file defines the services that make up the application stack.
This diagram shows the services managed by Docker Compose and how they interact. The Dashboard and API are exposed to the host machine, while the Rust runtime communicates with the API and persists data to a Docker volume.
Sources: README.md:88-94
Shared Configurations
To maintain code consistency and quality across the monorepo, several shared configuration packages are used. These packages are located in the packages/ directory.
@kodus/eslint-config: Provides a shared ESLint configuration for all TypeScript projects.@kodus/prettier-config: A shared Prettier configuration to enforce a consistent code style.@kodus/config: Contains shared utilities, such as a structured logger, for Node.js applications.@kodus/types: Defines shared TypeScript types and interfaces used by both the API and the Dashboard.
These packages are consumed as dependencies by the applications in the apps/ directory, ensuring that all parts of the project adhere to the same standards.
Sources: packages/eslint-config/package.json, packages/prettier-config/package.json, packages/config/package.json, packages/types/package.json
Summary
The developer tooling for Kodus Runtime is a well-integrated system that addresses the challenges of a polyglot monorepo. Turbo and yarn provide a robust foundation for managing Node.js/TypeScript projects, while cargo handles the Rust ecosystem. The inclusion of Docker and a suite of helper scripts simplifies both local development and deployment, creating a productive and consistent environment for all developers working on the project.
Sources: package.json, README.md, Cargo.toml