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.
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();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 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 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.
Directly patch typescript installation to allow custom transformers (plugins).
tsconfig.json, or provided programmatically in CompilerOptions.ttypescript configuration + transformers.ts-patch /?)Program instance during creation. (see: Transforming Program)$ npm i ts-patch -D
$ ts-patch install
For more options, use: ts-patch /?
Add transformers to compilerOptions in plugin array:
{
"compilerOptions": {
"plugins": [
{ "transform": "transformer-module" }
]
}
}
| 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+). |
| transformProgram | Transform Program before program.emit() is called (see: Transforming Program) |
| ... | Provide your own custom options, which will be passed to the transformer |
Note: Required options are bold
ts.TransformerFactory >>> (context: ts.TransformationContext) => (sourceFile: ts.SourceFile) => ts.SourceFile
TspExtras >>>
{
ts: typeof ts;
addDiagnostic: (diag: Diagnostic) => number,
removeDiagnostic: (index: number) => void,
diagnostics: readonly Diagnostic[]
}
Signature with ts.Program instance:
(program: ts.Program, config: PluginConfig | undefined, extras: TspExtras) => ts.TransformerFactory
Signature with transformer's config:
(config: PluginConfig) => ts.TransformerFactory
Signature with ts.TypeChecker:
(checker: ts.TypeChecker, config?: PluginConfig) => ts.TransformerFactory
Signature without ts-patch wrapper:
/* ts.TransformerFactory */
(context: ts.TransformationContext) => (sourceFile: ts.SourceFile) => ts.SourceFile
(compilerOpts: ts.CompilerOptions, config?: PluginConfig) => ts.TransformerFactory
{
"compilerOptions": {
"plugins": [
{ "transform": "transformer-module", "someOption1": 123, "someOption2": 321 }, // type defaults to 'program'
{ "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", "transformProgram": true },
{ "transform": "transformer-module4", "transformProgram": true } // No type specified - transformProgram has only one signature
]
}
}
Transformers can be written in JS or TS.
// transformer1-module
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 {
// if (ts.isCallExpression(node)) {
// return ts.createLiteral('call');
// }
return ts.visitEachChild(node, visitor, ctx);
}
return ts.visitEachChild(sourceFile, visitor, ctx);
};
};
}
{ 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" }
There are some cases where a transformer isn't enough. Some of the biggest examples are if you're trying to:
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.
Good news! ts-patch now supports this via a transformProgram plugin. The transform action takes place during ts.createProgram.
There is only one possible signature for a Program transformer.
(program: ts.Program, host?: ts.CompilerHost, options?: PluginConfig) => ts.Program
/**
* Add a file to Program
*/
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(
/* rootNames */ program.getRootFileNames().concat([ newFile ]),
program.getCompilerOptions(),
host,
/* oldProgram */ program
);
}
A Program transformer is not a Node Transformer. This means the following options will not apply when transformProgram: true is specified:
typebeforeafterTo alter diagnostics, use the program type signature, and use the following from the TspExtras parameter
| property | description |
|---|---|
| ts | Reference to ts instance |
| diagnostics | Reference to Diagnostic[] created during ts.emitFilesAndReportErrors() (works with tsc also) |
| addDiagnostic() | Directly add Diagnostic to diagnostics array |
| removeDiagnostic() | Directly remove Diagnostic from diagnostics array (uses splice, for safe removal) |
ts.emitFilesAndReportErrors() is used, any diagnostics added via addDiagnostic()
will still be merged into the result of program.emit() -> diagnostics| 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 |
| Author | Module |
|---|---|
| Ron S. | ts-patch |
| cevek | ttypescript |
#typescript-compiler-api tag).#compiler room on the TypeScript Discord Server.This project is licensed under the MIT License
FAQs
Patch typescript to support custom transformers in tsconfig.json
The npm package ts-patch receives a total of 94,413 weekly downloads. As such, ts-patch popularity was classified as popular.
We found that ts-patch demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.