Repository files navigation

Opinionated build tool for TypeScript libraries, powered bytsc (ortsgo!).

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

Zile is an opinionated zero-config tool for transpiling TypeScript libraries based on yourpackage.json file, powered bytsc.

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

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

npm i zile typescript -D

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

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

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

Themain entry will be remapped to the built file in your output when you runzile.

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

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

Theexports will be remapped to the built files in your output when you runzile.

A binary entrypoint can be specified as thebin 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 thebin 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. Thebin will be remapped to the built file in your output when you runzile.

Add abuild script to yourpackage.json file, and run it withnpm run build.

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

npm run build

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

Themain 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 generatesexports,module andtypes 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"    }  }}

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

Thebin field specifies CLI entrypoints for your package.

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

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

Zile also sets these fields if not already present:

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

Sincetsc is used under the hood, Zile also uses fields in yourtsconfig.json file to determine the output directory and particular settings for transpilation.

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

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

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

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

zile/0.0.0Usage:  $ zile [root]Commands:  [root]    build   Build package  dev     Resolve package exports tosourcefor developmentFor more info, run anycommand with the`--help` flag:  $ zile --help  $ zile build --help  $ zile dev --helpOptions:  --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 tsgofor transpilation   -v, --version             Display version number   -h, --help                Display this message

MIT License.