Simple build

A build system for JS/TS that simply builds your project. In the fastest way possible, with zero effort from you.

Installation

Global Installation (Recommended)

npm install -g @simple-software/simplebuild

Local Installation

npm install @simple-software/simplebuild

Usage

Command Line

After global installation, you can use simplebuild from anywhere:

# Build current directory
simplebuild

# Build specific directory
simplebuild --working-dir=/path/to/your/project

# Use custom build directory name
simplebuild --working-dir=/path/to/project --simplebuild-dir=build

Programmatic API

You can also use Simple Build programmatically in your Node.js applications:

const { runSimpleBuild } = require('@simple-software/simplebuild');

async function buildProject() {
  try {
    const result = await runSimpleBuild({
      workingDir: '/path/to/your/project',
      simpleBuildDir: '.simplebuild' // optional, defaults to '.simplebuild'
    });
    
    console.log('Build completed with exit code:', result.exitCode);
    console.log('Output:', result.output);
  } catch (error) {
    console.error('Build failed:', error.message);
  }
}

buildProject();

Phases

Simple Build runs through five distinct phases:

1. Mirror – symlink your sources into a hidden directory
2. Analyze – inspect the mirrored files for dependencies
3. Generate – create Bazel build files from the analysis
4. Build – execute the Bazel build
5. Report – parse the build output and present the result

Prerequisites

• Node.js – version 23 or higher
• Bazel – builds the files mirrored into .simplebuild

Development

Prerequisites for Development

• JDK – required for running the Kotlin CLI via the Gradle wrapper
• pnpm – used for installing dependencies, running tests and linting
• Bazel – builds the files mirrored into .simplebuild

Running the CLI from Source

Use the Gradle wrapper to run the application and pass the working directory you want to mirror. You can optionally choose the name of the mirrored directory:

./gradlew run --args="--working-dir=<path> [--simplebuild-dir=<dir>]"

This creates a directory (by default .simplebuild) inside <path> containing symlinks of your source files. Stub MODULE.bazel, BUILD.bazel and .bazelversion files are also generated so you can invoke Bazel inside that directory.

Testing and linting

Install your JavaScript dependencies with pnpm and then run tests and linters with pnpm as well:

pnpm install
pnpm test
pnpm lint

Building the npm package

npm run build

End‑to‑end examples

Four example projects live under e2e/:

# Typescript example
cd e2e/typescript
pnpm install
../../gradlew run --args="--working-dir=$(pwd)"

# Vite example
cd ../vite
pnpm install
../../gradlew run --args="--working-dir=$(pwd)"

# JavaScript example
cd ../javascript
pnpm install
../../gradlew run --args="--working-dir=$(pwd)"

# JavaScript multiple files example
cd ../javascript-multiple-files
pnpm install
../../gradlew run --args="--working-dir=$(pwd)"

After running, inspect <project>/<dir> (defaults to .simplebuild) and use Bazel commands there.

Publishing

Automated Publishing (Recommended)

Use the semantic versioning commands for automated publishing:

# Patch version (0.0.6 → 0.0.7) - for bug fixes
npm run publish:patch

# Minor version (0.0.6 → 0.1.0) - for new features  
npm run publish:minor

# Major version (0.0.6 → 1.0.0) - for breaking changes
npm run publish:major

These commands will:

• Check for uncommitted changes
• Bump the version in package.json
• Commit the version change
• Build and test the package
• Create a git tag
• Push to GitHub
• Trigger GitHub Actions to publish to npm

Manual Publishing

For manual publishing with a specific version:

./scripts/publish.sh 0.0.7

License

MIT License - see LICENSE file for details.