Zile

https://github.com/wevm/zile
Admin
Zile is an opinionated zero-config build tool for transpiling TypeScript libraries to ESM-only...
Tokens:25,038
Snippets:304
Trust Score:8
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### zile examples:check

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Typecheck and optionally format JSDoc examples.

```APIDOC
## zile examples:check

### Description
Typecheck and optionally format JSDoc examples.

### Signature
`zile examples:check [--cwd <dir>] [--source-dir <dir>] [--project <path>] [--fix]`

### Options
- **--cwd** (string) - Optional - Working directory (default: current working directory)
- **--source-dir** (string) - Optional - Directory to scan for source files (default: <cwd>/src)
- **--project** (string) - Optional - Path to tsconfig.json (default: ./tsconfig.json)
- **--fix** (boolean) - Optional - Write formatted snippets back into source files
```

--------------------------------

### Examples Module

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Functions for managing JSDoc code blocks in examples.

```APIDOC
## Examples.extract(options)

### Description
Extract JSDoc code blocks.

### Parameters
- **file** (string) - Required - Source file path
- **source** (string) - Required - Source code

## Examples.check(options)

### Description
Type-check all examples.

### Parameters
- **cwd** (string) - Optional - Working directory (default: process.cwd())
- **sourceDir** (string) - Optional - Source scan directory (default: cwd/src)
- **format** (boolean) - Optional - Format snippets (default: true)
- **formatOptions** (FormatOptions) - Optional - Formatter options
- **project** (string) - Optional - tsconfig path (default: ./tsconfig.json)
- **fix** (boolean) - Optional - Write fixes (default: false)
- **workDir** (string) - Optional - Temp directory (default: cwd/.examples)

## Examples.applyFixes(options)

### Description
Write fixes back to source.

### Parameters
- **fixes** (Map<Block, string>) - Required - Block to code mapping
```

--------------------------------

### Initialize and Build Project

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Standard workflow for creating, installing, and building a new Zile-managed package.

```bash
# Create new project
npx zile new --npm

# Enter directory
cd my-package

# Install dependencies
npm install

# Build
npm run build
```

--------------------------------

### Execute Full Example Workflow

Source: https://github.com/wevm/zile/blob/main/_autodocs/04-examples.md

A complete sequence for extracting, checking, reporting, and applying fixes to JSDoc examples.

```typescript
import * as Examples from 'zile/Examples'

// 1. Extract and check all examples
const result = await Examples.check({
  cwd: '/path/to/package',
  format: true,
  fix: false  // Don't auto-fix yet
})

// 2. Report findings
if (result.typeErrors.length > 0) {
  console.error('Type errors found:')
  for (const error of result.typeErrors) {
    console.error(`  ${error.message}`)
  }
}

if (result.formatFixes.size > 0) {
  console.log('Formatting issues found:')
  for (const block of result.formatFixes.keys()) {
    console.log(`  ${block.file}:${block.startLine}`)
  }
  
  // 3. Apply formatting fixes
  await Examples.applyFixes({ fixes: result.formatFixes })
  console.log('Formatting fixes applied')
}

console.log(`Checked ${result.blocks.length} examples`)
```

--------------------------------

### Enable JSDoc example checking

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Validates JSDoc examples before building, exiting with code 1 on failure.

```bash
zile build --check-examples
```

--------------------------------

### Define Example Check Options

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Configuration interface for validating and formatting code examples.

```typescript
{
  cwd?: string                    // Working directory
  sourceDir?: string              // Source files directory
  format?: boolean                // Format snippets
  formatOptions?: FormatOptions   // Formatter config
  project?: string                // Path to tsconfig.json
  fix?: boolean                   // Write fixes
  workDir?: string                // Temp directory
}
```

--------------------------------

### Development mode with symlinks

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Starts the development environment with symlink support.

```bash
zile dev
```

--------------------------------

### Configuration Resolution Example

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Illustrates how Zile resolves the output directory based on the configuration hierarchy.

```text
CLI: zile build --cwd ./packages/core
  ↓ (no outDir flag, check tsconfig.json)
tsconfig.json: { "compilerOptions": { "outDir": "./build" } }
  ↓ (found!)
Output: ./packages/core/build
```

--------------------------------

### Example tsconfig.json configuration

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

A complete example of a tsconfig.json file compatible with Zile. Note that some values may be overridden by the framework.

```json
{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "lib": ["es2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}
```

--------------------------------

### Examples.check

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Validates extracted code examples.

```APIDOC
## Examples.check(options: check.Options)

### Description
Checks code examples for formatting and type errors.

### Parameters
- **cwd** (string) - Optional - Working directory
- **sourceDir** (string) - Optional - Source files directory
- **format** (boolean) - Optional - Format snippets
- **formatOptions** (object) - Optional - Formatter config
- **project** (string) - Optional - Path to tsconfig.json
- **fix** (boolean) - Optional - Write fixes
- **workDir** (string) - Optional - Temp directory
```

--------------------------------

### Set source directory for examples

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Defines the directory to scan for TypeScript source files containing JSDoc examples.

```bash
zile examples:check --source-dir ./lib
```

--------------------------------

### Build a package with various configurations

Source: https://github.com/wevm/zile/blob/main/_autodocs/02-package.md

Examples of using the build function for basic builds, development mode with symlinks, using tsgo, and specifying a custom tsconfig path.

```typescript
import * as Package from 'zile/Package'

// Basic build
const result = await Package.build({
  cwd: '/path/to/package',
})
console.log(result.packageJson.main) // "./dist/index.js"
console.log(result.packageJson.exports) // { ".": { ... } }

// Development mode with symlinks
await Package.build({
  cwd: '/path/to/package',
  link: true
})

// Using tsgo for faster transpilation
await Package.build({
  cwd: '/path/to/package',
  tsgo: true
})

// Custom tsconfig path
await Package.build({
  cwd: '/path/to/package',
  project: './tsconfig.build.json'
})
```

--------------------------------

### Apply formatting fixes example

Source: https://github.com/wevm/zile/blob/main/_autodocs/04-examples.md

Demonstrates how to check for formatting issues and apply fixes to source files.

```typescript
import * as Examples from 'zile/Examples'

// Get formatting fixes
const result = await Examples.check({
  cwd: '/path/to/package',
  fix: false
})

// Review and apply fixes
if (result.formatFixes.size > 0) {
  console.log(`Applying ${result.formatFixes.size} format fixes`)
  await Examples.applyFixes({
    fixes: result.formatFixes
  })
}
```

--------------------------------

### Example usage of readPackageJson

Source: https://github.com/wevm/zile/blob/main/_autodocs/02-package.md

Demonstrates reading a package.json file from a specified directory.

```typescript
import * as Package from 'zile/Package'

const pkgJson = await Package.readPackageJson({
  cwd: '/path/to/package'
})

console.log(pkgJson.name)
console.log(pkgJson.main)
```

--------------------------------

### Usage of decoratePackageJson

Source: https://github.com/wevm/zile/blob/main/_autodocs/02-package.md

Example demonstrating how to invoke decoratePackageJson with a sample package configuration and options.

```typescript
import * as Package from 'zile/Package'

const decorated = await Package.decoratePackageJson(
  {
    name: 'my-lib',
    main: './src/index.ts',
    exports: {
      '.': './src/index.ts',
      './utils': './src/utils.ts'
    }
  },
  {
    cwd: '/path/to/package',
    link: false,
    outDir: '/path/to/package/dist',
    sourceDir: '/path/to/package/src',
    assets: []
  }
)
```

--------------------------------

### Example usage of stripPreMarkerKeys

Source: https://github.com/wevm/zile/blob/main/_autodocs/02-package.md

Demonstrates removing development-only fields from a package object.

```typescript
const original = {
  scripts: { build: 'zile' },
  devDependencies: { zile: '^0.1.0' },
  '[!start-pkg]': '',
  name: 'my-pkg',
  version: '1.0.0'
}

const stripped = Package.stripPreMarkerKeys(original)
// { name: 'my-pkg', version: '1.0.0' }
```

--------------------------------

### Check JSDoc examples

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Validates JSDoc examples for type errors and formatting, with an optional fix flag to apply formatting changes.

```bash
zile examples:check [--cwd <dir>] [--source-dir <dir>] [--project <path>] [--fix]
```

--------------------------------

### Install Zile dependencies

Source: https://github.com/wevm/zile/blob/main/README.md

Adds Zile and TypeScript as development dependencies to an existing project.

```bash
npm i zile typescript -D
```

--------------------------------

### Build a package

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Builds a package at the specified directory using tsc or tsgo, with optional JSDoc example typechecking.

```bash
zile build [--cwd <dir>] [--project <path>] [--check-examples] [--tsgo]
```

--------------------------------

### Execute Zile CLI commands

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Examples of invoking the CLI with process arguments or specific command configurations.

```typescript
import * as Cli from 'zile/Cli'

// Run the CLI with process arguments
await Cli.run({
  args: process.argv
})

// Or run with specific arguments
await Cli.run({
  args: ['build', '--cwd', './packages/my-lib', '--project', './tsconfig.build.json']
})

// Run dev mode
await Cli.run({
  args: ['dev', '--cwd', '.']
})
```

--------------------------------

### Extract and Check Examples

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Extracts code blocks from source files and validates them.

```typescript
import * as Examples from 'zile/Examples'
import * as fs from 'node:fs'

const source = fs.readFileSync('./src/index.ts', 'utf-8')
const blocks = Examples.extract({
  file: '/absolute/path/to/src/index.ts',
  source
})

console.log(`Extracted ${blocks.length} blocks`)

const result = await Examples.check({
  cwd: '.',
  fix: true
})

if (result.typeErrors.length > 0) {
  console.error('Type errors:', result.typeErrors)
}
```

--------------------------------

### Check and Fix JSDoc Examples

Source: https://github.com/wevm/zile/blob/main/_autodocs/README.md

Uses the Examples module to validate JSDoc code blocks and optionally apply formatting fixes.

```typescript
import * as Examples from 'zile/Examples'

const result = await Examples.check({
  cwd: '.',
  fix: true  // Write fixes back
})

console.log(`Fixed ${result.formatFixes.size} formatting issues`)
```

--------------------------------

### Use the find function to discover packages

Source: https://github.com/wevm/zile/blob/main/_autodocs/03-packages.md

Examples showing how to use the find function with various options for monorepo discovery, pattern matching, and exclusions.

```typescript
import * as Packages from 'zile/Packages'

// Find all packages in a monorepo
const packages = await Packages.find({
  cwd: '/path/to/monorepo'
})
// Returns: ['/path/to/monorepo/packages/foo', '/path/to/monorepo/packages/bar']

// Find packages in a specific pattern
const packages = await Packages.find({
  cwd: '/path/to/monorepo',
  includes: ['packages/*/package.json']
})

// Find packages excluding certain directories
const packages = await Packages.find({
  cwd: '/path/to/monorepo',
  includes: ['packages/**', '!**/node_modules/**', '!**/dist/**']
})

// Find with multiple include patterns
const packages = await Packages.find({
  cwd: '/path/to/monorepo',
  includes: [
    'packages/*',
    'tools/*',
    '!**/node_modules/**'
  ]
})
```

--------------------------------

### check(options)

Source: https://github.com/wevm/zile/blob/main/_autodocs/04-examples.md

Type-checks and optionally formats every JSDoc example under a directory.

```APIDOC
## check(options)

### Description
Type-checks and optionally formats every JSDoc example under a directory. It walks the source directory, extracts code blocks, validates them with `tsc`, and optionally applies formatting.

### Signature
`async function check(options?: check.Options): Promise<check.ReturnType>`

### Parameters
- **options** (check.Options) - Optional - Configuration object for the check process.
  - **cwd** (string) - Optional - Working directory (default: `process.cwd()`).
  - **sourceDir** (string) - Optional - Directory to scan for source files (default: `path.resolve(cwd, 'src')`).
  - **format** (boolean) - Optional - Whether to format snippets with oxfmt (default: `true`).
  - **formatOptions** (FormatOptions) - Optional - Oxfmt formatting options.
  - **project** (string) - Optional - Path to tsconfig.json relative to cwd (default: './tsconfig.json').
  - **fix** (boolean) - Optional - Write formatted snippets back to source (default: `false`).
  - **workDir** (string) - Optional - Temporary directory for staged examples (default: `path.resolve(cwd, '.examples')`).

### Return Type
- **blocks** (readonly Block[]) - Every extracted block, in source order.
- **typeErrors** (readonly TypeError[]) - Type errors reported by `tsc` against the extracted examples.
- **formatFixes** (Map<Block, string>) - Mapping of block to formatted code for blocks that aren't already formatted.

### Example Usage
```typescript
import * as Examples from 'zile/Examples'

const result = await Examples.check({
  cwd: '/path/to/package',
  fix: true
})

console.log(`Checked ${result.blocks.length} examples`)
```
```

--------------------------------

### Example usage of check()

Source: https://github.com/wevm/zile/blob/main/_autodocs/04-examples.md

Demonstrates how to invoke the check function with specific options.

```typescript
import * as Examples from 'zile/Examples'

// Check examples with formatting
const result = await Examples.check({
  cwd: '/path/to/package',
  fix: true  // Write fixes back
})

console.log(`Checked ${result.blocks.length} examples`)
console.log(`Found ${result.typeErrors.length} type errors`)
console.log(`Fixed ${result.formatFixes.size} formatting issues`)

if (result.typeErrors.length > 0) {
  for (const error of result.typeErrors) {
    if (error.block) {
      console.error(
        `${error.block.file}:${error.block.startLine} - ${error.message}`
      )
    } else {
      console.error(error.raw)
    }
  }
}
```

--------------------------------

### Extract code blocks usage

Source: https://github.com/wevm/zile/blob/main/_autodocs/04-examples.md

Demonstrates how to read a source file and extract JSDoc code blocks using the Examples module.

```typescript
import * as Examples from 'zile/Examples'
import * as fs from 'node:fs'

const source = fs.readFileSync('./src/index.ts', 'utf-8')

const blocks = Examples.extract({
  file: '/absolute/path/to/src/index.ts',
  source
})

for (const block of blocks) {
  console.log(`Block ${block.index} at line ${block.startLine}:`)
  console.log(block.code)
}
```

--------------------------------

### Create new project

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Initializes a new project, optionally specifying the package manager.

```bash
zile new
zile new --pnpm
zile new --bun
```

--------------------------------

### Create a new project

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Scaffolds a new Zile project from the template directory with interactive prompts.

```bash
zile new [--npm] [--pnpm] [--bun]
```

--------------------------------

### Prepare for publishing

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Generates build outputs and creates a stripped version of package.json for publishing.

```bash
zile publish:prepare [--cwd <dir>]
```

--------------------------------

### Initialize a new Zile project

Source: https://github.com/wevm/zile/blob/main/README.md

Creates a new project with opinionated defaults using the Zile CLI.

```bash
npx zile new
```

--------------------------------

### Prepare for publishing

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Executes the pre-publish, npm publish, and post-publish lifecycle steps.

```bash
zile publish:prepare
npm publish
zile publish:post
```

--------------------------------

### Configure multiple binaries

Source: https://github.com/wevm/zile/blob/main/README.md

Use keys with a .src suffix in the bin object to define multiple CLI entrypoints.

```diff
{
  "name": "my-cli",
  "version": "0.0.0",
  "type": "module",
+ "bin": {
+   "foo.src": "./src/cli-foo.ts",
+   "bar.src": "./src/cli-bar.ts"
+ }
}
```

```json
{
  "name": "my-cli",
  "version": "0.0.0",
  "type": "module",
  "bin": {
    "foo": "./dist/cli-foo.js",
    "foo.src": "./src/cli-foo.ts",
    "bar": "./dist/cli-bar.js",
    "bar.src": "./src/cli-bar.ts"
  }
}
```

--------------------------------

### Build and Development Commands

Source: https://github.com/wevm/zile/blob/main/examples/basic/README.md

Use these commands to prepare the package for distribution or to establish symlinks for local development.

```sh
npm run build  # Builds and transpiles the package
npm run dev    # Create symlinks for development
```

--------------------------------

### Configure single binary

Source: https://github.com/wevm/zile/blob/main/README.md

Point the bin field to a source file to have Zile create a built binary and a .src reference.

```diff
{
  "name": "my-cli",
  "version": "0.0.0",
  "type": "module",
+ "bin": "./src/cli.ts"
}
```

```json
{
  "name": "my-cli",
  "version": "0.0.0",
  "type": "module",
  "bin": {
    "my-cli": "./dist/cli.js",
    "my-cli.src": "./src/cli.ts"
  }
}
```

--------------------------------

### Configure main entrypoint

Source: https://github.com/wevm/zile/blob/main/README.md

Specify the source file in the main field to have Zile generate exports, module, and types fields.

```diff
{
  "name": "my-pkg",
  "version": "0.0.0",
  "type": "module",
+ "main": "./src/index.ts"
}
```

```json
{
  "name": "my-pkg",
  "version": "0.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "src": "./src/index.ts",
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  }
}
```

--------------------------------

### Missing entrypoint error

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Indicates that the file specified in the main field of package.json cannot be found.

```text
Error: `./src/index.ts` does not exist on `package.json#main`
```

--------------------------------

### Define TypeError structure

Source: https://github.com/wevm/zile/blob/main/_autodocs/05-types.md

Represents a single type error found in an extracted JSDoc example.

```typescript
type TypeError = {
  /** The block the error came from, when we could map it back */
  block: Block | undefined
  
  /** 1-based line within the snippet */
  line: number | undefined
  
  /** 1-based column within the snippet */
  column: number | undefined
  
  /** TSC error message, e.g. `error TS2304: Cannot find name 'foo'.` */
  message: string
  
  /** Raw line as printed by tsc */
  raw: string
}
```

--------------------------------

### Discover and build monorepo packages

Source: https://github.com/wevm/zile/blob/main/_autodocs/03-packages.md

Demonstrates the standard workflow for finding and building packages, along with a shorthand method for direct building.

```typescript
import * as Packages from 'zile/Packages'

// 1. Discover all packages
const packages = await Packages.find({
  cwd: '/path/to/monorepo',
  includes: ['packages/*']
})

console.log(`Found ${packages.length} packages`)

// 2. Build all discovered packages
const results = await Packages.build({
  cwd: '/path/to/monorepo',
  includes: ['packages/*']
})

console.log(`Built ${results.length} packages`)
```

```typescript
// This internally calls find() and then builds each
const results = await Packages.build({
  cwd: '/path/to/monorepo',
  includes: ['packages/*']
})
```

--------------------------------

### Develop a package

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Enables rapid development by creating symlinks instead of copying files.

```bash
zile dev [--cwd <dir>] [--project <path>] [--tsgo]
```

--------------------------------

### Supported JSDoc fence formats

Source: https://github.com/wevm/zile/blob/main/_autodocs/04-examples.md

Examples of the different fenced code block formats recognized by the extraction utility.

```typescript
/**
 * Example with plain TypeScript:
 *
 * ``` ts
 * const x: number = 42
 * ```
 */

/**
 * Example with twoslash directives:
 *
 * ``` ts twoslash
 * const x: number = 42
 * // @noErrors
 * ```
 */

/**
 * Example using "typescript" keyword:
 *
 * ``` typescript
 * const x: number = 42
 * ```
 */
```

--------------------------------

### Configure and run build script

Source: https://github.com/wevm/zile/blob/main/README.md

Adds the build command to package.json and executes the Zile build process.

```diff
{
  "name": "my-pkg",
  "version": "0.0.0",
  "type": "module",
  "main": "./src/index.ts"
+ "scripts": {
+   "build": "zile"
+ },
  ...
}
```

```bash
npm run build
```

--------------------------------

### run(options: run.Options)

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Executes the Zile CLI with the provided command-line arguments. This function handles command registration, argument parsing, and execution of tasks like building, development linking, and project creation.

```APIDOC
## run(options: run.Options)

### Description
Runs the Zile CLI with the given arguments. It parses the input and executes the corresponding command (e.g., build, dev, new).

### Signature
`export async function run(options: run.Options): Promise<void>`

### Parameters
- **options** (run.Options) - Required - Configuration object containing CLI arguments.
  - **args** (string[]) - Required - Command-line arguments to parse (typically `process.argv`).

### Return Type
`Promise<void>` - Resolves when the CLI completes execution.

### Throws
- Rejects if a command fails.

### Example Usage
```typescript
import * as Cli from 'zile/Cli'

// Run the CLI with process arguments
await Cli.run({
  args: process.argv
})

// Run with specific arguments
await Cli.run({
  args: ['build', '--cwd', './packages/my-lib']
})
```
```

--------------------------------

### Apply automatic fixes to JSDoc examples

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Modifies source files to write formatted code back into JSDoc comments.

```bash
zile examples:check --fix
```

--------------------------------

### Configure main entry point

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Defines the package entry point which Zile transforms into a structured exports object during build.

```json
{
  "main": "./src/index.ts"
}
```

```json
{
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "src": "./src/index.ts",
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  }
}
```

--------------------------------

### Skip type-checking with directives

Source: https://github.com/wevm/zile/blob/main/_autodocs/04-examples.md

Use Twoslash directives to ignore errors or assert specific error codes in JSDoc examples.

```typescript
/**
 * Example with intentional errors (not type-checked):
 *
 * ``` ts twoslash
 * // @noErrors
 * const x: number = 'not a number'
 * ```
 */

/**
 * Example asserting specific errors:
 *
 * ``` ts twoslash
 * // @errors: 2322
 * const x: number = 'not a number'
 * ```
 */
```

--------------------------------

### Cli.run()

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Executes the Zile CLI with the provided options.

```APIDOC
## Cli.run(options)

### Description
Run the CLI with given arguments.

### Signature
`(options: Options) => Promise<void>`

### Parameters
- **options** (Options) - Required - Configuration object containing `args` (string[])
```

--------------------------------

### Configure CLI binaries

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Specifies executable entry points. Source entries must use the .src suffix, which Zile uses to generate the final executable path.

```json
{
  "bin": "./src/cli.ts"
}
```

```json
{
  "bin": {
    "my-package": "./dist/cli.js",
    "my-package.src": "./src/cli.ts"
  }
}
```

```json
{
  "bin": {
    "foo.src": "./src/cli-foo.ts",
    "bar.src": "./src/cli-bar.ts"
  }
}
```

```json
{
  "bin": {
    "foo": "./dist/cli-foo.js",
    "foo.src": "./src/cli-foo.ts",
    "bar": "./dist/cli-bar.js",
    "bar.src": "./src/cli-bar.ts"
  }
}
```

--------------------------------

### check.Options

Source: https://github.com/wevm/zile/blob/main/_autodocs/05-types.md

Configuration options for the Examples.check() function.

```APIDOC
## check.Options

### Description
Options for the `Examples.check()` function.

### Parameters
- **cwd** (string | undefined) - Optional - Working directory. Default: process.cwd()
- **sourceDir** (string | undefined) - Optional - Directory to scan for source files. Default: path.resolve(cwd, 'src')
- **format** (boolean | undefined) - Optional - When false, skips running snippets through oxfmt. Default: true
- **formatOptions** (FormatOptions | undefined) - Optional - Oxfmt options applied to each extracted snippet
- **project** (string | undefined) - Optional - Path to the tsconfig.json the check tsconfig should extend. Default: './tsconfig.json'
- **fix** (boolean | undefined) - Optional - When true, formatted snippets are written back into the source. Default: false
- **workDir** (string | undefined) - Optional - Scratch directory used to stage extracted examples. Default: path.resolve(cwd, '.examples')
```

--------------------------------

### zile publish:prepare

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Prepares the package for publishing by building and stripping pre-marker fields.

```APIDOC
## zile publish:prepare

### Description
Prepares the package for publishing by building and stripping pre-marker fields.

### Signature
`zile publish:prepare [--cwd <dir>]`

### Options
- **--cwd** (string) - Optional - Working directory
```

--------------------------------

### Configure package.json entrypoints

Source: https://github.com/wevm/zile/blob/main/README.md

Defines source entrypoints in package.json for Zile to remap during the build process.

```diff
{
  "name": "my-pkg",
  "version": "0.0.0",
  "type": "module",
+ "main": "./src/index.ts"
}
```

```diff

{
  "name": "my-pkg",
  "version": "0.0.0",
  "type": "module",
+ "exports": {
+   ".": "./src/index.ts",
+   "./utils": "./src/utils.ts"
+ }
}
```

```diff
{
  "name": "my-pkg",
  "version": "0.0.0",
  "type": "module",
+ "bin": "./src/cli.ts"
}
```

```diff
{
  "name": "my-pkg",
  "version": "0.0.0",
  "type": "module",
+ "bin": {
+   "foo.src": "./src/cli.ts"
+   "bar.src": "./src/cli2.ts"
+ }
}
```

--------------------------------

### View Zile CLI Help and Commands

Source: https://github.com/wevm/zile/blob/main/README.md

Displays the available commands, options, and usage patterns for the Zile CLI tool.

```sh
zile/0.0.0

Usage:
  $ zile [root]

Commands:
  [root]           
  build            Build package
  dev              Resolve package exports to source for development
  new              Create a new zile project
  publish:prepare  Prepare package for publishing
  publish:post     Post-process package after publishing

For more info, run any command with the `--help` flag:
  $ zile --help
  $ zile build --help
  $ zile dev --help
  $ zile new --help
  $ zile publish:prepare --help
  $ zile publish:post --help

Options:
  --cwd <directory>         Working directory to build 
  --includes <patterns...>  Glob patterns to include 
  --project <path>          Path to tsconfig.json file, relative to the working directory. 
  --tsgo                    Use tsgo for transpilation 
  -v, --version             Display version number 
  -h, --help                Display this message
```

--------------------------------

### Standard directory structure

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

The recommended file layout for packages using this tool.

```text
my-package/
├── src/                          # Source directory (auto-detected)
│   ├── index.ts                  # Main entry
│   └── utils.ts                  # Sub-entry
├── dist/                         # Output directory (auto-created)
│   ├── index.js                  # Built main
│   ├── index.d.ts                # Type definitions
│   ├── utils.js                  # Built sub-entry
│   └── utils.d.ts
├── package.json                  # Configuration
├── tsconfig.json                 # TypeScript config
└── node_modules/.bin/
    ├── tsc                       # TypeScript compiler
    └── tsgo                      # Optional faster compiler
```

--------------------------------

### Apply custom format options

Source: https://github.com/wevm/zile/blob/main/_autodocs/05-types.md

Demonstrates passing custom formatting options to the Examples.check() method.

```typescript
import * as Examples from 'zile/Examples'

await Examples.check({
  cwd: '.',
  format: true,
  formatOptions: {
    printWidth: 80,
    semi: true,
    singleQuote: false
  }
})
```

--------------------------------

### run.Options

Source: https://github.com/wevm/zile/blob/main/_autodocs/05-types.md

Configuration options for the Cli.run() function.

```APIDOC
## run.Options

### Description
Options for the `Cli.run()` function.

### Parameters
- **args** (string[]) - Required - Command-line arguments to parse
```

--------------------------------

### Examples.extract

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Extracts code blocks from source files.

```APIDOC
## Examples.extract(options: { file: string, source: string })

### Description
Parses a source string to extract code examples for validation.

### Parameters
- **file** (string) - Required - Absolute path to the source file
- **source** (string) - Required - The source code content
```

--------------------------------

### Configure exports entrypoints

Source: https://github.com/wevm/zile/blob/main/README.md

Define multiple entrypoints in the exports field to have Zile expand them with types and built file paths.

```diff
{
  "name": "my-pkg",
  "version": "0.0.0",
  "type": "module",
+ "exports": {
+   ".": "./src/index.ts",
+   "./utils": "./src/utils.ts"
+ }
}
```

```json
{
  "name": "my-pkg",
  "version": "0.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "src": "./src/index.ts",
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./utils": {
      "src": "./src/utils.ts",
      "types": "./dist/utils.d.ts",
      "default": "./dist/utils.js"
    }
  }
}
```

--------------------------------

### Usage of getEntries

Source: https://github.com/wevm/zile/blob/main/_autodocs/02-package.md

Demonstrates how to extract source files from a package.json object.

```typescript
import * as Package from 'zile/Package'

const pkgJson = {
  main: './src/index.ts',
  exports: {
    '.': './src/index.ts',
    './utils': './src/utils.ts'
  }
}

const entries = await Package.getEntries({
  cwd: '/path/to/package',
  pkgJson
})

console.log(entries.sources)
// ['/path/to/package/src/index.ts', '/path/to/package/src/utils.ts']
```

--------------------------------

### build(options: build.Options)

Source: https://github.com/wevm/zile/blob/main/_autodocs/02-package.md

Builds a package and generates all output artifacts based on the provided configuration options.

```APIDOC
## build(options)

### Description
Builds a package and generates all output artifacts. The process includes reading configuration, validating inputs, transpiling source files, and writing results.

### Signature
`export async function build(options: build.Options): Promise<build.ReturnType>`

### Parameters
- **options** (build.Options) - Required - Build configuration object.
  - **cwd** (string) - Optional - Working directory to build from (default: process.cwd()).
  - **link** (boolean) - Optional - Create symlinks instead of building (default: false).
  - **project** (string) - Optional - Path to tsconfig.json relative to cwd (default: './tsconfig.json').
  - **tsgo** (boolean) - Optional - Use tsgo instead of tsc for transpilation (default: false).

### Return Type
- **packageJson** (PackageJson) - The transformed package.json file.
- **tsConfig** (TsConfigJson) - The tsconfig.json used for transpilation.

### Throws
- Rejects if package.json is invalid or missing required fields.
- Rejects if any entrypoint file does not exist.
- Rejects if TypeScript compilation fails.

### Example Usage
```typescript
import * as Package from 'zile/Package'

// Basic build
const result = await Package.build({
  cwd: '/path/to/package',
})

// Development mode with symlinks
await Package.build({
  cwd: '/path/to/package',
  link: true
})
```
```

--------------------------------

### build(options: build.Options)

Source: https://github.com/wevm/zile/blob/main/_autodocs/03-packages.md

Builds all packages found in the specified working directory by discovering them via glob patterns and executing builds concurrently.

```APIDOC
## build(options: build.Options)

### Description
Builds all packages found in the given working directory. It discovers packages matching the provided patterns and invokes `Package.build()` on each, returning the results concurrently.

### Parameters
- **options** (build.Options) - Required - Build configuration options.
- **options.cwd** (string) - Optional - Working directory to search for packages (default: `process.cwd()`).
- **options.includes** (string[]) - Optional - Glob patterns to match (default: `['**', '!**/node_modules/**']`).

### Return Type
`Promise<build.ReturnType>[]` - Array of promises resolving to `Package.build()` results.

### Example Usage
```typescript
import * as Packages from 'zile/Packages'

// Build all packages in a monorepo
const results = await Packages.build({
  cwd: '/path/to/monorepo'
})
```
```

--------------------------------

### zile new

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Creates a new Zile project from the template directory.

```APIDOC
## zile new

### Description
Creates a new Zile project from the template directory.

### Signature
`zile new [--npm] [--pnpm] [--bun]`

### Options
- **--npm** (boolean) - Optional - Use npm package manager
- **--pnpm** (boolean) - Optional - Use pnpm package manager
- **--bun** (boolean) - Optional - Use bun package manager
```

--------------------------------

### Examples.extract() Return Type

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Returns an array of extracted code blocks.

```typescript
Block[]   // Array of extracted blocks
```

--------------------------------

### zile dev

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Creates symlinks instead of copying files for rapid development iteration.

```APIDOC
## zile dev

### Description
Creates symlinks instead of copying files for rapid development iteration.

### Signature
`zile dev [--cwd <dir>] [--project <path>] [--tsgo]`

### Options
- **--cwd** (string) - Optional - Working directory
- **--project** (string) - Optional - Path to tsconfig.json
- **--tsgo** (boolean) - Optional - Use tsgo instead of tsc
```

--------------------------------

### zile build

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Builds a single package at the specified working directory.

```APIDOC
## zile build

### Description
Builds a single package at the specified working directory.

### Signature
`zile build [--cwd <dir>] [--project <path>] [--check-examples] [--tsgo]`

### Options
- **--cwd** (string) - Optional - Working directory (default: current working directory)
- **--project** (string) - Optional - Path to tsconfig.json relative to cwd (default: ./tsconfig.json)
- **--check-examples** (boolean) - Optional - Typecheck JSDoc examples before building
- **--tsgo** (boolean) - Optional - Use tsgo instead of tsc for transpilation
```

--------------------------------

### Cli.run

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Executes Zile CLI commands programmatically.

```APIDOC
## Cli.run(options: { args: string[] })

### Description
Runs the Zile CLI programmatically using an array of arguments.

### Parameters
- **args** (string[]) - Required - Command line arguments
```

--------------------------------

### Examples.check() Return Type

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Return structure containing validation results and format fixes.

```typescript
{
  blocks: Block[],
  typeErrors: TypeError[],
  formatFixes: Map<Block, string>
}
```

--------------------------------

### checkInput()

Source: https://github.com/wevm/zile/blob/main/_autodocs/02-package.md

Validates the working directory structure before building, ensuring required entrypoints exist.

```APIDOC
## checkInput(options)

### Description
Validates the working directory structure before building. Throws an error if the package.json is missing required fields or if referenced entrypoint files do not exist.

### Signature
`export async function checkInput(options: checkInput.Options): Promise<checkInput.ReturnType>`

### Parameters
- **options** (checkInput.Options) - Required
  - **cwd** (string) - Optional - Working directory to check (default: process.cwd())
  - **outDir** (string) - Optional - Expected output directory (default: path.resolve(cwd, 'dist'))

### Return Type
`undefined` (Returns undefined on success, throws on failure)
```

--------------------------------

### Define package build and find options

Source: https://github.com/wevm/zile/blob/main/_autodocs/03-packages.md

Type definitions for the configuration options used in package discovery and building.

```typescript
export declare namespace build {
  type Options = find.Options
}

export declare namespace find {
  type Options = {
    /** Working directory to start searching from. @default process.cwd() */
    cwd?: string | undefined
    /** Glob patterns to include. @default ['**'] */
    includes?: string[] | undefined
  }
}
```

--------------------------------

### Enable faster transpilation with --tsgo

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Uses tsgo for transpilation; requires @typescript/native-preview version 7.0.0 or higher.

```bash
zile build --tsgo
```

--------------------------------

### Importing Zile Types

Source: https://github.com/wevm/zile/blob/main/_autodocs/README.md

Demonstrates importing types from the main entry point or specific modules.

```typescript
import type {
  PackageJson,
  TsConfigJson,
  FormatOptions
} from 'zile'
```

```typescript
import type { PackageJson } from 'zile/Package'
import type { FormatOptions } from 'zile/Examples'
```

--------------------------------

### Define Package Build Options

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Configuration interface for building a single package.

```typescript
{
  cwd?: string                    // Working directory
  link?: boolean                  // Create symlinks (dev mode)
  project?: string                // Path to tsconfig.json
  tsgo?: boolean                  // Use tsgo for transpilation
}
```

--------------------------------

### Build packages in a monorepo

Source: https://github.com/wevm/zile/blob/main/_autodocs/03-packages.md

Demonstrates building all packages, specific patterns, or applying exclusions within a monorepo.

```typescript
import * as Packages from 'zile/Packages'

// Build all packages in a monorepo
const results = await Packages.build({
  cwd: '/path/to/monorepo'
})

console.log(results.length) // Number of packages built
for (const result of results) {
  console.log(result.packageJson.name)
}

// Build specific packages matching a pattern
await Packages.build({
  cwd: '/path/to/monorepo',
  includes: ['packages/*/package.json']
})

// Build with exclusions
await Packages.build({
  cwd: '/path/to/monorepo',
  includes: ['**', '!**/node_modules/**', '!**/dist/**']
})
```

--------------------------------

### Configure monorepo package discovery

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Uses glob patterns to define which directories to include or exclude during package discovery.

```bash
zile --includes packages/* --includes tools/* --includes '!**/node_modules/**'
```

--------------------------------

### Package.build

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Builds a single package based on the provided configuration options.

```APIDOC
## Package.build(options: build.Options)

### Description
Builds a single package using the specified working directory and configuration.

### Parameters
- **cwd** (string) - Optional - Working directory
- **link** (boolean) - Optional - Create symlinks (dev mode)
- **project** (string) - Optional - Path to tsconfig.json
- **tsgo** (boolean) - Optional - Use tsgo for transpilation

### Response
- **packageJson** (object) - The parsed package.json content
- **tsConfig** (object) - The parsed tsconfig content
```

--------------------------------

### Packages.build

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Builds multiple packages within a monorepo structure.

```APIDOC
## Packages.build(options: build.Options)

### Description
Builds multiple packages based on glob patterns defined in the options.

### Parameters
- **cwd** (string) - Optional - Working directory
- **includes** (string[]) - Optional - Glob patterns for packages
- **project** (string) - Optional - Path to tsconfig.json
- **checkExamples** (boolean) - Optional - Validate examples
- **tsgo** (boolean) - Optional - Use tsgo
```

--------------------------------

### Package.build() Return Type

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Return structure for the build method.

```typescript
{
  packageJson: PackageJson,
  tsConfig: TsConfigJson
}
```

--------------------------------

### Integrate Zile into Build Process

Source: https://github.com/wevm/zile/blob/main/_autodocs/04-examples.md

Demonstrates how to invoke the check function programmatically and via CLI commands.

```typescript
// In src/internal/cli/commands.ts

if (checkExamples && !link) {
  console.log('→ Checking JSDoc examples')
  const result = await Examples.check({ cwd, format: false, project })
  if (result.typeErrors.length > 0) {
    // Print errors and exit with code 1
  }
}
```

```bash
zile build --check-examples
```

```bash
zile examples:check --fix
```

--------------------------------

### Zile CLI Commands

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Common CLI commands for building, checking, and publishing packages using Zile.

```APIDOC
## CLI Commands

### Build with Development Symlinks
`zile dev`

### Check Examples
`zile examples:check --fix`

### Build with Example Validation
`zile build --check-examples`

### Publish Workflow
`zile publish:prepare`
`npm publish`
`zile publish:post`

### Monorepo Build
`zile --includes 'packages/*' --includes '!**/node_modules/**'`
```

--------------------------------

### Define check.Options

Source: https://github.com/wevm/zile/blob/main/_autodocs/05-types.md

Configuration object for the Examples.check() function.

```typescript
type Options = {
  /** Working directory. @default process.cwd() */
  cwd?: string | undefined
  
  /** Directory to scan for source files. @default path.resolve(cwd, 'src') */
  sourceDir?: string | undefined
  
  /** When false, skips running snippets through oxfmt. @default true */
  format?: boolean | undefined
  
  /** Oxfmt options applied to each extracted snippet */
  formatOptions?: FormatOptions | undefined
  
  /** Path to the tsconfig.json the check tsconfig should extend. @default './tsconfig.json' */
  project?: string | undefined
  
  /** When true, formatted snippets are written back into the source. @default false */
  fix?: boolean | undefined
  
  /** Scratch directory used to stage extracted examples. @default path.resolve(cwd, '.examples') */
  workDir?: string | undefined
}
```

--------------------------------

### Packages Module

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Functions for workspace package discovery and building.

```APIDOC
## Packages.build(options)

### Description
Build all discovered packages.

### Parameters
- **cwd** (string) - Optional - Working directory (default: process.cwd())
- **includes** (string[]) - Optional - Glob patterns (default: ['**', '!**/node_modules/**'])

## Packages.find(options)

### Description
Find all packages in workspace.

### Parameters
- **cwd** (string) - Optional - Working directory (default: process.cwd())
- **includes** (string[]) - Optional - Glob patterns (default: ['**', '!**/node_modules/**'])
```

--------------------------------

### Package.transpile

Source: https://github.com/wevm/zile/blob/main/_autodocs/05-types.md

Transpiles code by merging user-provided configuration with Zile's internal overrides.

```APIDOC
## Package.transpile

### Description
Performs transpilation by merging the user's `tsconfig.json` settings with Zile's mandatory overrides (e.g., `target: 'es2022'`, `esModuleInterop: true`). It validates that `module` and `moduleResolution` are set to `nodenext`.
```

--------------------------------

### Run CLI function signature

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

The primary entry point for executing the Zile CLI.

```typescript
export async function run(options: run.Options): Promise<void>
```

--------------------------------

### Define build.Options interface

Source: https://github.com/wevm/zile/blob/main/_autodocs/05-types.md

Configuration options for the Package.build function, including working directory and transpilation settings.

```typescript
type Options = {
  /** Working directory to start searching from. @default process.cwd() */
  cwd?: string | undefined
  
  /** Whether to link output files to source files for development. @default false */
  link?: boolean | undefined
  
  /** Path to tsconfig.json file, relative to the working directory. @default './tsconfig.json' */
  project?: string | undefined
  
  /** Whether to use tsgo for transpilation. @default false */
  tsgo?: boolean | undefined
}
```

--------------------------------

### Build Single Package

Source: https://github.com/wevm/zile/blob/main/_autodocs/07-api-summary.md

Builds a single package using the specified configuration.

```typescript
import * as Package from 'zile/Package'

const result = await Package.build({
  cwd: './my-lib',
  link: false,
  project: './tsconfig.json'
})

console.log(result.packageJson)
console.log(result.tsConfig)
```

--------------------------------

### Post-publish cleanup

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Restores the original package.json file after a publish operation.

```bash
zile publish:post [--cwd <dir>]
```

--------------------------------

### Build all packages in monorepo

Source: https://github.com/wevm/zile/blob/main/_autodocs/06-configuration.md

Builds all packages matching the provided glob pattern.

```bash
zile --includes 'packages/*'
```

--------------------------------

### zile publish:post

Source: https://github.com/wevm/zile/blob/main/_autodocs/01-cli.md

Restores the original package.json after publishing.

```APIDOC
## zile publish:post

### Description
Restores the original package.json after publishing.

### Signature
`zile publish:post [--cwd <dir>]`

### Options
- **--cwd** (string) - Optional - Working directory
```
Tokens:
Raw