Table of Contents

• Overview
• Getting Started
• package.json Reference
• tsconfig.json Reference
• CLI Reference
• License

Overview

Zile is an opinionated zero-config tool for transpiling TypeScript libraries based on your package.json file, powered by tsc.

• Zero-config: No config files or specific config to get started – relies on standard package.json fields
• ESM-only: Builds libraries with pure-ESM output
• Development mode: zile dev creates symlinks for rapid development without full transpilation
• Support for tsgo: Use tsgo for faster transpilation
• Binary/CLI Support: Supports CLI tools with automatic handling of package.json#bin
• Auto-generated package.json: Zile will auto-generate a valid package.json file to distribute to package registries

Getting Started

1. Install

Install Zile as a dev dependency on your project, and ensure that typescript is also installed.

npm i zile typescript -D

2. Add Entrypoints

Zile does not require specific configuration. However, it does require a few fields in your package.json file to be present depending if you have a single or multiple entrypoints.

Single Entrypoint

A single entrypoint can be specified as the main field pointing to your source file.

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

The main entry will be remapped to the built file in your output when you run zile.

Multiple Entrypoints

Multiple entrypoints can be specified as the exports field pointing to your source files.

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

The exports will be remapped to the built files in your output when you run zile.

Binary/CLI Entrypoint(s)

A binary entrypoint can be specified as the bin field pointing to your source file.

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

Or if you want to specify a custom name for the binary, or multiple binary entrypoints, you can use the bin field as an object.

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

Make sure you add a .src suffix and the value is pointing to your source file. The bin will be remapped to the built file in your output when you run zile.

3. Run Zile

Add a build script to your package.json file, and run it with npm run build.

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

npm run build

package.json Reference

This section describes how Zile transforms your package.json fields during the build process.

main

The main field specifies a single entrypoint for your package.

Point to your source file:

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

↓↓↓ Output

Zile transforms this to point to the built file and generates exports, module and types fields:

{
  "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"
    }
  }
}

exports

The exports field enables you to specify multiple (or single) entrypoints for your package.

Point to your source files directly:

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

↓↓↓ Output

Zile expands each entrypoint to include types and built files:

{
  "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"
    }
  }
}

bin

The bin field specifies CLI entrypoints for your package.

String Format (Single Binary)

Point to your source file:

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

↓↓↓ Output

Zile creates both the built binary and preserves a .src reference:

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

Object Format (Multiple Binaries)

Use keys with .src suffix to indicate source files:

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

↓↓↓ Output

Zile creates built versions without the .src suffix:

{
  "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"
  }
}

Additional Fields

Zile also sets these fields if not already present:

• type: Set to "module" (ESM-only)
• sideEffects: Set to false

[!start-pkg]

The [!start-pkg] comment marker allows you to control which fields from your package.json are included when publishing.

When using zile publish:prepare, only fields that appear after the [!start-pkg] comment will be picked for the published package. This is useful for excluding development-only fields (like devDependencies, scripts, or workspace configurations) from the published package.

Example

{
  "scripts": {
    "build": "zile build",
    "publish": "zile publish:prepare && npm publish && zile publish:post",
    "test": "vitest"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  },
+ "[!start-pkg]": "",
  "name": "my-pkg",
  "version": "0.0.0",
  "type": "module",
  "main": "./src/index.ts",
  "dependencies": {
    "some-lib": "^1.0.0"
  }
}

In this example, when running zile publish:prepare, only the fields after [!start-pkg] (type, main, and dependencies) will be included in the published package. The scripts and devDependencies will be excluded.

tsconfig.json Reference

Since tsc is used under the hood, Zile also uses fields in your tsconfig.json file to determine the output directory and particular settings for transpilation.

Any field in the tsconfig.json can be modified, and the following fields are worth noting:

• outDir: Output directory. Defaults to ./dist
• target: Target ES version. Defaults to es2021

The following fields cannot be modified, and are overridden by Zile:

• composite: Set to false to disable project references and incremental compilation, and allow for purity.
• declaration: Set to true as we always want to emit declaration files.
• declarationMap: Set to true to emit source maps for declaration files.
• emitDeclarationOnly: Set to false to force emitting built files.
• esModuleInterop: Set to true to enable interoperability between CommonJS and ES modules.
• noEmit: Set to false to force emitting built files.
• skipLibCheck: Set to true to skip type checking of external libraries.
• sourceMap: Set to true to emit source maps.

CLI Reference

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 

License

MIT License.