# Before Semicolon Builder

Package-building utilities for Before Semicolon projects.

Builder 2.0 is focused exclusively on producing JavaScript packages. The
Markdown documentation builder and its templates were removed. Documentation
sites now belong to
[`@beforesemicolon/site-builder`](https://www.npmjs.com/package/@beforesemicolon/site-builder).

## Installation

```bash
npm install --save-dev @beforesemicolon/builder
```

## Build modules

`buildModules` compiles the TypeScript and JavaScript files under `src` into
ES modules and CommonJS modules. Specification files and `client.ts` are not
included in the module output.

```js
import { buildModules } from '@beforesemicolon/builder'

await buildModules()
```

The default output is:

```text
dist/
  esm/
  cjs/
```

Use another source directory when needed:

```js
await buildModules({ directoryPath: './source' })
```

Pass additional esbuild options through `esbuildOptions`. Builder continues to
own the source entries, output directories, module formats, and its required
plugins.

```js
await buildModules({
    esbuildOptions: {
        keepNames: false,
        target: 'es2022',
    },
})
```

## Build a browser bundle

`buildBrowser` bundles a browser entry point with esbuild. It defaults to
`src/client` and writes `dist/client.js` with a source map.

```js
import { buildBrowser } from '@beforesemicolon/builder'

await buildBrowser()
```

Custom entry and output paths are supported:

```js
await buildBrowser({
    entry: './src/browser.ts',
    out: './dist/browser.js',
})
```

Additional esbuild options can customize the browser build without replacing
its entry or output file. Custom plugins run after Builder's required plugin.

```js
await buildBrowser({
    esbuildOptions: {
        keepNames: false,
        sourcemap: false,
    },
})
```

## Migrating from Builder 1.x

`buildDocs` and `src/docs` are intentionally absent from Builder 2.0. Replace
the old import:

```js
import { buildDocs } from '@beforesemicolon/builder'
```

with:

```js
import { buildDocs } from '@beforesemicolon/site-builder/build-docs'

await buildDocs()
```

Configure Markdown documentation builds with `site.config.json` in the target
project. Builder does not retain a deprecated alias or compatibility layer for
the removed documentation API.

## License

BSD-3-Clause