@cc-ts/builder

A powerful bundler and build tool for ComputerCraft TypeScript projects. The builder helps you compile, bundle, and serve TypeScript code for ComputerCraft computers.

Note: The builder requires Bun to run.

Features

• 🎯 TypeScript to Lua compilation optimized for ComputerCraft
• 📦 Smart bundling with dependency resolution
• 🔍 Source map support for better debugging
• 🔎 Dependency analysis and explain reports
• 🚀 Development server for quick testing
• ⚡ Watch mode for rapid development
• 📑 Minimal Lua library generation per entrypoint
• 🗜️ Optional minification

Getting Started

The easiest way to get started with CC-TS is to use our project creation tool:

bun create cc-ts my-project
# or
npm create cc-ts@latest my-project
Copy

This will guide you through creating a new project with two options:

• Bundled App: A complete application that uses @cc-ts/builder for bundling and development
• CC Library: A library project that can be published and used by other CC-TS projects

The creation tool will set up your project with the correct dependencies and configuration files.

For more information about creating new projects, check out the create-cc-ts package.

Installation

bun add -D @cc-ts/builder
# or
npm install --save-dev @cc-ts/builder
Copy

Usage

CLI

The builder can be used via its CLI command cc-ts:

cc-ts [options] [files...]
Copy

Configuration

Configure your project by adding a cc-ts section to your tsconfig.json:

{
    "compilerOptions": {
        // ... your TypeScript options
    },
    "tstl": {
        "luaTarget": "CC-5.2",
        "luaLibImport": "require-minimal",
        "buildMode": "default"
    },
    "cc-ts": {
        "minify": false,
        "analyze": false,
        "builtInModules": [],
        "externals": [],
        "reproducible": false,
        "serve": false,
        "servePort": 8080
    }
}
Copy

CLI Options

• -p, --project <path> - Path to tsconfig.json
• --minify - Minify the output Lua code
• --analyze - Print a dependency analysis report after the build
• --analyzeFormat <text|json> - Choose analysis output format
• --analyzeOutput <path> - Write analysis output to a file
• --serve - Start a development server
• --servePort <number> - Specify development server port (default: 8080)
• --watch - Watch mode for development
• --debug - Enable debug logging
• --explain <a,b,c> - Explain specific modules in the analysis output
• --externals <json> - Configure external module rules
• --reproducible - Remove volatile build metadata from bundle headers
• -h, --help - Show help information
• -v, --version - Show version information

Development Server

The builder includes a development server for testing your code. Enable it with:

cc-ts --serve
Copy

This will start a server (default port 8080) that serves your compiled Lua files.

Watch Mode

For development, you can use watch mode to automatically recompile on changes:

cc-ts --watch
Copy

Combine with serve for a complete development setup:

cc-ts --watch --serve
Copy

Package Scripts

Add these convenient scripts to your package.json:

{
    "scripts": {
        "build": "cc-ts",
        "dev": "cc-ts --watch --serve",
        "watch": "cc-ts --watch"
    }
}
Copy

Advanced Features

Built-in Modules

Specify built-in modules that should not be resolved and bundled:

{
    "cc-ts": {
        "builtInModules": ["fs", "http"]
    }
}
Copy

This is useful when a module is provided by ComputerCraft or by your own runtime environment.

Ignoring Files as Entry Points

Specify which files should be ignored as entry points using glob patterns:

{
    "cc-ts": {
        "ignoreAsEntryPoint": ["**/*.lib.ts", "src/utils/**"]
    }
}
Copy

Files matching these patterns will still be included when imported by other modules, but won't be built as standalone entry points. This is useful for utility libraries, shared code, and similar files.

Dependency Analysis

Ask the builder to explain what happened to each dependency:

cc-ts --analyze
cc-ts --analyze --analyzeFormat json --analyzeOutput dist/build-analysis.json
cc-ts --analyze --explain fs,my-library.runtime
Copy

This is useful when you want to answer questions like:

• why was a module bundled?
• why was it left external?
• which runtime files were copied into dist/?

External Runtime Rules

externals rules let you explicitly classify runtime dependencies:

{
    "cc-ts": {
        "externals": [
            {
                "pattern": "fs",
                "mode": "builtin",
                "reason": "Provided by the ComputerCraft runtime"
            },
            {
                "pattern": "my-vendor-lib",
                "mode": "external",
                "reason": "Installed separately on the target computer"
            },
            {
                "pattern": "my-lua-lib",
                "mode": "copy",
                "outDir": "vendor",
                "reason": "Ship the runtime Lua alongside the bundle"
            }
        ]
    }
}
Copy

Rule modes:

• builtin: treat the module like a provided runtime dependency.
• external: leave the module unresolved at bundle time and expect it at runtime.
• copy: emit the runtime Lua file into the build output and extend package.path to find it.

External Code Guidance

The builder works best with these dependency shapes:

• local TypeScript or JSON files in your project
• TSTL-compatible packages that publish compilable source
• Lua runtime packages that also ship .d.ts declarations
• vendored runtime Lua that you mark as external or copy

Packages that only publish JavaScript are usually not directly usable from ComputerCraft builds. When possible, prefer:

• a .lua + .d.ts package
• vendored TypeScript source
• a TSTL-compatible package
• a custom adapter layer instead of importing a Node-oriented package directly

Minification

Enable minification for production builds:

{
    "cc-ts": {
        "minify": true
    }
}
Copy

minify currently cannot be combined with sourceMap or sourceMapTraceback in the builder. If you need runtime traceback fidelity, keep minification disabled.

Reproducible Bundles

Enable reproducible to remove timestamp noise from generated headers:

{
    "cc-ts": {
        "reproducible": true
    }
}
Copy

Created and maintained by Jakob Helgesson.