Skip to content

Commit

Permalink
docs: improve grammar & formatting, plus add TSConfig Reference links (…
Browse files Browse the repository at this point in the history 
…#375)

- improve grammar in several places
  - mostly add "the" and commas in several places where they were missing
    - and put a period or semicolon in a few places where there was a comma splice
    - for "deep merge", parens were used, whereas a colon is a better fit
  - consistently use "(see #x)", instead of sometimes using parens and other times using commas
    - also change "only if `useTsconfigDeclarationDir`" to "unless `useTsconfigDeclarationDir`" for clarity
      - have looked at this many times and thought something was unintuitive about this: `useTsconfigDeclarationDir` defaults to `false` after all
  - "typescript" -> "TypeScript" as a proper noun
  - "js" -> "JS" similarly
  - "es6" -> "ES6"
  - "rollup" -> "Rollup"
  - "rollup watch" -> "Rollup's watch mode"
  - "work directory" -> "working directory" (that's what the "w" stands for)

- improve formatting in several places
  - split up paragraphs a bit more neatly as a single new line in Markdown is just rendered as a space
    - similar to my previous commit for `emitDeclarationOnly`
      - and apparently I missed two sentences in the "Declarations" section there too
  - for `tsconfig`, `objectHashIgnoreUnknownHack`, and `typescript`, actually add a double new line
    - to break up the paragraph for better rendered readability
  - don't skip heading level for "Some compiler options" -- this should be an h3, not an h4
    - remove inconsistent period in one of the headings as well (and headings aren't normally supposed to have periods)
  - consistently use backticks when referencing plugin, `tsconfig` options, etc
    - e.g. `tsconfig`, `include`, `exclude`, `node_modules`, etc
      - also, for `allowJs`, put the proper `**/node_modules/**/*` `exclude` as an example similar to the `**/*.js+(|x)`
        - as plain `node_modules` won't work as I've recently found out
  - consistently use 1 tab indent for plugin options' descriptions, instead of a few 2 tab indents
  - for "Requirements" section, use bullets instead having everything on one line
    - the way it was written seemed like they were intended to be on different lines, but a single new line in Markdown is just rendered as a space (per above)
      - bullets are a little better than just new lines as well

- add TSConfig Reference links to several `tsconfig` options mentions
  - `extends`, `declarationDir`, `declaration`, `declarationMap`, and `emitDeclarationOnly`
    - also added the mention of `extends` in "chaining tsconfigs"
  • Loading branch information
@agilgur5
agilgur5 authored Jul 6, 2022
1 parent 00b4414 commit 8f659a9
Showing 1 changed file with 50 additions and 32 deletions.
82 changes: 50 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@

Rollup plugin for typescript with compiler errors.

This is a rewrite of original rollup-plugin-typescript, starting and borrowing from [this fork](https://github.com/alexlur/rollup-plugin-typescript).
This is a rewrite of the original `rollup-plugin-typescript`, starting and borrowing from [this fork](https://github.com/alexlur/rollup-plugin-typescript).

This version is somewhat slower than original, but it will print out typescript syntactic and semantic diagnostic messages (the main reason for using typescript after all).
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

Expand All @@ -34,38 +34,40 @@ export default {
}
```

The 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.
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
### Some compiler options are forced

* `noEmitHelpers`: false
* `importHelpers`: true
* `noResolve`: false
* `noEmit`: false (Rollup controls emit)
* `noEmitOnError`: false (Rollup controls emit. See [#254](https://github.com/ezolenko/rollup-plugin-typescript2/issues/254) and the `abortOnError` plugin option below)
* `inlineSourceMap`: false (see [#71](https://github.com/ezolenko/rollup-plugin-typescript2/issues/71))
* `outDir`: `./placeholder` in cache root, see [#83](https://github.com/ezolenko/rollup-plugin-typescript2/issues/83) and [Microsoft/TypeScript#24715](https://github.com/Microsoft/TypeScript/issues/24715)
* `declarationDir`: Rollup's `output.file` or `output.dir` (*only if `useTsconfigDeclarationDir` is false in the plugin options*)
* `outDir`: `./placeholder` in cache root (see [#83](https://github.com/ezolenko/rollup-plugin-typescript2/issues/83) and [Microsoft/TypeScript#24715](https://github.com/Microsoft/TypeScript/issues/24715))
* `declarationDir`: Rollup's `output.file` or `output.dir` (*unless `useTsconfigDeclarationDir` is true in the plugin options*)
* `moduleResolution`: `node` (*`classic` is [deprecated](https://www.typescriptlang.org/docs/handbook/module-resolution.html). It also breaks this plugin, see [#12](https://github.com/ezolenko/rollup-plugin-typescript2/issues/12) and [#14](https://github.com/ezolenko/rollup-plugin-typescript2/issues/14)*)
* `allowNonTsExtensions`: true to let other plugins on the chain generate typescript, update plugin's include filter to pick them up (see [#111](https://github.com/ezolenko/rollup-plugin-typescript2/issues/111))
* `allowNonTsExtensions`: true to let other plugins on the chain generate typescript; update plugin's `include` filter to pick them up (see [#111](https://github.com/ezolenko/rollup-plugin-typescript2/issues/111))

#### Some compiler options have more than one compatible value.
### Some compiler options have more than one compatible value

* `module`: defaults to `ES2015`, other valid value is `ESNext` (required for dynamic imports, see [#54](https://github.com/ezolenko/rollup-plugin-typescript2/issues/54)).

#### Some options need additional configuration on plugin side
### Some options need additional configuration on plugin side

* `allowJs`: lets typescript process js files as well, if you use it, modify plugin's `include` option to add `"*.js+(|x)", "**/*.js+(|x)"` (might want to exclude node_modules, it will slow down the build significantly).
* `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 `browser: true` option is used, see [#66](https://github.com/ezolenko/rollup-plugin-typescript2/issues/66).
Must be before `rollup-plugin-typescript2` in the plugin list, especially when the `browser: true` option is used (see [#66](https://github.com/ezolenko/rollup-plugin-typescript2/issues/66)).

#### @rollup/plugin-commonjs

See explanation for `rollupCommonJSResolveHack` option below.
See the explanation for `rollupCommonJSResolveHack` option below.

#### @rollup/plugin-babel

Expand All @@ -91,13 +93,14 @@ See [#108](https://github.com/ezolenko/rollup-plugin-typescript2/issues/108)

* `cwd`: `string`

The current work directory, default `process.cwd()`.
The current working directory. Defaults to `process.cwd()`.

* `tsconfigDefaults`: `{}`

The object passed as `tsconfigDefaults` will be merged with loaded `tsconfig.json`. Final config passed to typescript will be the result of values in `tsconfigDefaults` replaced by values in loaded `tsconfig.json`, replaced by values in `tsconfigOverride` and then replaced by hard `compilerOptions` overrides on top of that (see above).
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 usage of defaults and overrides and keep everything in `tsconfig.json` file (tsconfigs can themselves be chained, so save some turtles).
For simplicity and other tools' sake, try to minimize the usage of defaults and overrides and keep everything in a `tsconfig.json` file (`tsconfig`s can themselves be chained with [`extends`](https://www.typescriptlang.org/tsconfig#extends), so save some turtles).

```js
let defaults = { compilerOptions: { declaration: true } };
Expand All @@ -113,11 +116,15 @@ See [#108](https://github.com/ezolenko/rollup-plugin-typescript2/issues/108)
]
```

This is a [deep merge](https://lodash.com/docs/4.17.4#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.
This is a [deep merge](https://lodash.com/docs/4.17.4#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 file is missing unless the value is set explicitly.
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`: `{}`

Expand Down Expand Up @@ -152,31 +159,40 @@ See [#108](https://github.com/ezolenko/rollup-plugin-typescript2/issues/108)

* `abortOnError`: true

Bail out on first syntactic or semantic error. In some cases setting this to false will result in exception in rollup itself (for example for unresolvable imports).
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`](https://github.com/ezolenko/rollup-plugin-typescript2/releases/0.30.0) (see [#251](https://github.com/ezolenko/rollup-plugin-typescript2/pull/251)), so this no longer has any effect -- as if it is always `true`.

* `objectHashIgnoreUnknownHack`: false

The plugin uses rollup config as part of 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 if you need it (`Error: Unknown object type "xxx"` for example) and make sure to run with `clean: true` once in a while and definitely before a release. (See [#105](https://github.com/ezolenko/rollup-plugin-typescript2/issues/105) and [#203](https://github.com/ezolenko/rollup-plugin-typescript2/pull/203))
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](https://github.com/ezolenko/rollup-plugin-typescript2/issues/105) and [#203](https://github.com/ezolenko/rollup-plugin-typescript2/pull/203))

* `useTsconfigDeclarationDir`: false

If true, declaration files will be emitted in the directory given in the tsconfig. If false, the declaration files will be placed inside the destination directory given in the Rollup configuration.
If true, declaration files will be emitted in the [`declarationDir`](https://www.typescriptlang.org/tsconfig#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.
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")`. Must be TS 2.0+, things might break if transpiler interfaces changed enough from what the plugin was built against.
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")`.

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+
**experimental**, TypeScript 2.4.1+

Transformers will likely be available in tsconfig eventually, so this is not a stable interface, see [Microsoft/TypeScript#14419](https://github.com/Microsoft/TypeScript/issues/14419).
Transformers will likely be available in `tsconfig` eventually, so this is not a stable interface (see [Microsoft/TypeScript#14419](https://github.com/Microsoft/TypeScript/issues/14419)).

For example, integrating [kimamula/ts-transformer-keys](https://github.com/kimamula/ts-transformer-keys):

Expand All @@ -195,28 +211,30 @@ See [#108](https://github.com/ezolenko/rollup-plugin-typescript2/issues/108)

### Declarations

This plugin respects `declaration: true` in your `tsconfig.json` file. When set, it will emit `*.d.ts` files for your bundle.
This plugin respects [`declaration: true`](https://www.typescriptlang.org/tsconfig#declaration) 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](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html).<br />
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 the declarationDir set `useTsconfigDeclarationDir` to `true` in the plugin options.
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`](https://www.typescriptlang.org/tsconfig#declarationDir), set `useTsconfigDeclarationDir: true` in the plugin options.

The above also applies to `declarationMap: true` and `*.d.ts.map` files for your bundle.
The above also applies to [`declarationMap: true`](https://www.typescriptlang.org/tsconfig#declarationMap) 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`.
This plugin also respects [`emitDeclarationOnly: true`](https://www.typescriptlang.org/tsconfig#emitDeclarationOnly) 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.<br />
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 watch, because import statements are not generated and changing them doesn't trigger a rebuild.
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)
* TypeScript `2.4+`
* Rollup `1.26.3+`
* Node `6.4.0+` (basic ES6 support)

### Reporting bugs and Contributing

Expand Down

0 comments on commit 8f659a9

Please sign in to comment.