Build System & Bundling
Relevant source files
The following files were used as context for generating this wiki page:
The Recoup CLI build system is designed to transform a TypeScript-based source repository into a production-ready, executable Command Line Interface. The architecture focuses on high-speed compilation, compatibility with Node.js environments (specifically version 22+), and reliable distribution via npm.
The system utilizes tsup as the primary bundler to generate CommonJS (CJS) distributions, ensuring compatibility for global installations within various environments like sandboxes.
Sources: CLAUDE.md:8-9, tsup.config.ts:1-11, package.json:1-15
Build Pipeline Architecture
The build pipeline moves from TypeScript source files located in the src/ directory to a single executable entry point in the dist/ directory.
This diagram illustrates the transformation from source code to the final binary executable.
Sources: tsup.config.ts:4-11, tsconfig.json:11-12, package.json:6-8
Configuration Management
TypeScript Configuration
The project uses ES2022 as the target and module system for development. The configuration ensures strict type checking and maps the source files for debugging.
| Option | Value | Description |
|---|---|---|
| target | ES2022 | Specifies the JavaScript language version for output |
| module | ES2022 | Sets the module system for the program |
| outDir | dist | Redirects output structure to this directory |
| rootDir | src | Specifies the root folder within source files |
| declaration | true | Generates corresponding .d.ts files |
Sources: tsconfig.json:2-12
Bundler Configuration (tsup)
The tsup.config.ts file defines how the application is packaged for distribution. It specifically targets Node.js 22 and cleans the output directory before every build.
export default defineConfig({
entry: ["src/bin.ts"],
format: ["cjs"],
target: "node22",
clean: true,
banner: {
js: "#!/usr/bin/env node",
},
});
Sources: tsup.config.ts:3-11
Distribution & Execution
The CLI is packaged to be used as a global command. The package.json defines the recoup command, mapping it to the bundled CommonJS file.
Key Build Scripts
| Script | Command | Purpose |
|---|---|---|
| build | tsup | Compiles and bundles the project using tsup configuration |
| test | vitest run | Executes the test suite against the codebase |
| lint | eslint . --ext .ts --fix | Performs static analysis and automatic formatting fixes |
| format | prettier --write "src/**/*.ts" | Standardizes code style across the source directory |
Sources: package.json:13-18
Executable Generation
To ensure the script runs as a standalone CLI tool, a "shebang" (#!/usr/bin/env node) is injected into the top of the generated dist/bin.cjs file via the banner property in the tsup configuration. This allows the system to identify the appropriate interpreter (Node.js) when the recoup command is invoked.
Sources: tsup.config.ts:8-10, package.json:6-8
Verification and Testing
The build system's integrity is verified through automated tests that check version reporting and command execution.
This sequence shows how the build output is validated against the project configuration.
Sources: tests/bin.test.ts:6-20
The build system effectively bridges the gap between modern TypeScript development and stable CLI distribution, utilizing specialized tooling to handle environment-specific requirements like CommonJS compatibility and Node.js version targeting.