Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add note about usage of ESM in source config file #1394

Open
wants to merge 3 commits into
base: docs
Choose a base branch
from
Open

Add note about usage of ESM in source config file #1394

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ed1af94
fix (#1391)
cspotcode Jul 9, 2021
df27a27
fix transformers docs about ttypescript and ts-patch (#1392)
cspotcode Jul 9, 2021
ef08bc8
Add note about usage of ESM in source config file
karlhorky Jul 10, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
6 changes: 4 additions & 2 deletions website/docs/compilers.md
View file
Open in desktop
Expand Up @@ -6,14 +6,16 @@ Some projects require a patched typescript compiler which adds additional featur
add the ability to configure custom transformers. These are drop-in replacements for the vanilla `typescript` module and
implement the same API.

For example, to use `ts-patch` and `ts-transformer-keys`, add this to your `tsconfig.json`:
For example, to use `ttypescript` and `ts-transformer-keys`, add this to your `tsconfig.json`:

```json title="tsconfig.json"
{
"ts-node": {
"compiler": "ts-patch"
// This can be omitted when using ts-patch
"compiler": "ttypescript"
},
"compilerOptions": {
// plugin configuration is the same for both ts-patch and ttypescript
"plugins": [
{ "transform": "ts-transformer-keys/transformer" }
]
Expand Down
23 changes: 23 additions & 0 deletions website/docs/module-type-overrides.md
View file
Open in desktop
Expand Up @@ -41,6 +41,29 @@ When multiple patterns match the same file, the last pattern takes precedence.
* `esm` overrides matches files to compile and execute as native ECMAScript modules.
* `package` resets either of the above to default behavior, which obeys `package.json` `"type"` and `tsconfig.json` `"module"` options.

**Note:** This does not mean that you have to write CommonJS in your source `webpack.config.ts` file
- here you can continue writing imports and exports in ESM syntax.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about wordsmithing this a bit to focus on "syntax" and avoid negatives, so we're saying something like "you can still use ECMAScript import / export syntax in your .ts file."

Following that by a link to webpack's documentation page makes sense.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about merging this entire page into the "CommonJS vs native ECMAScript modules" page? Maybe giving that page a better title, like "Module Formats: CommonJS and ECMAScript modules"?

I'm wondering if we can have a single page that comprehensively describes the differences between CommonJS and ECMAScript modules, explains that you can almost always use import and export syntax, and explains moduleTypes overrides.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about wordsmithing this a bit to focus on "syntax" and avoid negatives, so we're saying something like "you can still use ECMAScript import / export syntax in your .ts file."

Following that by a link to webpack's documentation page makes sense.

I'm wondering if we can have a single page that comprehensively describes the differences between CommonJS and ECMAScript modules, explains that you can almost always use import and export syntax, and explains moduleTypes overrides.

Nice, I think these two together makes for a really nice change. Then anyone confused can read everything about the module formats, because the information is right next to it.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok cool. If I get to this before you, I think I'll take a stab at some of this refactoring -- pushing my changes to this branch -- and ask you for a review to make sure it's all still intuitive.


For example, this syntax with `import` and `export` in your `webpack.config.ts` source file is just fine:

```ts
import * as path from 'path';
import * as webpack from 'webpack';
// in case you run into any typescript error when configuring `devServer`
import 'webpack-dev-server';

const config: webpack.Configuration = {
mode: 'production',
entry: './foo.js',
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'foo.bundle.js',
},
};

export default config;
```
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hesitate to duplicate this rather than linking to webpack's documentation. webpack might be updating it soon. Also, webpack is not the only tool we want to integrate with.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about we create a webpack page under "Recipes"? That way, we can afford to give very specific webpack advice and examples, and we can link to the moduleTypes page.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, if we just follow your other suggestion from above and link to the webpack config, would that resolve this in a different way?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess the only thing we'd be saying that webpack's website isn't, is we'd be giving an example moduleTypes config. I dunno if webpack's website will eventually add the same.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, I think I understand - you mean because if it was a recipe, both the moduleTypes config and the actual webpack config would just be in one place, got it. That's true - if we linked to the docs instead, then the moduleTypes config would be on the ts-node website and the webpack config would be on the webpack docs website, separated by that link.


## Caveats

Files with an overridden module type are transformed with the same limitations as [`isolatedModules`](https://www.typescriptlang.org/tsconfig#isolatedModules). This will only affect rare cases such as using `const enum`s with [`preserveConstEnums`](https://www.typescriptlang.org/tsconfig#preserveConstEnums) disabled.
Expand Down
2 changes: 1 addition & 1 deletion website/readme-sources/license.md
View file
Open in desktop
Expand Up @@ -2,7 +2,7 @@
title: License
---

[MIT](https://github.com/TypeStrong/ts-node/blob/main/LICENSE)
ts-node is licensed under the MIT license. [MIT](https://github.com/TypeStrong/ts-node/blob/main/LICENSE)

ts-node includes source code from Node.js which is licensed under the MIT license. [Node.js license information](https://raw.githubusercontent.com/nodejs/node/master/LICENSE)

Expand Down