robuild 0.0.5 → 0.0.7

package/README.md

@@ -8,48 +8,54 @@ English | <a href="./README-zh.md">简体中文</a>
 
 ⚡️ Zero-config ESM/TS package builder. Powered by [**oxc**](https://oxc.rs/), [**rolldown**](https://rolldown.rs/) and [**rolldown-plugin-dts**](https://github.com/sxzz/rolldown-plugin-dts).
 
-- 👌 Focus on ESM compatibility.
-- 🌱 Fresh rewrite with cleanups and removal of legacy features.
-- 🚀 Using [**oxc**](https://oxc.rs/) (for transform) and [**rolldown**](https://rolldown.rs/) (for bundle) for much faster builds!
+## Features
 
-## Proof of concept
+⚡ **Fast**: Built on top of [rolldown](https://rolldown.rs/) and [oxc](https://oxc.rs/)
+📦 **Zero config**: Works out of the box, configurable when needed
+🎯 **TypeScript**: First-class TypeScript support with `.d.ts` generation
+🔄 **Dual mode**: Bundle or transform your source code
+🚀 **Stub mode**: Lightning-fast development with file linking
+🏢 **Enterprise**: Workspace support, package filtering, migration tools
 
-> [!IMPORTANT]
->
-> Features are incomplete, and API and output behavior may change between 0.x versions.
->
-> Feedback and contributions are very welcome! If you'd like to make changes with more than a few lines of code, please open an issue first to discuss.
+## Installation
 
-## Usage
+```sh
+npm install robuild
+# or
+pnpm add robuild
+# or
+yarn add robuild
+```
 
-### CLI
+## Quick Start
 
 ```sh
-# bundle
+# Bundle your library
 npx robuild ./src/index.ts
 
-# transform
+# Transform source files
 npx robuild ./src/runtime/:./dist/runtime
-```
 
-You can use `--dir` to set the working directory.
+# Watch mode for development
+npx robuild ./src/index.ts --watch
+```
 
-If paths end with `/`, robuild uses transpile mode using [oxc-transform](https://www.npmjs.com/package/oxc-transform) instead of bundle mode with [rolldown](https://rolldown.rs/).
+## Usage
 
-### Programmatic
+```sh
+# Bundle your library
+npx robuild ./src/index.ts
 
-```js
-import { build } from 'robuild'
+# Transform source files
+npx robuild ./src/runtime/:./dist/runtime
 
-await build({
-  cwd: '.',
-  entries: ['./src/index.ts'],
-})
+# Watch mode for development
+npx robuild ./src/index.ts --watch
 ```
 
-## Config
+## Configuration
 
-You can use `build.config.mjs` (or `.ts`) or pass config to `build()` function.
+Create `build.config.ts` in your project root:
 
 ```js
 import { defineConfig } from 'robuild'
@@ -58,33 +64,150 @@ export default defineConfig({
   entries: [
     {
       type: 'bundle',
-      input: ['./src/index.ts', './src/cli.ts'],
-      // outDir: "./dist",
-      // minify: false,
-      // stub: false,
-      // rolldown: {}, // https://rolldown.rs/reference/config-options
-      // dts: {}, // https://github.com/sxzz/rolldown-plugin-dts#options
+      input: './src/index.ts',
+      format: ['esm', 'cjs'],
     },
     {
       type: 'transform',
       input: './src/runtime',
       outDir: './dist/runtime',
-      // minify: false,
-      // stub: false,
-      // oxc: {},
-      // resolve: {}
     },
   ],
-  hooks: {
-    // start: (ctx) => {},
-    // end: (ctx) => {},
-    // entries: (entries, ctx) => {},
-    // rolldownConfig: (config, ctx) => {},
-    // rolldownOutput: (output, res, ctx) => {},
+})
+```
+
+### Bundle Entry Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `input` | `string \| string[]` | Entry point(s) |
+| `format` | `OutputFormat \| OutputFormat[]` | Output format(s): `esm`, `cjs`, `iife`, `umd` |
+| `platform` | `Platform` | Target platform: `browser`, `node`, `neutral` |
+| `globalName` | `string` | Global name for IIFE/UMD formats |
+| `clean` | `boolean \| string[]` | Clean output directory |
+| `env` | `Record<string, any>` | Environment variables to inject |
+| `define` | `Record<string, string>` | Constants to define |
+| `external` | `(string \| RegExp)[] \| function` | External dependencies |
+| `noExternal` | `(string \| RegExp)[] \| function` | Force bundle dependencies |
+| `outDir` | `string` | Output directory (default: `dist`) |
+| `minify` | `boolean` | Minify output |
+| `dts` | `boolean \| DtsOptions` | Generate TypeScript declarations |
+
+## Advanced Features
+
+### Multi-format Output
+
+Build your library in multiple formats simultaneously:
+
+**Supported Formats:**
+- **ESM** (`.mjs`) - ES Modules for modern environments
+- **CJS** (`.cjs`) - CommonJS for Node.js compatibility
+- **IIFE** (`.js`) - Immediately Invoked Function Expression for browsers
+- **UMD** (`.js`) - Universal Module Definition for maximum compatibility
+
+**Output Structure:**
+```
+dist/
+├── index.mjs          # ESM format
+├── index.d.mts        # TypeScript declarations (ESM only)
+├── index.cjs          # CJS format
+└── index.js           # IIFE format
+```
+
+### Environment Variables & Constants
+
+Inject environment variables and define constants at build time:
+
+```js
+export default defineConfig({
+  entries: [
+    {
+      type: 'bundle',
+      input: './src/index.ts',
+      env: {
+        VERSION: '1.0.0',
+        NODE_ENV: 'production'
+      },
+      define: {
+        __DEV__: 'false',
+        BUILD_MODE: '"production"'
+      }
+    }
+  ]
+})
+```
+
+This replaces `process.env.VERSION` with `"1.0.0"` and `__DEV__` with `false` at compile time.
+
+### External Dependencies
+
+Control which dependencies are bundled or kept external:
+
+```js
+export default defineConfig({
+  entries: [
+    {
+      type: 'bundle',
+      input: './src/index.ts',
+      external: [
+        'lodash', // Keep lodash external
+        /^@types\//, // Keep all @types/* external
+        id => id.includes('node_modules') // Custom function
+      ],
+      noExternal: [
+        'some-package' // Force bundle this package
+      ]
+    }
+  ]
+})
+```
+
+## Watch Mode
+
+For development, robuild provides a watch mode that automatically rebuilds your project when files change.
+
+### CLI Usage
+
+```sh
+# Enable watch mode for any build
+npx robuild ./src/index.ts --watch
+
+# Watch mode with transform
+npx robuild ./src/runtime/:./dist/runtime --watch
+
+# Watch mode with custom working directory
+npx robuild ./src/index.ts --watch --dir ./my-project
+```
+
+### Configuration
+
+You can configure watch behavior in your `build.config.ts`:
+
+```js
+import { defineConfig } from 'robuild'
+
+export default defineConfig({
+  entries: ['./src/index.ts'],
+  watch: {
+    enabled: true, // Enable watch mode by default
+    include: ['src/**/*'], // Files to watch
+    exclude: ['**/*.test.ts'], // Files to ignore
+    delay: 100, // Rebuild delay in ms
+    ignoreInitial: false, // Skip initial build
+    watchNewFiles: true, // Watch for new files
   },
 })
 ```
 
+### Features
+
+- **Real-time rebuilding**: Automatically rebuilds when source files change
+- **Smart file detection**: Automatically determines what files to watch based on your entries
+- **Debounced rebuilds**: Configurable delay to prevent excessive rebuilds
+- **Error recovery**: Continues watching even after build errors
+- **Clear feedback**: Shows file changes and rebuild status
+- **Graceful shutdown**: Clean exit with Ctrl+C
+
 ## Stub Mode
 
 When working on a package locally, it can be tedious to rebuild or run the watch command every time.
@@ -107,6 +230,50 @@ You can use `stub: true` (per entry config) or the `--stub` CLI flag. In this mo
 - Using [oxc-node](https://github.com/oxc-project/oxc-node) (`node --import @oxc-node/core/register`)
 - Using [unloader](https://github.com/sxzz/unloader) (`node --import unloader/register`)
 
+## Status
+
+> [!IMPORTANT]
+>
+> This is a proof of concept. Features are incomplete, and API and output behavior may change between 0.x versions.
+>
+> Feedback and contributions are very welcome! If you'd like to make changes with more than a few lines of code, please open an issue first to discuss.
+
+## 📚 Documentation
+
+### 🎯 Guides
+- [Getting Started](./docs/guide/getting-started.md) - Get up and running in 5 minutes
+- [CLI Usage](./docs/guide/cli.md) - Complete command-line interface guide
+- [Configuration](./docs/guide/configuration.md) - Detailed configuration reference
+- [Build Modes](./docs/guide/build-modes.md) - Bundle vs Transform modes
+- [Watch Mode](./docs/guide/watch-mode.md) - Real-time development builds
+- [Stub Mode](./docs/guide/stub-mode.md) - Lightning-fast development mode
+- [TypeScript](./docs/guide/typescript.md) - TypeScript best practices
+- [ESM](./docs/guide/esm.md) - ES modules support
+- [Performance](./docs/guide/performance.md) - Build performance optimization
+
+### 🔧 Feature Guides
+- [CLI & Config Enhancements](./docs/guide/cli-config-enhancements.md) - Multi-format output, platform targets, environment variables
+- [Build Enhancements](./docs/guide/build-enhancements.md) - File copying, hashing, banner/footer, extensions
+- [Development Experience](./docs/guide/dev-experience.md) - Success callbacks, watch optimization, Vite integration
+
+### 🏢 Enterprise Features
+- [Enterprise Features](./docs/guide/enterprise.md) - Workspace, filtering, exports, migration
+- [Plugin System](./docs/guide/plugins.md) - Plugin development and usage
+- [Advanced Build Options](./docs/guide/advanced-build.md) - Loaders, shims, CJS handling
+- [Hooks](./docs/guide/hooks.md) - Build lifecycle hooks
+
+### 📖 API Reference
+- [API Overview](./docs/api/index.md) - Programmatic API overview
+- [Configuration API](./docs/api/config.md) - Configuration options
+- [CLI API](./docs/api/cli.md) - Command-line interface
+- [Type Definitions](./docs/api/types.md) - TypeScript type definitions
+
+### 🏗️ Architecture
+- [Core Architecture](./docs/architecture/core.md) - robuild core design
+- [Builders](./docs/architecture/builders.md) - Bundle and Transform builders
+- [Plugin System](./docs/architecture/plugins.md) - Plugin architecture design
+- [Performance](./docs/architecture/performance.md) - Performance optimization strategies
+
 ## Prior Arts
 
 - [unbuild](https://github.com/unjs/unbuild): Stable solution based on rollup and [mkdist](https://github.com/unjs/mkdist).