Docs: Better typescript cli docs (cucumber#1382)

* Docs: Better typescript cli docs

* Reorganize docs/cli transpilation chapter

* Update docs/cli.md

Co-authored-by: David Goss <[email protected]>

Co-authored-by: aurelien-reeves <[email protected]>
Co-authored-by: David Goss <[email protected]>

Author: 3 people

.gitignore

@@ -11,3 +11,4 @@ node_modules
 tmp/
 usage.txt
 yarn-error.log
+.vscode

docs/cli.md

@@ -174,31 +174,43 @@ For instance, for ES6 support with [Babel](https://babeljs.io/) 7 add:
 
 This will effectively call `require('@babel/register')` prior to requiring any support files.
 
-### Non JS files
+If your files end with an extension other than `js`, make sure to also include the `--require` option to state the required support files. For example, if using [CoffeeScript](https://www.npmjs.com/package/coffeescript):
 
-If your files end in an extension other than `js`, make sure to also include the `--require` option to state the support files to require.
+```
+--require-module coffeescript/register --require 'features/**/*.coffee'
+```
+
+### Typescript
 
-For example, with [TypeScript](https://www.typescriptlang.org/):
+#### With ts-node
+
+If you are using [ts-node](https://github.com/TypeStrong/ts-node):
 
 ```
 --require-module ts-node/register --require 'step-definitions/**/*.ts'
 ```
 
-or [CoffeeScript](https://www.npmjs.com/package/coffeescript):
+> ⚠️ Some TypeScript setups use `esnext` modules by default, 
+>   which doesn't marry well with Node. You may consider using commonjs instead.
+>   See how to add [extra configuration](#extra-configuration) below.
+
+#### With babel
+
+If you are using babel with [@babel/preset-typescript](https://babeljs.io/docs/en/babel-preset-typescript):
 
 ```
---require-module coffeescript/register --require 'features/**/*.coffee'
+--require-module @babel/register --require 'step-definitions/**/*.ts'
 ```
 
-### Extra configuration
+### Extra Configuration
 
-Sometimes the required module (say `@ts-node/register`) needs extra configuration (e.g. you might want to configure it such that it prevents the compiled JS being written out to files, and pass some compiler options). In such cases, create a script (say, `tests.setup.js`):
+Sometimes the required module (say `@ts-node/register`) needs extra configuration. For example, you might want to configure it such that it prevents the compiled JS being written out to files, and pass some compiler options. In such cases, create a script (say, `tests.setup.js`):
 
 ```js
 require('ts-node').register({
   transpileOnly: true,
   compilerOptions: {
-    // your compiler options here
+    "module": "commonjs",
   },
 });
 ```