What is ts-patch?
ts-patch is a tool that allows you to patch the TypeScript compiler (tsc) to enable custom transformers and other advanced features. It is particularly useful for developers who need to extend the capabilities of TypeScript beyond what is natively supported.
What are ts-patch's main functionalities?
Custom Transformers
This feature allows you to apply custom transformers to the TypeScript compiler. By patching the compiler, you can specify custom transformers in your tsconfig.json file, enabling advanced code transformations during the compilation process.
const { patch, unpatch } = require('ts-patch');
// Apply the patch
patch();
// Now you can use custom transformers in your tsconfig.json
// tsconfig.json
{
"compilerOptions": {
"plugins": [
{ "transform": "./path/to/your/transformer" }
]
}
}
// Unpatch when done
unpatch();
Advanced Compiler Options
This feature allows you to enable advanced compiler options that are not natively supported by TypeScript. By patching the compiler, you can use options like experimental decorators and emit decorator metadata.
const { patch, unpatch } = require('ts-patch');
// Apply the patch
patch();
// Now you can use advanced compiler options in your tsconfig.json
// tsconfig.json
{
"compilerOptions": {
"experimentalDecorators": true,
"emitDecoratorMetadata": true
}
}
// Unpatch when done
unpatch();
Integration with Build Tools
This feature allows you to integrate ts-patch with various build tools like Webpack. By patching the TypeScript compiler, you can use custom transformers and advanced compiler options in your build process.
const { patch, unpatch } = require('ts-patch');
// Apply the patch
patch();
// Now you can integrate ts-patch with build tools like Webpack
// webpack.config.js
const path = require('path');
module.exports = {
entry: './src/index.ts',
module: {
rules: [
{
test: /\.tsx?$/,
use: 'ts-loader',
exclude: /node_modules/
}
]
},
resolve: {
extensions: ['.tsx', '.ts', '.js']
},
output: {
filename: 'bundle.js',
path: path.resolve(__dirname, 'dist')
}
};
// Unpatch when done
unpatch();
Other packages similar to ts-patch
ttypescript
ttypescript is a fork of the TypeScript compiler that allows you to use custom transformers directly in your tsconfig.json. It is similar to ts-patch in that it enables advanced TypeScript features, but it requires you to use a different compiler binary.
babel-plugin-transform-typescript-metadata
babel-plugin-transform-typescript-metadata is a Babel plugin that adds support for TypeScript metadata reflection. While it doesn't patch the TypeScript compiler, it provides similar functionality by enabling advanced TypeScript features through Babel.
typescript-transform-paths
typescript-transform-paths is a TypeScript transformer that rewrites module paths based on the paths specified in tsconfig.json. It is similar to ts-patch in that it allows for custom transformations, but it focuses specifically on module path rewriting.
ts-patch
Directly patch typescript installation to allow custom transformers (plugins).
- Plugins are specified in
tsconfig.json
, or provided programmatically in CompilerOptions
. - (New) Supports 'transforming' the
Program
instance prior to emit. (see: Program Transformers) - Logic based on ttypescript - 100% compatibility with
ttypescript
configuration + transformers.
Features
- Easy to patch or unpatch any version of typescript (2.7+)
- One step setup - no complicated install process
- Optionally, enable persistence, which re-patches typescript automatically if it is updated
- Advanced options for patching individual files, specific locations, etc. (see
ts-patch /?
) - Can transform
Program
instance used for emit
Installation
npm i ts-patch -D
Usage
ts-patch install
For more options, use: ts-patch /?
Table of Contents
Configuring
tsconfig.json
Add transformers to compilerOptions
in plugin
array:
{
"compilerOptions": {
"plugins": [
{ "transform": "transformer-module" }
]
}
}
Plugin Options
Option | Description |
---|
transform | Module name or path to transformer (*.ts or *.js) |
type | Plugin entry point format (see: Type Signatures) |
import | Name of exported transformer function (defaults to default export) |
after | Apply transformer after stock TS transformers. |
afterDeclarations | Apply transformer to declaration (*.d.ts) files (TypeScript 2.9+). |
beforeEmit | Transform Program before program.emit() is called (see: Program Transformers) |
... | Provide your own custom options, which will be passed to the transformer |
Note: Required options are bold
Type Signatures
ts.TransformerFactory
>>> (context: ts.TransformationContext) => (sourceFile: ts.SourceFile) => ts.SourceFile
program (default)
Signature with ts.Program
instance:
(program: ts.Program, config: PluginConfig | undefined) => ts.TransformerFactory
config
Signature with transformer's config:
(config: PluginConfig) => ts.TransformerFactory
checker
Signature with ts.TypeChecker
:
(checker: ts.TypeChecker, config?: PluginConfig) => ts.TransformerFactory
raw
Signature without ts-patch
wrapper:
(context: ts.TransformationContext) => (sourceFile: ts.SourceFile) => ts.SourceFile
compilerOptions
(compilerOpts: ts.CompilerOptions, config?: PluginConfig) => ts.TransformerFactory
Examples
{
"compilerOptions": {
"plugins": [
{ "transform": "transformer-module", "someOption1": 123, "someOption2": 321 },
{ "transform": "./transformers/my-transformer.ts", "type": "program" },
{ "transform": "transformer-module1", "type": "config", "after": true },
{ "transform": "transformer-module2", "type": "checker", "afterDeclarations": true },
{ "transform": "transformer-module3", "type": "raw" },
{ "transform": "transformer-module4", "type": "compilerOptions", "beforeEmit": true },
{ "transform": "transformer-module4", "beforeEmit": true }
]
}
}
Node Transformers
Transformers can be written in JS or TS.
import * as ts from 'typescript';
export default function(program: ts.Program, pluginOptions: any) {
return (ctx: ts.TransformationContext) => {
return (sourceFile: ts.SourceFile) => {
function visitor(node: ts.Node): ts.Node {
return ts.visitEachChild(node, visitor, ctx);
}
return ts.visitEachChild(sourceFile, visitor, ctx);
};
};
}
Example Node Transformers
{ transform: "typescript-is/lib/transform-inline/transformer" }
{ transform: "ts-transformer-keys/transformer" }
{ transform: "ts-transformer-enumerate/transformer" }
{ transform: "ts-transform-graphql-tag/dist/transformer" }
{ transform: "ts-transform-img/dist/transform", type: "config" }
{ transform: "ts-transform-css-modules/dist/transform", type: "config" }
{ transform: "ts-transform-react-intl/dist/transform", import: "transform", type: "config" }
{ transform: "ts-nameof", type: "raw" }
{ transform: "typescript-transform-jsx" }
{ transform: "typescript-transform-paths" }
{ transform: "typescript-transform-macros" }
{ transform: "ts-transformer-minify-privates" }
{ transform: "typescript-plugin-styled-components", type: "config" }
Program Transformers
There are some cases where a transformer isn't enough. Some of the biggest examples are if you're trying to:
- TypeCheck code after it's been transformed
- Add or remove emit files during transformation
In order to do this, you'd normally have to create a custom build tool which manually creates Program
and manipulates
or re-creates it as you need.
The good news is, you can now integrate this into standard tsc behaviour via a beforeEmit
plugin.
Signature
There is only one possible signature for a Program transformer.
(program: ts.Program, host?: ts.CompilerHost, options?: PluginConfig) => ts.Program
Example Program Transformer
import * as ts from 'typescript';
import * as path from 'path';
export const newFile = path.resolve(__dirname, 'added-file.ts');
export default function (program: ts.Program, host?: ts.CompilerHost) {
return ts.createProgram(
program.getRootFileNames().concat([ newFile ]),
program.getCompilerOptions(),
host,
program
);
}
Notes
A Program transformer is not a Node Transformer. This means the following options will not apply when beforeEmit: true
is specified:
Resources
Recommended Reading
Recommended Tools
Tool | Type | Description |
---|
TS AST Viewer | Website | Allows you to see the Node structure of any TS/JS source, including Flags, Type , and Symbol . This is the go-to tool for all things TypeScript AST. |
ts-query | NPM Module | Perform fast CSS-like queries on AST to find specific nodes (by attribute, kind, name, etc) |
ts-query Playground | Website | Test ts-query in realtime |
Credit
HALP!!!
- If you're new to this sort of thing, please be sure to go through the Recommended Reading.
- A good place to ask questions is StackOverflow (with the
#typescript-compiler-api
tag) - Read the handbook and still stuck? Ask in Issues, and I or someone else may help when they have some time!
License
This project is licensed under the MIT License