# ESBuild

ESBuild is an extremely fast JavaScript and CSS bundler and minifier written in Go. It provides comprehensive build tooling with native support for JavaScript, CSS, TypeScript, and JSX, featuring built-in tree shaking, minification, source map generation, and extensive platform support.

## Package Information

- **Package Name**: esbuild
- **Package Type**: npm
- **Language**: Go (with JavaScript/TypeScript APIs)
- **Installation**: `npm install esbuild`

## Core Imports

```typescript
import * as esbuild from "esbuild";
```

For specific imports:

```typescript
import { build, transform, buildSync, transformSync } from "esbuild";
```

CommonJS:

```javascript
const esbuild = require("esbuild");
const { build, transform } = require("esbuild");
```

## Basic Usage

```typescript
import * as esbuild from "esbuild";

// Build a project
const result = await esbuild.build({
  entryPoints: ["src/app.js"],
  bundle: true,
  minify: true,  
  outfile: "dist/app.js",
});

// Transform a single file
const transformed = await esbuild.transform(`
  const greeting = (name: string) => \`Hello \${name}!\`;
`, {
  loader: "ts",
  format: "esm",
});

console.log(transformed.code);
```

## Architecture

ESBuild is structured around several core concepts:

- **Build Operations**: Complete project bundling with file resolution, dependency analysis, and output generation
- **Transform Operations**: Single-file transformation for syntax conversion and minification
- **Build Context**: Advanced interface providing watch mode, development server, and rebuild capabilities  
- **Plugin System**: Extensible architecture for custom build logic and transformations
- **Platform Flexibility**: Native binaries for optimal performance with WebAssembly fallback

## Capabilities

### Core Build API

Primary build functionality for bundling, transforming, and optimizing JavaScript/CSS projects. Supports both asynchronous and synchronous operations.

```typescript { .api }
function build(options: BuildOptions): Promise<BuildResult>;
function buildSync(options: BuildOptions): BuildResult;
```

[Core Build API](./core-build-api.md)

### File Transformation  

Single-file transformation capabilities for syntax conversion, minification, and format conversion without full bundling.

```typescript { .api }
function transform(
  input: string | Uint8Array, 
  options?: TransformOptions
): Promise<TransformResult>;

function transformSync(
  input: string | Uint8Array, 
  options?: TransformOptions  
): TransformResult;
```

[File Transformation](./file-transformation.md)

### Build Context & Advanced Features

Advanced build management with watch mode, development server, and incremental rebuilding capabilities.

```typescript { .api }
function context(options: BuildOptions): Promise<BuildContext>;

interface BuildContext {
  rebuild(): Promise<BuildResult>;
  watch(options?: WatchOptions): Promise<void>;
  serve(options?: ServeOptions): Promise<ServeResult>;
  cancel(): Promise<void>;
  dispose(): Promise<void>;
}
```

[Build Context & Advanced Features](./build-context.md)

### Plugin System

Extensible plugin architecture for custom build transformations, file resolution, and code generation.

```typescript { .api }
interface Plugin {
  name: string;
  setup(build: PluginBuild): void;
}

interface PluginBuild {
  initialOptions: BuildOptions;
  onStart(callback: () => Promise<void>): void;
  onEnd(callback: (result: BuildResult) => Promise<void>): void;
  onResolve(options: OnResolveOptions, callback: OnResolveCallback): void;
  onLoad(options: OnLoadOptions, callback: OnLoadCallback): void;
  resolve(path: string, options?: ResolveOptions): Promise<ResolveResult>;
  esbuild: {
    build: typeof build;
    transform: typeof transform;
    formatMessages: typeof formatMessages;
    analyzeMetafile: typeof analyzeMetafile;
  };
}
```

[Plugin System](./plugin-system.md)

### Utility Functions

Additional utilities for message formatting, metafile analysis, and service management.

```typescript { .api }
function formatMessages(
  messages: PartialMessage[], 
  options: FormatMessagesOptions
): Promise<string[]>;

function analyzeMetafile(
  metafile: Metafile | string, 
  options?: AnalyzeMetafileOptions
): Promise<string>;

function initialize(options: InitializeOptions): Promise<void>;
function stop(): Promise<void>;

const version: string;
```

[Utility Functions](./utility-functions.md)

## Types

```typescript { .api }
interface BuildOptions {
  // Entry points
  entryPoints?: string[] | Record<string, string> | { in: string; out: string }[];
  stdin?: StdinOptions;
  
  // Output configuration
  bundle?: boolean;
  outfile?: string;
  outdir?: string;
  outbase?: string;
  format?: Format;
  splitting?: boolean;
  
  // Platform and environment
  platform?: Platform;
  target?: string | string[];
  
  // Processing options
  minify?: boolean;
  sourcemap?: boolean | "linked" | "inline" | "external" | "both";
  treeShaking?: boolean;
  
  // Advanced options
  plugins?: Plugin[];
  external?: string[];
  loader?: Record<string, Loader>;
  resolveExtensions?: string[];
  metafile?: boolean;
  write?: boolean;
  
  // And many more options...
}

interface BuildResult {
  errors: Message[];
  warnings: Message[];
  outputFiles?: OutputFile[];
  metafile?: Metafile;
  mangleCache?: Record<string, string | false>;
}

interface TransformOptions {
  loader?: Loader;
  format?: Format;
  target?: string | string[];
  minify?: boolean;
  sourcemap?: boolean | "linked" | "inline" | "external" | "both";
  sourcefile?: string;
  banner?: string;
  footer?: string;
  // Plus all CommonOptions...
}

interface TransformResult {
  code: string;
  map: string;
  warnings: Message[];
  mangleCache?: Record<string, string | false>;
  legalComments?: string;
}

type Platform = "browser" | "node" | "neutral";
type Format = "iife" | "cjs" | "esm"; 
type Loader = "js" | "jsx" | "ts" | "tsx" | "css" | "json" | "text" | "base64" | "file" | "dataurl" | "binary" | "copy" | "default" | "empty" | "local-css";
```