# awesome-typescript-loader

> Awesome TS loader for webpack

Latest version **5.2.1** (published 2018-09-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install awesome-typescript-loader
pnpm add awesome-typescript-loader
yarn add awesome-typescript-loader
bun add awesome-typescript-loader
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.2.1 |
| Published | 2018-09-06 |
| First published | 2015-02-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 8 |
| Unpacked size | 398.5 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 2338 |
| Author | Stanislav Panferov |
| Maintainers | panferov-s |
| Keywords | webpack, loader, webpack-loader, typescript |

## Links

- npm: https://www.npmjs.com/package/awesome-typescript-loader
- Repository: https://github.com/s-panferov/awesome-typescript-loader
- Issues: https://github.com/s-panferov/awesome-typescript-loader/issues
- npm.io page: https://npm.io/package/awesome-typescript-loader

## Dependencies (8)

- [chalk](https://npm.io/package/chalk.md) ^2.4.1
- [lodash](https://npm.io/package/lodash.md) ^4.17.5
- [mkdirp](https://npm.io/package/mkdirp.md) ^0.5.1
- [micromatch](https://npm.io/package/micromatch.md) ^3.1.9
- [webpack-log](https://npm.io/package/webpack-log.md) ^1.2.0
- [loader-utils](https://npm.io/package/loader-utils.md) ^1.1.0
- [enhanced-resolve](https://npm.io/package/enhanced-resolve.md) ^4.0.0
- [source-map-support](https://npm.io/package/source-map-support.md) ^0.5.3

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 5.2.1 (latest) — 2018-09-06
- 4.0.0-1 (prerelease) — 2018-03-02
- 4.0.0-0 (next) — 2018-02-24
- 5.2.0 — 2018-06-21
- 5.1.1 — 2018-06-19
- 5.1.0 — 2018-06-17
- 5.0.0 — 2018-04-06
- 4.0.1 — 2018-03-08
- 5.0.0-1 — 2018-03-07
- 5.0.0-0 — 2018-03-06
- 4.0.0 — 2018-03-06
- 3.5.0 — 2018-02-24
- 3.4.1 — 2017-12-01
- 3.4.0 — 2017-11-18
- 3.4.0-0 — 2017-11-17
- … 170 more at https://npm.io/package/awesome-typescript-loader/versions

## README

# TypeScript loader for Webpack

[![Join the chat at https://gitter.im/s-panferov/awesome-typescript-loader](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/s-panferov/awesome-typescript-loader?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Build Status](https://travis-ci.org/s-panferov/awesome-typescript-loader.svg?branch=master)](https://travis-ci.org/s-panferov/awesome-typescript-loader)

See also:

1. [tygen](https://github.com/s-panferov/tygen) — TypeScript documentation generator.

## Installation

```
npm install awesome-typescript-loader --save-dev
```

## Performance issues

Please note that ATL works **the same way as a TypeScript compiler** as much as possible. So please be careful with your `files`/`exclude`/`include` sections.

**ADVICE**: Turn on `useCache` option.

**ADVICE**: Typically you want your `files` section to include only entry points.

**ADVICE**: The loader works faster if you use `isolatedModules` or `forceIsolatedModules` options.

**ADVICE**: The loader works faster if you will use `reportFiles` to restrict
checking scope.

**ADVICE**: Use the loader together with [hard-source-webpack-plugin](https://github.com/mzgoddard/hard-source-webpack-plugin)

The world is changing, other solutions are evolving and ATL may work **slower**
for [some workloads](https://github.com/s-panferov/awesome-typescript-loader/issues/497). Feel free to try [`ts-loader`](https://github.com/TypeStrong/ts-loader) with [`HappyPack` ](https://github.com/amireh/happypack) or [`thread-loader`](https://webpack.js.org/loaders/thread-loader/) and [hard-source-webpack-plugin](https://github.com/mzgoddard/hard-source-webpack-plugin).

## Differences between [`ts-loader`](https://github.com/TypeStrong/ts-loader)

`awesome-typescript-loader` loader was created mostly to speed-up compilation in my own projects.
Some of them are quite big and I wanted to have full control on how my files are compiled. There are two major points:

1) atl has first-class integration with Babel and enables caching possibilities. This can be useful for those who use Typescript with Babel.
When `useBabel` and `useCache` flags are enabled, typescript's emit will be transpiled with Babel and cached.
So next time if source file (+environment) has the same checksum we can totally skip typescript's and babel's transpiling.
This significantly reduces build time in this scenario.

2) atl is able to fork type-checker and emitter to a separate process, which also speeds-up some development scenarios (e.g. react with react-hot-loader)
So your webpack compilation will end earlier and you can explore compiled version in your browser while your files are typechecked.

## Configuration

1. Add `.ts` as a resolvable extension.
2. Configure all files with a `.ts` extension to be handled by `awesome-typescript-loader`.

**webpack.config.js**

```javascript
// `CheckerPlugin` is optional. Use it if you want async error reporting.
// We need this plugin to detect a `--watch` mode. It may be removed later
// after https://github.com/webpack/webpack/issues/3460 will be resolved.
const { CheckerPlugin } = require('awesome-typescript-loader')

module.exports = {

  // Currently we need to add '.ts' to the resolve.extensions array.
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx']
  },

  // Source maps support ('inline-source-map' also works)
  devtool: 'source-map',

  // Add the loader for .ts files.
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'awesome-typescript-loader'
      }
    ]
  },
  plugins: [
      new CheckerPlugin()
  ]
};
```

After that, you will be able to build TypeScript files with webpack.

## NodeJS versions

**The loader supports NodeJS 4 and newer.**

## tsconfig.json

You can use the tsconfig.json file to configure your compiler and loader:

```
{
    "compilerOptions": {
        "noImplicitAny": true,
        "removeComments": true
    },
    "awesomeTypescriptLoaderOptions": {
        /* ... */
    }
}
```

## Supported TypeScript

`awesome-typescript-loader@2.x` aims to support only `typescript@2.x` and `webpack@2x`, if you need old compilers please use
`1.x` or `0.x` versions.

## Advanced path resolution in TypeScript 2.0

If you want to use new `paths` and `baseUrl` feature of TS 2.0 please include `TsConfigPathsPlugin`.
This feature is available only for `webpack@2.1`.

```
const { TsConfigPathsPlugin } = require('awesome-typescript-loader');

resolve: {
    plugins: [
        new TsConfigPathsPlugin(/* { configFileName, compiler } */)
    ]
}
```

## Loader options

### silent *(boolean) (default=false)*

No logging from the checker. Please note that this option disables async error reporting because
this option bans `console.log()` usage.

### compiler *(string) (default='typescript')*

Allows use of TypeScript compilers other than the official one. Must be
set to the NPM name of the compiler, e.g. *ntypescript* or the path to a package folder.
Note that the compiler must be installed in **your** project. You can also use
nightly versions.

### useTranspileModule (boolean) (default=false)*

Use fast `transpileModule` emit mode. Disables automatically when you set compilerOption `declaration: true` ([reference](https://www.typescriptlang.org/docs/handbook/compiler-options.html)).

### instance *(string) (default='at-loader')*

Allows the use of several TypeScript compilers with different settings in one app. Override `instance` to initialize another instance.

### configFileName *(string) (default='tsconfig.json')*

Specifies the path to a TS config file. This is useful when you have multiple config files. This setting is useless *inside* a TS config file.

### transpileOnly *(boolean)*

Use this setting to disable type checking, enabling this will nullify the `CheckerPlugin` usage in your webpack configuration.

### errorsAsWarnings *(boolean)*

Emit all typescript errors as warnings.

### forceIsolatedModules *(boolean)*

Use this setting to disable dependent module recompilation.

### ignoreDiagnostics *(number[]) (default=[])*

You can squelch certain TypeScript errors by specifying an array of [diagnostic codes](https://github.com/Microsoft/TypeScript/blob/master/src/compiler/diagnosticMessages.json) to ignore.
For example, you can transpile [stage 1 properties](https://github.com/jeffmo/es-class-fields-and-static-properties) from `*.js` using `"ignoreDiagnostics": [8014]`.

### useBabel *(boolean) (default=false)*

Invoke Babel to transpile files. Useful with ES6 target. Please see `useCache` option
which can improve warm-up time.

If you're using `babelOptions`, anything in `.babelrc` will take precedence. This breaks expected usage for scenarios where you need two sets of Babel configs (example: one for Webpack, one for your build tools).

You may want to `"babelrc": false` to disable `.babelrc` if you don't want it:

```json
{
    "useBabel": true,
    "babelOptions": {
        "babelrc": false, /* Important line */
        "presets": [
            ["@babel/preset-env", { "targets": "last 2 versions, ie 11", "modules": false }]
        ]
    },
    "babelCore": "@babel/core", // needed for Babel v7
}
```

### babelCore *(string) (default=undefined)*

Override the path used to find `babel-core`. Useful if `node_modules` is installed in a non-standard place or webpack is being invoked from a directory not at the root of the project.

For Babel 7, this should be set to `"@babel/core"`.

### babelOptions *(object) (default=null)*

Use this option to pass some options to Babel (e.g. presets). Please note that
[`.babelrc` file](https://babeljs.io/docs/usage/babelrc/) is more universal way to do this.

### useCache *(boolean) (default=false)*

Use internal file cache. This is useful with Babel, when processing takes a long time to complete. Improves warm-up time.

### usePrecompiledFiles *(boolean) (default=false)*

Use pre-compiled files if any. Files must be named as `{filename}.js` and `{filename}.map`.

### cacheDirectory *(string) (default='.awcache')*

Directory where cache is stored.

### reportFiles *(string[])*

Specify [globs](https://github.com/isaacs/minimatch) to report file diagnostics. ALL OTHER ERRORS WILL NOT BE REPORTED. Example:

```
reportFiles: [
    "src/**/*.{ts,tsx}"
]
```

### getCustomTransformers *(string | ((program: ts.Program) => ts.CustomTransformers | undefined)) (default=undefined)*

Provide custom transformers, TypeScript 2.4.1+. Example:

```js
const styledComponentsTransformer = require('typescript-plugin-styled-components').default;
const keysTransformer = require('ts-transformer-keys/transformer').default;

// ...
rules: [
    {
        test: /\.tsx?$/,
        loader: 'awesome-typescript-loader',
        options: {
            // ... other loader's options
            getCustomTransformers: program => ({
                before: [
                    styledComponentsTransformer(),
                    keysTransformer(program)
                ]
            })
        }
    }
]
```

## Compiler options

You can pass compiler options inside the loader query string or in a TS config file.

---
_Source: https://npm.io/package/awesome-typescript-loader · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._