extra-build

2.3.1 verified Sat May 09 auth: no javascript

Common build tools for extra-* packages, providing a JavaScript API for building TypeScript-based libraries. Version 2.3.1 is current. It offers utility functions for generating JavaScript and type declarations, bundling scripts, managing package metadata, executing shell commands, handling git operations (commit+push, branch setup), parsing GitHub URLs, updating repo details, logging with colors, and reading/writing text/JSON files. Unlike a CLI-based approach, this redesigned version provides flexibility via a programmable API, suitable for CI systems like GitHub Actions. It includes functions like bundleScript, webifyScript, exec, gitCommitPush, and updateGithubRepoDetails.

Common errors

error Cannot find module 'extra-build' or its corresponding type declarations. ↓

cause Package is ESM-only; project may be using CommonJS or missing typeRoots.

fix

Add "type": "module" to package.json, or use dynamic import(): const { bundleScript } = await import('extra-build').

error TypeError: bundleScript is not a function ↓

cause The named import is incorrect; usually default import used.

fix

Use import { bundleScript } from 'extra-build' instead of import bundleScript from 'extra-build'.

error Error: Cannot find module 'extra-build/git' ↓

cause Trying to import from a subpath that doesn't exist.

fix

All exports are at top-level: import { gitCommitPush, gitSetupBranch } from 'extra-build' directly.

Warnings

gotcha All functions are async; forgetting await leads to unresolved promises. ↓

fix Ensure all calls to extra-build functions are awaited.

breaking v2 removed the CLI and changed from CommonJS to ESM-only. ↓

fix Migrate from CLI usage to JavaScript API; use import instead of require.

gotcha bundleScript does not bundle type declarations by default; must be explicitly configured. ↓

fix Set declaration: true in the options object passed to bundleScript.

deprecated readDocument and writeDocument are experimental and may be removed in a future version. ↓

fix Prefer readFileText/writeFileText or readJson/writeJson for stable file I/O.

Install

npm install extra-build

yarn add extra-build

pnpm add extra-build

Imports

bundleScript

wrong

const bundleScript = require('extra-build').bundleScript

correct

import { bundleScript } from 'extra-build'

Package is ESM-only since v2. Use named imports.

exec
wrong
```
const exec = require('extra-build/exec')
```
correct
```
import { exec } from 'extra-build'
```
All functions are exported from the main entrypoint; no subpath imports.
readMetadata
```
import { readMetadata } from 'extra-build'
```
Also available as default export? No, only named exports in v2+.

writeMetadata

wrong

import writeMetadata from 'extra-build'

correct

import { writeMetadata } from 'extra-build'

Do not use default import; writeMetadata is a named export.

gitCommitPush

wrong

import { gitCommitPush } from 'extra-build/git'

correct

import { gitCommitPush } from 'extra-build'

No submodules; all exports are flat.

Quickstart

Demonstrates bundling a TypeScript source file, executing a shell command, and reading/writing package.json using extra-build API.

import { bundleScript, exec, writeMetadata, readMetadata } from 'extra-build';
import { writeFileSync } from 'fs';

async function build() {
  // Bundle source script
  const bundledCode = await bundleScript({
    input: 'src/index.ts',
    format: 'esm',
    target: 'es2020'
  });
  writeFileSync('dist/index.js', bundledCode);

  // Execute a shell command
  const output = await exec('echo Hello', { cwd: '.' });

  // Read and update package.json
  const meta = await readMetadata();
  meta.version = '1.0.0';
  await writeMetadata(meta);
}

build().catch(console.error);