Builderz

Common errors

• Error: Cannot find module 'builderz'

  cause The 'builderz' package is not installed or incorrectly referenced in your project's `node_modules`.
  fix Run `npm install builderz` or `yarn add builderz` to add it to your project's dependencies. Ensure your `package.json` correctly lists it under `devDependencies` or `dependencies`.

• Error: Invalid or missing configuration file

  cause The `builderz` command was run without a specified configuration file, or the specified file (`-c`) could not be found or parsed.
  fix Ensure you have a `builderz.config.js` (or `.ts`) file in your project root, or explicitly point to its location using `builderz build -c ./path/to/builderz.config.js`. Verify the file's syntax for any JavaScript/TypeScript errors.

• Build failed with errors

  cause Generic error indicating an issue during the bundling process, often related to syntax errors in source code, missing dependencies, or incorrect plugin configuration.
  fix Examine the console output for more specific error messages, which will usually pinpoint the problematic file or configuration setting. Check your source code for syntax errors, ensure all imported modules exist, and verify your `builderz.config.js` is valid.

Warnings

• breaking The arguments for the `builderz` CLI and potentially its programmatic API were updated in `v0.9.0`. This might require changes to existing build scripts or configurations.
  Fix: Refer to the updated documentation on the GitHub repository for the correct argument structure and configuration options for `builderz.config.js` files.
• gotcha As a 'zero-configuration' bundler, Builderz makes many assumptions by default. While this simplifies setup, it can be less flexible for highly customized build requirements or complex monorepos without explicit configuration overrides.
  Fix: For custom behaviors, utilize the `builderz.config.js` file and its `plugins` option. Inspect the generated output to understand default behaviors. Consider other bundlers if deep, fine-grained control is consistently required beyond what `builderz` exposes.
• gotcha Starting from `v0.10.0`, the internal caching mechanism was switched from using a `Map` to a plain JavaScript object. While this is primarily an internal change, it could theoretically have subtle performance implications or edge-case behaviors in very specific environments or with extremely large projects.
  Fix: Monitor build times and cache effectiveness after updating to `v0.10.x` or later. If unexpected performance degradation occurs, consider reverting or reporting an issue to the maintainers.

Install

• npm install builderz npm
• yarn add builderz yarn
• pnpm add builderz pnpm

Imports

• build
  wrong:

  const { build } = require('builderz')

  correct:

  import { build } from 'builderz'

  Builderz primarily uses ESM for its programmatic API. While CommonJS `require` might work in some contexts, ESM imports are the recommended and most robust approach.
• watch
  wrong:

  const { watch } = require('builderz')

  correct:

  import { watch } from 'builderz'

  Used for development mode to automatically rebuild on file changes. Follows the same ESM import recommendation as `build`.
• defineConfig
  wrong:

  import defineConfig from 'builderz'

  correct:

  import { defineConfig } from 'builderz'

  This utility function is specifically for type-checking and autocompletion in your `builderz.config.js` or `builderz.config.ts` file, and is a named export.

Quickstart

Demonstrates setting up a `package.json`, a `builderz.config.js` with ES module support, and an entry file, then running a build via CLI.

{
  "name": "my-builderz-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "builderz build -c builderz.config.js",
    "start": "node dist/esm/index.js"
  },
  "devDependencies": {
    "builderz": "^0.11.0"
  }
}

// builderz.config.js
import { defineConfig } from 'builderz';

export default defineConfig({
  entries: ['src/index.js'],
  output: {
    dir: 'dist',
    formats: ['esm', 'cjs'],
    fileName: '[name].[format].js'
  },
  plugins: [],
  external: [] // Example: externalize node built-in modules
});

// src/index.js
import path from 'node:path';
import url from 'node:url';

const __dirname = path.dirname(url.fileURLToPath(import.meta.url));

console.log(`Hello from Builderz! Running from: ${__dirname}`);