Skip to content

Latest commit

 

History

History
248 lines (164 loc) · 11.6 KB

README.md

File metadata and controls

248 lines (164 loc) · 11.6 KB
Raw

rollup-plugin-typescript2

npm-version npm-monthly-downloads Node.js CI

Rollup plugin for typescript with compiler errors.

This is a rewrite of the original rollup-plugin-typescript, starting and borrowing from this fork.

This version is somewhat slower than the original, but it will print out TypeScript syntactic and semantic diagnostic messages (the main reason for using TypeScript after all).

Installation

# with npm
npm install rollup-plugin-typescript2 typescript tslib --save-dev
# with yarn
yarn add rollup-plugin-typescript2 typescript tslib --dev

Usage

// rollup.config.js
import typescript from 'rollup-plugin-typescript2';

export default {
	input: './main.ts',

	plugins: [
		typescript(/*{ plugin options }*/)
	]
}

This plugin inherits all compiler options and file lists from your tsconfig.json file. If your tsconfig has another name or another relative path from the root directory, see tsconfigDefaults, tsconfig, and tsconfigOverride options below. This also allows for passing in different tsconfig files depending on your build target.

Some compiler options are forced

  • noEmitHelpers: false
  • importHelpers: true
  • noResolve: false
  • noEmit: false (Rollup controls emit)
  • noEmitOnError: false (Rollup controls emit. See #254 and the abortOnError plugin option below)
  • inlineSourceMap: false (see #71)
  • outDir: ./placeholder in cache root (see #83 and Microsoft/TypeScript#24715)
  • declarationDir: Rollup's output.file or output.dir (unless useTsconfigDeclarationDir is true in the plugin options)
  • allowNonTsExtensions: true to let other plugins on the chain generate typescript; update plugin's include filter to pick them up (see #111)

Some compiler options have more than one compatible value

  • module: defaults to ES2015. Other valid values are ES2020, ES2022 and ESNext (required for dynamic imports, see #54).

  • moduleResolution: defaults to node10 (same as node), but value from tsconfig is used if specified. Other valid (but mostly untested) values are node16, nodenext and bundler. If in doubt, use node10.

    • classic is deprecated and changed to node10. It also breaks this plugin, see #12 and #14.

Some options need additional configuration on plugin side

  • allowJs: lets TypeScript process JS files as well. If you use it, modify this plugin's include option to add "*.js+(|x)", "**/*.js+(|x)" (might also want to exclude "**/node_modules/**/*", as it can slow down the build significantly).

Compatibility

@rollup/plugin-node-resolve

Must be before rollup-plugin-typescript2 in the plugin list, especially when the browser: true option is used (see #66).

@rollup/plugin-commonjs

See the explanation for rollupCommonJSResolveHack option below.

@rollup/plugin-babel

This plugin transpiles code, but doesn't change file extensions. @rollup/plugin-babel only looks at code with these extensions by default: .js,.jsx,.es6,.es,.mjs. To workaround this, add .ts and .tsx to its list of extensions.

// ...
import { DEFAULT_EXTENSIONS } from '@babel/core';
// ...
	babel({
		extensions: [
			...DEFAULT_EXTENSIONS,
			'.ts',
			'.tsx'
		]
	}),
// ...

See #108

Plugin options

  • cwd: string

    The current working directory. Defaults to process.cwd().

  • tsconfigDefaults: {}

    The object passed as tsconfigDefaults will be merged with the loaded tsconfig.json. The final config passed to TypeScript will be the result of values in tsconfigDefaults replaced by values in the loaded tsconfig.json, replaced by values in tsconfigOverride, and then replaced by forced compilerOptions overrides on top of that (see above).

    For simplicity and other tools' sake, try to minimize the usage of defaults and overrides and keep everything in a tsconfig.json file (tsconfigs can themselves be chained with extends, so save some turtles).

     let defaults = { compilerOptions: { declaration: true } };
 let override = { compilerOptions: { declaration: false } };

 // ...
 plugins: [
 	typescript({
 		tsconfigDefaults: defaults,
 		tsconfig: "tsconfig.json",
 		tsconfigOverride: override
 	})
 ]

    This is a deep merge: objects are merged, arrays are merged by index, primitives are replaced, etc. Increase verbosity to 3 and look for parsed tsconfig if you get something unexpected.

  • tsconfig: undefined

    Path to tsconfig.json. Set this if your tsconfig has another name or relative location from the project directory.

    By default, will try to load ./tsconfig.json, but will not fail if the file is missing, unless the value is explicitly set.

  • tsconfigOverride: {}

    See tsconfigDefaults.

  • check: true

    Set to false to avoid doing any diagnostic checks on the code. Setting to false is sometimes referred to as transpileOnly by other TypeScript integrations.

  • verbosity: 1

    • 0 -- Error
    • 1 -- Warning
    • 2 -- Info
    • 3 -- Debug

  • clean: false

    Set to true to disable the cache and do a clean build. This also wipes any existing cache.

  • cacheRoot: node_modules/.cache/rollup-plugin-typescript2

    Path to cache. Defaults to a folder in node_modules.

  • include: [ "*.ts+(|x)", "**/*.ts+(|x)", "**/*.cts", "**/*.mts" ]

    By default compiles all .ts and .tsx files with TypeScript.

  • exclude: [ "*.d.ts", "**/*.d.ts", "**/*.d.cts", "**/*.d.mts" ]

    But excludes type definitions.

  • abortOnError: true

    Bail out on first syntactic or semantic error. In some cases, setting this to false will result in an exception in Rollup itself (for example, unresolvable imports).

  • rollupCommonJSResolveHack: false

    Deprecated. OS native paths are now always used since 0.30.0 (see #251), so this no longer has any effect -- as if it is always true.

  • objectHashIgnoreUnknownHack: false

    The plugin uses your Rollup config as part of its cache key. object-hash is used to generate a hash, but it can have trouble with some uncommon types of elements. Setting this option to true will make object-hash ignore unknowns, at the cost of not invalidating the cache if ignored elements are changed.

    Only enable this option if you need it (e.g. if you get Error: Unknown object type "xxx") and make sure to run with clean: true once in a while and definitely before a release. (See #105 and #203)

  • useTsconfigDeclarationDir: false

    If true, declaration files will be emitted in the declarationDir given in the tsconfig. If false, declaration files will be placed inside the destination directory given in the Rollup configuration.

    Set to false if any other Rollup plugins need access to declaration files.

  • typescript: peerDependency

    If you'd like to use a different version of TS than the peerDependency, you can import a different TypeScript module and pass it in as typescript: require("path/to/other/typescript").

    You can also use an alternative TypeScript implementation, such as ttypescript, with this option.

    Must be TS 2.0+; things might break if the compiler interfaces changed enough from what the plugin was built against.

  • transformers: undefined

    experimental, TypeScript 2.4.1+

    Transformers will likely be available in tsconfig eventually, so this is not a stable interface (see Microsoft/TypeScript#14419).

    For example, integrating kimamula/ts-transformer-keys:

     const keysTransformer = require('ts-transformer-keys/transformer').default;
 const transformer = (service) => ({
 	before: [ keysTransformer(service.getProgram()) ],
 	after: []
 });

 // ...
 plugins: [
 	typescript({ transformers: [transformer] })
 ]

Declarations

This plugin respects declaration: true in your tsconfig.json file. When set, it will emit *.d.ts files for your bundle. The resulting file(s) can then be used with the types property in your package.json file as described here.
By default, the declaration files will be located in the same directory as the generated Rollup bundle. If you want to override this behavior and instead use declarationDir, set useTsconfigDeclarationDir: true in the plugin options.

The above also applies to declarationMap: true and *.d.ts.map files for your bundle.

This plugin also respects emitDeclarationOnly: true and will only emit declarations (and declaration maps, if enabled) if set in your tsconfig.json. If you use emitDeclarationOnly, you will need another plugin to compile any TypeScript sources, such as @rollup/plugin-babel, rollup-plugin-esbuild, rollup-plugin-swc, etc. When composing Rollup plugins this way, rollup-plugin-typescript2 will perform type-checking and declaration generation, while another plugin performs the TypeScript to JavaScript compilation.
Some scenarios where this can be particularly useful: you want to use Babel plugins on TypeScript source, or you want declarations and type-checking for your Vite builds (NOTE: this space has not been fully explored yet).

Watch mode

The way TypeScript handles type-only imports and ambient types effectively hides them from Rollup's watch mode, because import statements are not generated and changing them doesn't trigger a rebuild.

Otherwise the plugin should work in watch mode. Make sure to run a normal build after watch session to catch any type errors.

Requirements

  • TypeScript 2.4+
  • Rollup 1.26.3+
  • Node 6.4.0+ (basic ES6 support)

Reporting bugs and Contributing

See CONTRIBUTING.md