Improve TypeScript recipe for ESM and ts-node usage

Co-authored-by: Sindre Sorhus <[email protected]>
Co-authored-by: Mark Wubben <[email protected]>

Author: 3 people

docs/recipes/es-modules.md

@@ -4,6 +4,8 @@ Translations: [Français](https://github.com/avajs/ava-docs/blob/master/fr_FR/do
 
 As of Node.js 12.17, [ECMAScript Modules](https://nodejs.org/docs/latest/api/esm.html#esm_introduction) are natively supported in Node.js itself. AVA 3.3 supports ESM test files, however support is incomplete. The [ESM support project](https://github.com/orgs/avajs/projects/2) tracks our progress.
 
+If you use TypeScript with `ts-node` please [see our Typescript recipe for setup instructions](./typescript.md).
+
 ## Using the `esm` package
 
 If you're using Node.js 10 and AVA 3 and you want to use the ESM syntax, without relying on Node.js' implementation, your best bet is to use the [`esm`](https://github.com/standard-things/esm) package. Make sure to use the `.js` extension and *do not* set `"type": "module"` in `package.json`.

docs/recipes/typescript.md

@@ -8,13 +8,73 @@ This guide assumes you've already set up TypeScript for your project. Note that
 
 ## Enabling AVA's support for TypeScript test files
 
+### With precompile step
+
 Out of the box AVA does not load TypeScript test files. You can use our [`@ava/typescript`] package, which is designed to work for projects that precompile TypeScript using the `tsc` command. Please see [`@ava/typescript`] for setup instructions.
 
 ### Using `ts-node`
 
-You can use [`ts-node`] to do live testing without transpiling to js files.  This can be especially helpful when you're using a bundler.
+You can use [`ts-node`] to do live testing without transpiling. This can be especially helpful when you're using a bundler. Be sure to install the required dev dependencies:
+
+`npm install --save-dev typescript ts-node`
+
+Then, depending on whether or not your package is of type `module` or not, the required setup differs. See either:
+
+1. [for packages with type "module"](#for-packages-with-type-module)
+2. [for packages without type "module"](#for-packages-without-type-module)
+
+#### For packages with type `module`
+
+If your `package.json` has `"type": "module"`, then this is the AVA configuration you need:
+
+`package.json`:
+
+```json
+{
+	"ava": {
+		"extensions": {
+			"ts": "module"
+		},
+		"nonSemVerExperiments": {
+			"configurableModuleFormat": true
+		},
+		"nodeArguments": [
+			"--loader=ts-node/esm"
+		]
+	}
+}
+```
+
+You also need to have this in your `tsconfig.json`:
+
+```json
+{
+	"compilerOptions": {
+		"module": "ES2020",
+		"moduleResolution": "node"
+	}
+}
+```
+
+And finally, even though you directly import code from your TypeScript files, you **must** import it from your `.ts` files with the `.js` extension instead!
+
+For example if your source file is `index.ts` looks like this:
+
+```ts
+export function myFunction() {}
+```
+
+Then in your AVA test files you must import it **as if it has the `.js` extension** it like so:
+
+```ts
+import {myFunction} from './index.js';
+```
+
+The reason that you need to write `.js` to import `.ts` files in your AVA test files, is explained by the `ts-node` author [in this post](https://github.com/nodejs/modules/issues/351#issuecomment-621257543).
+
+#### For packages without type "module"
 
-`npm i --save-dev typescript ts-node`
+If your `package.json` does not have `"type": "module"`, then this is the AVA configuration you need:
 
 `package.json`:
 
@@ -31,7 +91,7 @@ You can use [`ts-node`] to do live testing without transpiling to js files.  Thi
 }
 ```
 
-It's worth noting that with this configuration tests will fail if there are TypeScript build errors. If you want to test while ignoring these errors you can use `ts-node/register/transpile-only` instead of `ts-node/register`.
+It's worth noting that with this configuration, tests will fail if there are TypeScript build errors. If you want to test while ignoring these errors you can use `ts-node/register/transpile-only` instead of `ts-node/register`.
 
 ## Writing tests