Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
compileFile
✓ import { compileFile } from 'bsb-js';
✗ const { compileFile } = require('bsb-js');
Primary asynchronous compilation function. CommonJS `require` works but ESM is preferred in modern tooling.
compileFileSync
✓ import { compileFileSync } from 'bsb-js';
✗ import compileFileSync from 'bsb-js';
Synchronous compilation function. Not a default export.
ReadBsConfig
✓ import type { ReadBsConfig } from 'bsb-js';
Type import for configuration objects. Available when using TypeScript.
Demonstrates setting up a minimal ReasonML project structure, creating a `bsconfig.json` and a `.re` file, then programmatically compiling it using `bsb-js`'s `compileFile` function and verifying the output.
import { writeFileSync, mkdirSync, readFileSync, rmSync } from 'fs';
import { join } from 'path';
import { compileFile } from 'bsb-js';
// 1. Setup a dummy ReasonML project structure
const projectRoot = join(process.cwd(), 'temp_bsb_project');
const srcDir = join(projectRoot, 'src');
const bsConfigPath = join(projectRoot, 'bsconfig.json');
const reasonFilePath = join(srcDir, 'MyModule.re');
// Ensure clean slate
try { rmSync(projectRoot, { recursive: true, force: true }); } catch (e) {}
mkdirSync(srcDir, { recursive: true });
// 2. Write a minimal bsconfig.json
writeFileSync(bsConfigPath, JSON.stringify({
"name": "temp_project",
"sources": ["src"],
"package-specs": {
"module": "commonjs",
"in-source": true
},
"suffix": ".bs.js"
}, null, 2));
// 3. Write a simple ReasonML file
writeFileSync(reasonFilePath, `
let message = "Hello from ReasonML!";
let greet = () => print_endline(message);
`);
console.log('Dummy ReasonML project set up.');
// 4. Use bsb-js to compile the file
async function compileMyModule() {
try {
console.log(`Compiling ${reasonFilePath} using bsb-js...`);
// The first argument is the root where bsconfig.json resides.
// The second argument is the path to the source file relative to the project root.
const result = await compileFile(projectRoot, 'src/MyModule.re', {
log: true // Output bsb logs to console
});
if (result.isSuccess) {
console.log('\nCompilation successful!');
const jsFilePath = join(srcDir, 'MyModule.bs.js'); // Assuming in-source build
if (readFileSync(jsFilePath, 'utf8')) {
console.log(`Compiled JS content found at ${jsFilePath}`);
console.log('--- Compiled JS (first 100 chars) ---');
console.log(readFileSync(jsFilePath, 'utf8').substring(0, 100));
console.log('------------------------------------');
}
} else {
console.error('\nCompilation failed:', result.errors);
}
} catch (error) {
console.error('\nAn unexpected error occurred during compilation:', error);
} finally {
// Clean up temporary directory
console.log('\nCleaning up temporary project...');
rmSync(projectRoot, { recursive: true, force: true });
}
}
compileMyModule();
Debug
Known issues
breakingThe `compileFileSync` function's parameters were updated in `bsb-js@1.1.0` to match those of `compileFile` for consistency. Code relying on the older `compileFileSync` signature will break.fixUpdate `compileFileSync` calls to provide the project root and relative file path as separate arguments, along with an options object if needed. Refer to the `compileFile` signature for the correct pattern.
affects: >=1.1.0
breakingStarting with `bs-loader@2.0.0`, the core compilation logic was extracted into separate packages, including `bsb-js` and `read-bsconfig`. Projects previously using `bs-loader` as a monolithic solution will need to explicitly integrate `bsb-js` or use other bundler plugins built on top of it.fixMigrate from direct `bs-loader` usage to using `bsb-js` directly in custom build scripts, or adopt community-maintained plugins like `rollup-plugin-bucklescript` that now utilize `bsb-js` under the hood.
affects: >=2.0.0 (for bs-loader users transitioning)
gotcha`bsb-js` wraps the `bsb` executable. Compatibility issues can arise if the `bs-platform` version installed in your environment (globally or locally) is not aligned with the expectations of your `bsb-js` version. For instance, `bsb-js@1.1.7` includes a fix for `bs-platform` 4.0.5.fixEnsure your `bs-platform` installation is up-to-date and compatible with the `bsb-js` version you are using. Check `bsb-js` release notes for specific `bs-platform` version mentions. Generally, installing `bs-platform` as a `devDependency` and ensuring its `bsb` executable is in your PATH during builds is recommended.
affects: All versions
Errors
Common errors & fixes
Error: spawn bsb ENOENT
The `bsb` executable (part of `bs-platform`) is not found in the system's PATH. `bsb-js` relies on this external command.
fixInstall `bs-platform` globally (`npm install -g bs-platform`) or locally in your project (`npm install --save-dev bs-platform`) and ensure your build environment's PATH includes the local `node_modules/.bin` directory.
Compilation failed: [...] "errors": [{ "type": "error", "message": "Syntax error: [...]" }]
The ReasonML or OCaml source file being compiled contains syntax errors or other compilation issues that `bsb` reports.
fixReview the error message details provided by `bsb` (which `bsb-js` forwards) and correct the syntax or logic in your source `.re` or `.ml` file.
Cannot find module 'bsb-js'
The `bsb-js` package has not been installed, or the import path is incorrect.
fixRun `npm install bsb-js` or `yarn add bsb-js`. Verify that your `import` or `require` statement correctly references the package name.
Audit
Dependencies
bs-platformrequiredRequired for `bsb-js` to function, as it wraps the `bsb` compiler executable which is provided by `bs-platform`. Must be installed globally or as a devDependency in the project.