Awesome
Deprecation Notice
ttypescript
is deprecated. It currently works with TS below 5.0, but it will not be updated.
For TypeScript 5+, please use ts-patch.
ttypescript
What it is
Currently TypeScript doesn't support custom transformers in the tsconfig.json, but supports it programmatically.
And there is no way to compile your files using custom transformers using tsc
command.
TTypescript (Transformer TypeScript) solves this problem by patching on the fly the compile module to use transformers from tsconfig.json
.
Instead of tsc and tsserver, use ttsc and ttsserver wrappers. This wrappers try to use locally installed typescript first.
No version lock-ins - typescript used as peer dependency.
How to install
npm i ttypescript -D
ttypescript uses your installed typescript
in your node_modules
How to use
tsconfig.json
Set a transformer path to the tsconfig.json
in compilerOptions
section plugin
array:
{
"compilerOptions": {
"plugins": [
{ "transform": "transformer-module" },
]
}
}
plugin entries described in PluginConfig
:
export interface PluginConfig {
/**
* Path to transformer or transformer module name
*/
transform?: string;
/**
* The optional name of the exported transform plugin in the transform module.
*/
import?: string;
/**
* Plugin entry point format type, default is program
*/
type?: 'program' | 'config' | 'checker' | 'raw' | 'compilerOptions';
/**
* Should transformer applied after all ones
*/
after?: boolean;
/**
* Should transformer applied for d.ts files, supports from TS2.9
*/
afterDeclarations?: boolean;
/**
* any other properties provided to the transformer as config argument
* */
[options: string]: any;
}
You just need to add the transform
block with optional import
, type
, after
, afterDeclarations
and plugin-related options.
transform
can accept npm module or local file path (.ts or .js) related to tsconfig.json
PluginConfig.type
Because currently transformers can run only programmatically, most of them use factory wrapper with different signatures.
For the possible to work with any of them you can specify type
in the plugin config.
By default will be used a program
type.
program
If the transformer has a factory signature using program
as first argument:
(program: ts.Program, config?: PluginConfig) => ts.TransformerFactory
where
ts.TransformerFactory = (context: ts.TransformationContext) => (sourceFile: ts.SourceFile) => ts.SourceFile
Plugin config entry: { "transform": "transformer-module" }
.
config
For the signature with transformer's config:
(config: PluginConfig) => ts.TransformerFactory
Plugin config entry: { "transform": "transformer-module", type: "config" }
.
checker
For the signature with ts.TypeChecker:
(checker: ts.TypeChecker, config?: PluginConfig) => ts.TransformerFactory
Plugin config entry: { "transform": "transformer-module", type: "checker" }
.
raw
For the signature without factory wrapper:
ts.TransformerFactory
Plugin config entry: { "transform": "transformer-module", type: "raw" }
.
compilerOptions
(compilerOpts: ts.CompilerOptions, config?: PluginConfig) => ts.TransformerFactory
Plugin config entry: { "transform": "transformer-module", type: "compilerOptions" }
.
{
"compilerOptions": {
"plugins": [
{ "transform": "transformer-module", "someOption1": 123, "someOption2": 321 },
{ "transform": "./transformers/my-transformer.ts" },
{ "transform": "transformer-module", "after": true },
{ "transform": "transformer-module", "afterDeclarations": true },
{ "transform": "transformer-module", "type": "ls" }
]
},
}
Command line
Like usual tsc
, all arguments work the same way.
ttsc
ts-node
ts-node --compiler ttypescript index.ts
or
ts-node -C ttypescript index.ts
Parcel
Just install a parcel plugin
npm i parcel-plugin-ttypescript
Webpack
{
test: /\.(ts|tsx)$/,
loader: require.resolve('awesome-typescript-loader'),
// or
loader: require.resolve('ts-loader'),
options: {
compiler: 'ttypescript'
}
}
Rollup
// rollup.config.js
import ttypescript from 'ttypescript'
import tsPlugin from 'rollup-plugin-typescript2'
export default {
// ...
plugins: [
// ...
tsPlugin({
typescript: ttypescript
})
]
}
VS Code
If you want to compile your project with VS Code task runner you need to overwrite the config typescript.tsdk
to path of the installed ttypescript
:
"typescript.tsdk": "/usr/local/lib/node_modules/ttypescript/lib",
or
"typescript.tsdk": "node_modules/ttypescript/lib",
Jest, ts-jest
module.exports = {
// [...]
globals: {
'ts-jest': {
compiler: 'ttypescript'
}
}
};
or in package.json
{
"jest": {
"globals": {
"ts-jest": {
"compiler": "ttypescript"
}
}
}
}
Transformers
You can use transformers written in ts or js
// transformer1-module
import * as ts from 'typescript';
export default function(program: ts.Program, pluginOptions: {}) {
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);
};
};
}
Examples of transformers:
{ "transform": "ts-nameof", type: "raw"}
{ "transform": "ts-optchain/transform" }
{ "transform": "ts-transform-asset" }
{ "transform": "ts-transform-auto-require" }
{ "transform": "ts-transform-css-modules/dist/transform", type: "config" }
{ "transform": "ts-transform-graphql-tag/dist/transformer" }
{ "transform": "ts-transform-img/dist/transform", type: "config" }
{ "transform": "ts-transform-react-intl/dist/transform", import: "transform", type: "config" }
{ "transform": "ts-transformer-enumerate/transformer" }
{ "transform": "ts-transformer-keys/transformer" }
{ "transform": "ts-transformer-minify-privates" }
{ "transform": "typescript-is/lib/transform-inline/transformer" }
{ "transform": "typescript-plugin-styled-components", type: "config" }
{ "transform": "typescript-transform-jsx" }
{ "transform": "typescript-transform-macros" }
{ "transform": "typescript-transform-paths" }
{ "transform": "@zerollup/ts-transform-paths" }
{ "transform": "@zoltu/typescript-transformer-append-js-extension" }
{ "transform": "@magic-works/ttypescript-browser-like-import-transformer" }
{ "transform": "typescript-transform-react-jsx-source" }
{ "transform": "ts-transformer-remove-named-export" }
{ "transform": "ts-transformer-export-default-name" }
{ "transform": "ts-transformer-inline-file/transformer" }
{ "transform": "ts-transformer-strip-const-enums", "entrySourceFiles": ["./src/index.ts" }
{ "transform": "ts-transformer-properties-rename", "entrySourceFiles": ["./src/index.ts"] }
{ "transform": "tsc-progress", "name": "TSC", "color": "green" }
Tutorial how to write a typescript transformer
- Tutorial how to write a typescript transformer
- Transformer framework
- Unit testing transformer compiler
Example
An example project is in the example directory
License
MIT License