Skip to content

README.md

Latest commit

 

History

History
169 lines (121 loc) · 4.38 KB

README.md

File metadata and controls

169 lines (121 loc) · 4.38 KB
Raw

@funish/build

GitHub npm version

Modern build system powered by tsdown with Jiti stub support.

🧑‍💻 Contributing? See the monorepo documentation for development setup and contribution guidelines.

What is @funish/build?

@funish/build is a build system designed for modern TypeScript/JavaScript projects. It leverages tsdown for ultra-fast bundling and Jiti for development stub generation.

Inspired by: unbuild, with modern tooling (Rolldown + Oxc).

Features

  • ⚡ tsdown-powered: Blazing fast builds powered by Rolldown and Oxc
  • 🔧 Zero Configuration: Sensible defaults with optional customization
  • 📦 Flexible Build Modes:
    • Bundle: Production bundling with code splitting
    • Unbundle: Keep module structure for plugins/tools
    • Stub: Development stubs with Jiti for instant iteration
  • 🎯 TypeScript First: Full TypeScript support with automatic type declarations
  • 📝 Jiti Integration: Runtime TypeScript execution for stub mode
  • 🔄 CITTY Compatible: CLI framework integration for easy automation
  • 🌍 Multi-format Output: Support for ESM, CJS, IIFE, and UMD

Quick Start

Installation

npm install -D @funish/build

Basic Usage

# Build with config file
isbuild

# Build specific entry
isbuild src/index.ts

# Build multiple entries
isbuild src/index.ts src/cli.ts

# Generate stubs
isbuild --stub src/index.ts

# With options
isbuild src/index.ts --format esm --minify --dts

CLI Options

Options:
  _                    Entry files
  --cwd <path>         Project directory (default: ".")
  --stub               Generate stub files
  --format <format>    Output format: esm, cjs, iife, umd
  --minify             Minify output
  --dts                Generate type declarations
  --out-dir <dir>      Output directory
  --clean              Clean output before build (default: true)
  --external <mods>    External dependencies (comma-separated)
  --watch              Watch mode
  --config <path>      Path to config file
  --no-config          Disable config file

Configuration

Using build.config.ts

import { defineBuildConfig } from "@funish/build/config";

export default defineBuildConfig({
  entries: [
    {
      entry: "src/index",
      minify: true,
    },
    {
      entry: "src/cli/**/*",
      outDir: "dist/cli/",
    },
  ],
});

Using vite.config.ts (Fallback)

When no build.config.ts is found, @funish/build automatically reads pack config from vite.config.ts:

import { defineConfig } from "vite-plus";

export default defineConfig({
  pack: {
    entry: ["src/index.ts", "src/cli/**/*"],
    minify: true,
  },
});

This enables seamless integration with Vite+ — use vp pack for production builds and isbuild --stub (or basis build --stub) for development stubs, all from the same configuration.

See tsdown documentation for all available options.

Stub Mode

Generate lightweight development stubs with Jiti for fast iteration:

# Via isbuild CLI
isbuild --stub

# Via basis CLI (reads pack.entry from vite.config.ts)
basis build --stub

Stub files use Jiti to load source TypeScript files at runtime, eliminating the need to rebuild during development.

Integration with Basis CLI

@funish/build integrates seamlessly with @funish/basis:

basis build --stub           # Generate stubs from vite.config.ts pack config

API

build(options)

import { build } from "@funish/build";

await build({
  cwd?: string;
  entries: (BuildEntry | string)[];
  hooks?: {
    start?: (ctx: BuildContext) => void | Promise<void>;
    end?: (ctx: BuildContext) => void | Promise<void>;
  };
});

BuildEntry extends tsdown's InlineConfig with:

  • stub?: boolean - Generate Jiti stub instead of bundling

defineBuildConfig(config)

import { defineBuildConfig } from "@funish/build/config";

export default defineBuildConfig({
  entries: [...],
});

License

MIT © Funish