nonara/ts-patch - GitHub (2025)

Patch typescript to allow custom transformers (plugins) during build.

Plugins are specified in tsconfig.json, or provided programmatically in CompilerOptions.

Migrating from ttypescript is easy! See: Method 1: Live Compiler

Features

Patch typescript installation via on-the-fly, in-memory patching oras a persistent patch

Can patch individual libraries (see ts-patch /?)

Hook build process by transforming the Program(see: Transforming Program )

Add, remove, or modify diagnostics (see: Altering Diagnostics )

Fully compatible with legacy ttypescript projects

(new)Experimental support for ES Module based transformers

ts-patch

Features

Table of Contents

Installation

Usage

Method 1: Live Compiler

Method 2: Persistent Patch

Configuration

Plugin Options

Writing Transformers

Source Transformers

Source Transformer Entry Point

Source Transformer Example

Altering Diagnostics

Note

Program Transformers

Program Transformer Entry Point

Configuring Program Transformers

Program Transformer Example

Resources

Recommended Reading

Recommended Tools

Discussion

Advanced Options

Maintainers

Help Wanted

License

Install package

  1. ``` shell
  2. <yarn|npm|pnpm> add -D ts-patch
  3. ```

Method 1: Live Compiler

The live compiler patches on-the-fly, each time it is run.

Via commandline:Simply use tspc(instead of tsc)

With tools such as ts-node, webpack, ts-jest, etc:specify the compiler asts-patch/compiler

Method 2: Persistent Patch

Persistent patch modifies the typescript installation within the node_modules path. It requires additional configuration to remain persisted, but it carries less load time and complexity compared to the live compiler.

Install the patch

  1. ``` shell
  2. # For advanced options, see: ts-patch /?
  3. ts-patch install
  4. ```

Add preparescript (keeps patch persisted after npm install)

package.json

  1. ``` js
  2. {
  3. /* ... */
  4. "scripts": {
  5. "prepare": "ts-patchinstall-s"
  6. }
  7. }
  8. ```

tsconfig.json: Add transformers to compilerOptionsin pluginsarray.

Examples

  1. ``` js
  2. {
  3. "compilerOptions": {
  4. "plugins": [
  5. // Source Transformers
  6. { "transform": "transformer-module" },
  7. { "transform": "transformer2", "extraOption": 123 },
  8. { "transform": "trans-with-mapping", "resolvePathAliases": true },
  9. { "transform": "esm-transformer,"isEsm":true},

  10. // Program Transformer
  11. { "transform": "transformer-module5", "transformProgram": true }
  12. ]
  13. }
  14. }
  15. ```

Plugin Options

| Option | Type | Description |

| :--- | :--- | :--- |

| transform| string| Module name or path to transformer (.ts or .js) |

| after| boolean| Apply transformer after stock TS transformers |

| afterDeclarations| boolean| Apply transformer to declaration (*.d.ts) files |

| transformProgram| boolean| Transform Program during ts.createProgram() (see: Program Transformers) |

| isEsm| boolean| Transformer is ES Module (note: experimental — requires esm) |

| resolvePathAliases| boolean| Resolve path aliases in transformer (requires tsconfig-paths) |

| type| string| See: Source Transformer Entry Point (default: 'program') |

| import| string| Name of exported transformer function (defaults to default export) |

| tsConfig| string| tsconfig.json file for transformer (allows specifying compileOptions, path mapping support, etc) |

| ...| | Provide your own custom options, which will be passed to the transformer |

Note: Required options are bold

Source Transformers

Source Transformers will transform the AST of SourceFiles during compilation, allowing you to alter the output of the JS or declarations files.

Source Transformer Entry Point

  1. ``` ts
  2. (program: ts.Program, config: PluginConfig, extras: TransformerExtras) => ts.TransformerFactory
  3. ```

PluginConfig: Type Declaration TransformerExtras: Type Declaration ts.TransformerFactory: (context: ts.TransformationContext) => (sourceFile: ts.SourceFile) => ts.SourceFile

Note: Additional legacy signatures are supported, but it is not recommended to develop a new transformer using them.

Source Transformer Example

Transformers can be written in JS or TS.

  1. ``` ts
  2. import type * as ts from 'typescript';
  3. import type { TransformerExtras, PluginConfig } from 'ts-patch';

  4. /** Changes string literal 'before' to 'after' */
  5. export default function (program: ts.Program, pluginConfig: PluginConfig, { ts: tsInstance }: TransformerExtras) {
  6. return (ctx: ts.TransformationContext) => {
  7. const { factory } = ctx;

  8. return (sourceFile: ts.SourceFile) => {
  9. function visit(node: ts.Node): ts.Node {
  10. if (tsInstance.isStringLiteral(node) && node.text === 'before') {
  11. return factory.createStringLiteral('after');
  12. }
  13. return tsInstance.visitEachChild(node, visit, ctx);
  14. }
  15. return tsInstance.visitNode(sourceFile, visit);
  16. };
  17. };
  18. }
  19. ```

Live Examples:

{ transform: "typescript-transform-paths" }

{ transform: "typescript-is/lib/transform-inline/transformer" }

{ transform: "typia/lib/transform" } (💻playground )

{ transform: "@nestia/core/lib/transform" }

Altering Diagnostics

Diagnostics can be altered in a Source Transformer.

To alter diagnostics you can use the following, provided from the TransformerExtrasparameter:

| property | description |

| :--- | :--- |

| diagnostics| Reference to Diagnostic array |

| addDiagnostic()| Safely add Diagnostic to diagnostics array |

| removeDiagnostic()| Safely remove Diagnostic from diagnostics array |

Note

This alters diagnostics during emit only. If you want to alter diagnostics in your IDE as well, you'll need to create a LanguageService plugin to accompany your source transformer

Program Transformers

Sometimes you want to do more than just transform source code. For example you may want to:

TypeCheck code after it's been transformed

Generate code and add it to the program

Add or remove emit files during transformation

For this, we've introduced what we call a Program Transformer. The transform action takes place during ts.createProgram, and allows re-creating the Programinstance that typescript uses.

Program Transformer Entry Point

  1. ``` ts
  2. (program: ts.Program, host: ts.CompilerHost | undefined, options: PluginConfig, extras: ProgramTransformerExtras) => ts.Program
  3. ```

ProgramTransformerExtras>>> Type Declaration

Configuring Program Transformers

To configure a Program Transformer, supply "transformProgram": truein the config transformer entry.

Note: The before, after, and afterDeclarationsoptions do not apply to a Program Transformer and will be ignored

See Config Example

Program Transformer Example

  1. ``` ts
  2. /**
  3. * Add a file to Program
  4. */
  5. import * as path from 'path';
  6. import type * as ts from 'typescript';
  7. import type { ProgramTransformerExtras, PluginConfig } from 'ts-patch';

  8. export const newFile = path.resolve(__dirname, 'added-file.ts');

  9. export default function (
  10. program: ts.Program,
  11. host: ts.CompilerHost | undefined,
  12. options: PluginConfig,
  13. { ts: tsInstance }: ProgramTransformerExtras
  14. ) {
  15. return tsInstance.createProgram(
  16. /* rootNames */ program.getRootFileNames().concat([ newFile ]),
  17. program.getCompilerOptions(),
  18. host,
  19. /* oldProgram */ program
  20. );
  21. }
  22. ```

Note:For a more complete example, see Transforming Program with additional AST transformations

Live Examples:

{ transform: "@typescript-virtual-barrel/compiler-plugin", transformProgram: true }

Resources

Recommended Reading

How-To: Advice for working with the TS Compiler API

How-To: TypeScript Transformer Handbook

Article: How to Write a TypeScript Transform (Plugin)

Article: Creating a TypeScript Transformer

Recommended Tools

| Tool | Type | Description |

| :--- | :--- | :--- |

| TS AST Viewer| Web App| Allows you to see the Node structure and other TS properties of your source code. |

| ts-expose-internals| NPM Package| Exposes internal types and methods of the TS compiler API |

Discussion

#compiler-internals-and-apion TypeScript Discord Server

TSP Discussions Board

(env) TSP_SKIP_CACHE

Skips patch cache when patching via cli or live compiler.

(env) TSP_COMPILER_TS_PATH

Specify typescript library path to use for ts-patch/compiler(defaults to require.resolve('typescript'))

(env) TSP_CACHE_DIR

Override patch cache directory

(cli) ts-patch clear-cache

Cleans patch cache & lockfiles

| |

| :--- |

| nonara/ts-patch - GitHub (1)Ron S.|

Help Wanted

If you're interested in helping and have a high levelof skill with the TS compiler API, please reach out!

This project is licensed under the MIT License, as described in LICENSE.md

nonara/ts-patch - GitHub (2025)
Top Articles
Latest Posts
Recommended Articles
Article information

Author: Cheryll Lueilwitz

Last Updated:

Views: 6464

Rating: 4.3 / 5 (74 voted)

Reviews: 81% of readers found this page helpful

Author information

Name: Cheryll Lueilwitz

Birthday: 1997-12-23

Address: 4653 O'Kon Hill, Lake Juanstad, AR 65469

Phone: +494124489301

Job: Marketing Representative

Hobby: Reading, Ice skating, Foraging, BASE jumping, Hiking, Skateboarding, Kayaking

Introduction: My name is Cheryll Lueilwitz, I am a sparkling, clean, super, lucky, joyous, outstanding, lucky person who loves writing and wants to share my knowledge and understanding with you.