@beforesemicolon/builder

Utilities to build npm packages and a documentation website for Before Semicolon projects.

This package provides small, focused helpers to:

• Build server-friendly CommonJS and ESM module bundles (dist/cjs and dist/esm).
• Produce a browser bundle (dist/client.js) for documentation or demos.
• Render a static documentation website from Markdown files (output defaults to website/).

Table of contents

• Features
• Requirements
• Installation
• Quick examples
  • Library usage (Node)
  • Building the browser bundle
  • Generating the documentation website
• API
  • buildModules(options?)
  • buildBrowser(options?)
  • buildDocs(options?)
• Documentation site layout and front-matter
• Scripts (in package.json)
• Development
• Contributing
• License

Features

• Builds all TypeScript sources into both ESM and CJS formats using esbuild.
• Produces a single browser bundle for client-side documentation UI.
• Static site generator for Markdown: supports layouts, assets, stylesheets, and scripts.
• Uses marked + highlight.js for Markdown rendering, DOMPurify for sanitization and minifies output CSS/JS/HTML.
• Simple, zero-config defaults plus options for common customization.

Requirements

• Node.js >= 18.16.0 (see engines in package.json)

Installation

Install from npm (package name: @beforesemicolon/builder) or use the repo directly.

# npm
npm install @beforesemicolon/builder

# or using the repository
git clone https://github.com/beforesemicolon/builder.git
cd builder
npm install

Quick examples

Library usage (Node / programmatic)

// ESM
import { buildModules, buildBrowser, buildDocs } from '@beforesemicolon/builder'

// Build server-side modules (dist/esm and dist/cjs)
await buildModules({ directoryPath: 'src' })

// Build single browser bundle (defaults to src/client -> dist/client.js)
await buildBrowser({ entry: 'src/client', out: 'dist/client.js' })

// Generate static docs (defaults: docs -> website)
await buildDocs({ srcDir: 'docs', publicDir: 'website' })

CommonJS

const { buildModules, buildBrowser, buildDocs } = require('@beforesemicolon/builder')

;(async () => {
  await buildModules()
  await buildBrowser()
  await buildDocs()
})()

CLI / npm scripts

The repo ships with a build script that will emit types and run the TypeScript build entry (build.ts).

npm run build

This runs TypeScript declaration emission and then executes build.ts which calls buildModules() to produce the dist/ outputs.

API

• buildModules(options?: { directoryPath?: string }) => Promise

  • Scans the given directory (default: process.cwd()/src) recursively for files and builds them into:
    • dist/esm (ESM format)
    • dist/cjs (CommonJS format)
  • Files ending with .spec.ts or /client.ts are ignored from the module build set.
  • Uses esbuild with minification and keeps symbol names for better stack traces.

• buildBrowser(options?: { entry?: string; out?: string }) => Promise

  • Bundles a single browser file using esbuild.
  • Defaults: entry -> src/client, out -> dist/client.js.
  • Includes a small plugin to remove the Doc export from @beforesemicolon/html-parser during bundling (keeps bundle size smaller when that export isn't used).
  • Generates sourcemaps and minifies the output.

• buildDocs(options?: { srcDir?: string; publicDir?: string }) => Promise

  • Generates a static documentation website from a Markdown docs directory.
  • Defaults: srcDir -> docs, publicDir -> website.
  • Supported docs structure (defaults used by the generator):
    • _layouts/ — custom templates (each module should default-export a function matching PageProps)
    • assets/ — copied to the site output
    • stylesheets/ — CSS files are minified and copied
    • scripts/ — JS files are minified and copied
    • *.md — Markdown pages with front-matter to control metadata
  • Pages use marked with a custom renderer (heading IDs, code blocks, links) and highlight.js for syntax highlighting.
  • HTML is sanitized with DOMPurify and minified with html-minifier.

Documentation site layout and front-matter

Markdown pages should contain front-matter (YAML) with properties compatible with the site's PageProps:

• title: string — page title (used in the HTML title)
• description: string — meta description
• order: number — numeric order used when building the site map and sorting pages
• layout: string — layout name; corresponds to a template in _layouts (default: default)

PageProps (shape used by layouts)

• name: string
• path: string (page path, e.g. /guide/getting-started.html)
• order: number
• title: string
• description: string
• content: string (HTML produced from Markdown)
• siteMap: Map representing the site structure
• tableOfContent: array of { path, label } entries generated from headings

A minimal docs layout example (the package ships a simple default template):

export default ({ title, description, content }) => `
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="description" content="${description}" />
    <title>${title}</title>
  </head>
  <body>
    ${content}
  </body>
</html>`

Scripts (from package.json)

• build — removes dist, emits TypeScript declarations, then runs build.ts (which calls buildModules).
• lint — runs ESLint and Prettier check
• format — runs ESLint autofix and Prettier write

Development

• Ensure you use Node >= 18.16.0
• Install dependencies:

npm install

• Run the build pipeline locally:

npm run build

• Lint and format:

npm run lint
npm run format

• The source entry points are in src/. src/build-modules.ts, src/build-browser.ts and src/docs/run.ts provide the public functionality.

Testing and validation

This repository does not include automated tests by default. If you add tests, consider using the existing devDependencies (TypeScript + ts-jest + tinybench if you want benchmarks).

Contributing

Contributions are welcome. A good workflow is:

1. Fork the repository and create a feature branch.
2. Add or modify code in src/.
3. Run npm run build to check the build output.
4. Run npm run lint or npm run format to keep code style consistent.
5. Open a pull request describing the change.

License

BSD-3-Clause — see package.json for author and license metadata.

Acknowledgements and internals

• Uses esbuild for fast bundling and minification.
• Markdown rendering powered by marked with a custom renderer and marked-highlight plugin using highlight.js.
• Front-matter parsing via front-matter.
• DOM sanitization by isomorphic-dompurify and HTML/CSS/JS minification using html-minifier, clean-css, and @putout/minify respectively.

If you'd like any sections expanded (examples, advanced options, or a CONTRIBUTING.md), tell me which parts to elaborate and I'll add them.