{"id":15550,"library":"bsb-js","title":"bsb-js: BuckleScript Build Wrapper","description":"bsb-js is a foundational JavaScript library designed to programmatically interface with the BuckleScript build system (`bsb`), which is crucial for compiling ReasonML and OCaml source code into JavaScript. As of version 1.1.7, it provides an API to trigger compilation tasks, allowing developers to integrate BuckleScript builds into various JavaScript tooling environments like Webpack (via `bs-loader`) or Rollup (via `rollup-plugin-bucklescript`). The library is currently active, receiving updates primarily for compatibility with new `bs-platform` versions and improving error resilience. Its release cadence is driven by maintenance and necessary adaptations to the BuckleScript ecosystem. A key differentiator is its role in decoupling the core compilation logic from specific bundler integrations, enabling a more modular and reusable approach to integrating ReasonML/OCaml builds within JavaScript projects.","status":"active","version":"1.1.7","language":"javascript","source_language":"en","source_url":"https://github.com/reasonml-community/bs-loader","tags":["javascript","bsb","bucklescript","reason","reasonml"],"install":[{"cmd":"npm install bsb-js","lang":"bash","label":"npm"},{"cmd":"yarn add bsb-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add bsb-js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required 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.","package":"bs-platform","optional":false}],"imports":[{"note":"Primary asynchronous compilation function. CommonJS `require` works but ESM is preferred in modern tooling.","wrong":"const { compileFile } = require('bsb-js');","symbol":"compileFile","correct":"import { compileFile } from 'bsb-js';"},{"note":"Synchronous compilation function. Not a default export.","wrong":"import compileFileSync from 'bsb-js';","symbol":"compileFileSync","correct":"import { compileFileSync } from 'bsb-js';"},{"note":"Type import for configuration objects. Available when using TypeScript.","symbol":"ReadBsConfig","correct":"import type { ReadBsConfig } from 'bsb-js';"}],"quickstart":{"code":"import { writeFileSync, mkdirSync, readFileSync, rmSync } from 'fs';\nimport { join } from 'path';\nimport { compileFile } from 'bsb-js';\n\n// 1. Setup a dummy ReasonML project structure\nconst projectRoot = join(process.cwd(), 'temp_bsb_project');\nconst srcDir = join(projectRoot, 'src');\nconst bsConfigPath = join(projectRoot, 'bsconfig.json');\nconst reasonFilePath = join(srcDir, 'MyModule.re');\n\n// Ensure clean slate\ntry { rmSync(projectRoot, { recursive: true, force: true }); } catch (e) {}\nmkdirSync(srcDir, { recursive: true });\n\n// 2. Write a minimal bsconfig.json\nwriteFileSync(bsConfigPath, JSON.stringify({\n  \"name\": \"temp_project\",\n  \"sources\": [\"src\"],\n  \"package-specs\": {\n    \"module\": \"commonjs\",\n    \"in-source\": true\n  },\n  \"suffix\": \".bs.js\"\n}, null, 2));\n\n// 3. Write a simple ReasonML file\nwriteFileSync(reasonFilePath, `\nlet message = \"Hello from ReasonML!\";\nlet greet = () => print_endline(message);\n`);\n\nconsole.log('Dummy ReasonML project set up.');\n\n// 4. Use bsb-js to compile the file\nasync function compileMyModule() {\n  try {\n    console.log(`Compiling ${reasonFilePath} using bsb-js...`);\n    // The first argument is the root where bsconfig.json resides.\n    // The second argument is the path to the source file relative to the project root.\n    const result = await compileFile(projectRoot, 'src/MyModule.re', {\n      log: true // Output bsb logs to console\n    });\n\n    if (result.isSuccess) {\n      console.log('\\nCompilation successful!');\n      const jsFilePath = join(srcDir, 'MyModule.bs.js'); // Assuming in-source build\n      if (readFileSync(jsFilePath, 'utf8')) {\n        console.log(`Compiled JS content found at ${jsFilePath}`);\n        console.log('--- Compiled JS (first 100 chars) ---');\n        console.log(readFileSync(jsFilePath, 'utf8').substring(0, 100));\n        console.log('------------------------------------');\n      }\n    } else {\n      console.error('\\nCompilation failed:', result.errors);\n    }\n  } catch (error) {\n    console.error('\\nAn unexpected error occurred during compilation:', error);\n  } finally {\n    // Clean up temporary directory\n    console.log('\\nCleaning up temporary project...');\n    rmSync(projectRoot, { recursive: true, force: true });\n  }\n}\n\ncompileMyModule();\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Update `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.","message":"The `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.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Migrate 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.","message":"Starting 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.","severity":"breaking","affected_versions":">=2.0.0 (for bs-loader users transitioning)"},{"fix":"Ensure 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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install `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.","cause":"The `bsb` executable (part of `bs-platform`) is not found in the system's PATH. `bsb-js` relies on this external command.","error":"Error: spawn bsb ENOENT"},{"fix":"Review the error message details provided by `bsb` (which `bsb-js` forwards) and correct the syntax or logic in your source `.re` or `.ml` file.","cause":"The ReasonML or OCaml source file being compiled contains syntax errors or other compilation issues that `bsb` reports.","error":"Compilation failed: [...] \"errors\": [{ \"type\": \"error\", \"message\": \"Syntax error: [...]\" }]"},{"fix":"Run `npm install bsb-js` or `yarn add bsb-js`. Verify that your `import` or `require` statement correctly references the package name.","cause":"The `bsb-js` package has not been installed, or the import path is incorrect.","error":"Cannot find module 'bsb-js'"}],"ecosystem":"npm"}