BITE

bite is a CLI tool designed to transform TypeScript (.ts & .tsx) files into JavaScript using Babel while also generating TypeScript declaration files (.d.ts). It supports monorepos, watch mode, caching, and optimized TypeScript compilation.

Features

• Transforms .ts and .tsx files to .js and .jsx using Babel
• Generates TypeScript declaration files (.d.ts)
• Supports a custom Babel and TypeScript configuration
• Watch mode for automatic re-transpilation on file changes
• Cleans the output directory before transpiling (optional)
• Works seamlessly within a monorepo setup
• Lightweight and fast with debounced file watching
• Includes a "witty" mode for fun logging messages

Installation

npm install @smallcase/bite

Usage

Basic Command

bite-tsx-transform --src ./lib --dist ./dist

Options

Option	Alias	Type	Description	Required
--src		string	Path to the source directory (default: src/)	❌ No
--dist		string	Path to the output directory (default: dist/)	❌ No
--watch	-w	boolean	Enables watch mode	❌ No
--clean		boolean	Cleans the output directory before transpiling	❌ No
--tsConfig		string	Path to custom tsconfig.json	❌ No
--babelConfig		string	Path to custom babel.config.json	❌ No
--version		boolean	Show CLI version	❌ No
--witty		boolean	Enables witty logging messages	❌ No

Examples

Transform TypeScript Files

bite-tsx-transform  --src ./src --dist ./build

Transform and Watch for Changes

bite-tsx-transform  --src ./src --dist ./build --watch

Clean Output Directory Before Transpiling

bite-tsx-transform --src ./src --dist ./build --clean

Use Custom TypeScript Config

bite-tsx-transform  --src ./lib --dist ./build --tsConfig ./tsconfig.custom.json

Use Custom Babel Config

bite-tsx-transform --src ./lib --dist ./build --babelConfig ./babel.custom.json

Enable Witty Logging

bite-tsx-transform  --src ./lib --dist ./build --witty

Workspace-root ambient declarations

Bite walks up from the source directory looking for a workspace-root marker (lerna.json, pnpm-workspace.yaml, or a package.json with a workspaces field). If one is found, any *.d.ts files sitting at that root (e.g. module.d.ts declaring *.module.css, *.svg, *.png, etc.) are automatically included in every package's TypeScript program.

This means a single root-level module.d.ts covers every package in the workspace — you don't need to symlink it into each packages/*/src/. Package-local *.d.ts files (under each package's src/) are still picked up as before; the two sets are merged in the program (TS treats declare module blocks additively). Files are deduped by realpath, so a symlink-into-src/ of the same root file doesn't enter the program twice.

Excluded source files

Bite skips a few classes of source files entirely — they are neither transpiled to dist/ nor included in the TypeScript program:

• *.stories.{ts,tsx,js,jsx,mjs,cjs}
• *.test.{ts,tsx,js,jsx,mjs,cjs}
• *.spec.{ts,tsx,js,jsx,mjs,cjs}
• anything inside a __tests__/ directory
• anything inside a __snapshots__/ directory

These are dev-only files that consumers of the published package should never import. Excluding them keeps dist/ clean and prevents a recurring footgun: stories or tests that import the package's own public name (e.g. import { Foo } from '@smallcase/components' from inside the components package) drag the package's own dist/*.d.ts back into the TypeScript program through workspace symlinks, producing TS5055 emit failures or noisy diagnostics.

Watch Mode

When using --watch, the CLI monitors the source directory and processes changes incrementally — per file:

• On edit (change) of a .ts/.tsx, only that file is re-transpiled via Babel and written to dist/. A persistent ts.createWatchProgram instance re-emits the corresponding .d.ts (and .d.ts.map) for just the files it considers affected.
• On add of a .ts/.tsx, the file is transpiled and TypeScript's watch program is updated with the new root file.
• On delete (unlink) of a .ts/.tsx, the matching .jsx/.js, .d.ts, and .d.ts.map artifacts in dist/ are removed.
• Non-TS files (assets) are copied/removed in the same way.

Type errors are logged but do not crash the watcher or wipe dist/ — fix and save to continue. If the initial (non-watch) build fails, the CLI still cleans the output directory and exits non-zero, matching the previous behavior.

Logging & Error Handling

• Uses Logger for structured logging.
• Displays errors clearly in case of transformation failure.
• Cleans the output directory if transformation fails.
• Supports an optional witty logging mode (--witty) for fun messages.

License

MIT License.

NOTE - The old command tsx-transform has been deprecated and will be removed in next major version

Incremental JavaScript-to-TypeScript migration

A source tree can contain JavaScript, TypeScript and handwritten declarations:

• .js/.jsx, .d.ts and assets are copied unchanged.
• .ts/.tsx implementations produce .js/.jsx and generated .d.ts files.
• Two sources cannot own the same output. For example, remove foo.js and its handwritten foo.d.ts when replacing them with foo.ts.

Watch mode copies declaration edits and removes deleted artifacts. Conflicting edits are reported without overwriting the last valid output; resolve the collision and save to continue. File events are batched to handle renames. Handwritten ambient declare module blocks for a migrated module must also be removed manually; Bite checks output paths, not duplicate API declarations.

Mixed-source configuration

Use a package-specific build config to extend your workspace settings:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": { "allowJs": true, "checkJs": false },
  "include": ["src/**/*"],
  "exclude": ["src/fixtures/**/*"]
}

bite-tsx-transform --src ./src --dist ./dist --tsConfig ./tsconfig.build.json

Bite parses configs with TypeScript, including JSONC, extends, relative paths, files, include and exclude. Source discovery stays inside --src and always excludes tests, stories, dependencies, .git and --dist. Imports can still bring other files into the TypeScript program, as with tsc.

With allowJs, JavaScript participates in type inference (and checking if checkJs is enabled), but only TS/TSX implementations generate declarations. Existing JS declarations are copied unchanged. Add a handwritten declaration or explicit public types if a generated API needs to reference an untyped JS module.

Precedence is Bite defaults, then user compiler options, then required build settings: CLI rootDir/outDir, declaration-only emission, declaration maps and preserved JSX. Inherited noEmit, outFile, declarationDir, incremental and composite settings cannot redirect or suppress Bite's output. Other options, including target, module, resolution and strictness, are retained. Babel configuration still controls runtime transformation; TypeScript paths do not rewrite imports.

Invalid configs and output directories that contain the source directory fail before cleanup. Restart watch mode after editing config files. Keep a separate tsc --noEmit check: normal builds retain their emit-diagnostics behavior, while watch mode reports semantic errors without exiting.