oxbuild

0.1.5 verified Fri May 01 auth: no javascript

oxbuild is an ultra-fast tsc-like compiler built on top of the oxc toolchain. It transpiles TypeScript, JavaScript, JSX, and TSX, emits .d.ts files for projects with isolatedDeclarations, and generates JS source maps. Current stable version is 0.1.5, released via npm and crates.io with no fixed release cadence until stable. Its key differentiator is raw speed compared to tsc and swc by leveraging the oxc parser written in Rust. As of v0.1.5, it is still in alpha, not recommended for production use, and limitations include incomplete TSConfig support and experimental declarations.

Common errors

error Error: Cannot find module 'oxbuild' ↓

cause Trying to require('oxbuild') as a Node.js library instead of using it as an installed CLI binary.

fix

Do not use require('oxbuild'). Install globally and run 'oxbuild' from command line. For npx use: npx oxbuild.

error Command 'oxbuild' not found ↓

cause oxbuild not installed or not in PATH.

fix

Install globally: npm install -g oxbuild. Or use npx: npx oxbuild.

error unknown option '--config' ↓

cause Used --config instead of --tsconfig.

fix

Use --tsconfig to specify a tsconfig file. E.g., oxbuild --tsconfig tsconfig.json

error Unable to find tsconfig.json ↓

cause oxbuild could not locate a tsconfig.json in the project root directory.

fix

Ensure tsconfig.json exists in the project root (where package.json is) or specify path with --tsconfig.

Warnings

gotcha oxbuild does not support all tsconfig options; only rootDir and outDir are respected. Other fields like strict or paths may be ignored silently. ↓

fix Review tsconfig options. Open an issue on GitHub if a specific option is missing.

breaking The CLI API is unstable and may change without notice before stable release (v1.0.0). Flags and default behavior can break across minor versions. ↓

fix Pin the exact version in CI and scripts. Monitor changelog.

deprecated The --tsconfig flag may be renamed or replaced in future versions. The current flag is --tsconfig but may change to --config. ↓

fix Be prepared to update scripts. Check release notes for changes.

gotcha Generating .d.ts files requires isolatedDeclarations enabled in tsconfig. Without it, no declaration files are emitted. ↓

fix Enable "isolatedDeclarations": true in tsconfig.json.

gotcha oxbuild is built on oxc which is also pre-1.0. Bugs in oxc often propagate to oxbuild. Expect potential crashes or incorrect output. ↓

fix Report issues to the oxbuild repository with RUST_LOG=debug output.

gotcha Node.js version must be >=14. Running on older versions will fail with cryptic errors. ↓

fix Upgrade Node.js to v14 or later.

Install

npm install oxbuild

yarn add oxbuild

pnpm add oxbuild

Imports

oxbuild
wrong
```
require('oxbuild')
```
correct
```
npx oxbuild
```
oxbuild is a CLI binary, not a library. Use npx or global install to run.
install
wrong
```
npm install oxbuild --save
```
correct
```
npm install -g oxbuild
```
oxbuild is intended for global use, not a project dependency. However, local install also works with npx.
use with tsconfig
wrong
```
oxbuild tsconfig.json
```
correct
```
oxbuild --tsconfig tsconfig.json
```
The tsconfig path must be passed with --tsconfig flag.

Quickstart

Shows global installation and basic CLI usage: running oxbuild in a project with default src/ layout.

# Install globally
npm install -g oxbuild

# In a TypeScript project, compile from ./src to ./dist
oxbuild

# With custom tsconfig
oxbuild --tsconfig tsconfig.json

# With debug logs
RUST_LOG=debug oxbuild