2243 clarify transpile.md #2244
Conversation
Cucumber needs typescript to be transpiled to the CommonJS format for the examples as given in this document to work.
More elaborate retooling for clarity.
Jeff-Tian
force-pushed
the
2243-clarify-transpile.md
branch
from
92eaea4
to
aea6ec2
Compare
|
Thanks, @michael-lloyd-morris! Great work, it'll benefit many others unfamiliar with nodejs and esm etc. |
docs/transpiling.md
Outdated
|
|
||
| ```javascript | ||
| export default { | ||
| requireModule: ['ts-node/register'], |
There was a problem hiding this comment.
This doesn’t seem right? require-module doesn’t affect import
There was a problem hiding this comment.
I think this can just be removed.
There was a problem hiding this comment.
It needs to be reworded heavily and I've done so. If you read that header as applying to all ESM projects others will too. That sub header is level 4 and it was meant to cover "with TS-Node to load ES modules"
docs/transpiling.md
Outdated
|
|
||
| ```shell | ||
| $ NODE_OPTIONS="--loader ts-node/esm" cucumber-js --import 'step-definitions/**/*.ts' | ||
| Your cucumber.js file will need to be an ESM module and contain the following at a minimum: |
There was a problem hiding this comment.
The config file can still be JSON or YAML - I guess we want to say that if JavaScript then it should be the appropriate format.
There was a problem hiding this comment.
Lines removed.
docs/transpiling.md
Outdated
|
|
||
| ```json | ||
| { | ||
| "scripts: { |
There was a problem hiding this comment.
Missing a double quote on the key here
There was a problem hiding this comment.
Ah. Sorry. Also spotted an uncapitalized T at the start of a sentence so I sent the whole thing through a spell/grammar checker to be sure. Should be good now.
|
These examples are fairly complex and they also raise a lot of Google and Bing search results. Perhaps linking to the relevant cucumber-js-examples would be in order? If so I need to add an example for the somewhat gnarly ts-node with esm modules scenario. |
|
@davidjgoss Please let me know what else do I need to do for this. |
docs/transpiling.md
Outdated
|
|
||
| You'll also need to specify where your support code is, since `.ts` files won't be picked up by default. | ||
| Cucumber doesn't load `*.ts` files by default. The glob pattern `step-definitions/**/*.ts` will load them from the default step definition location. |
There was a problem hiding this comment.
I don't think this line is an improvement. step-definitions isn't any of our default paths.
There was a problem hiding this comment.
Reverted. I wasn't aware of that btw - many of the examples follow this pattern.
docs/transpiling.md
Outdated
|
|
||
| - In a configuration file `{ requireModule: ['ts-node/register'], require: ['step-definitions/**/*.ts'] }` | ||
| - On the CLI `$ cucumber-js --require-module ts-node/register --require 'step-definitions/**/*.ts'` | ||
|
|
||
| #### ESM | ||
| If you are using ts-node in a CommonJS project then this configuration will work, but if you have an ESM project there are additional steps. |
There was a problem hiding this comment.
We should make clear that both requireModule and require are not suitable for ESM and that the --loader flag and import option are their respective equivalents.
docs/transpiling.md
Outdated
| ``` | ||
|
|
||
| Don't forget to set your `tsconfig.json` to emit JavaScript with `import` and `export` statements: | ||
| That last step requires setting an environment variable. The cleanest way to do this is to include the [cross-env](https://www.npmjs.com/package/cross-env) package with `npm i -D cross-env`. With that package installed make the following change to your npm test script invocation in the package.json file: |
There was a problem hiding this comment.
I don't think we should be prescriptive of using this particular library/approach. By all means mention it as an option but examples should be as vanilla as possible really.
|
Sorry about the lag. Requested updates now pushed. |
In particular, we don't have a `loader` option - this can't currently be set in-process so in practise we need to reply on users setting the environment variable (or, invoking `node` directly, but that's not an example I would document).
🤔 What's changed?
Clarified the differences between transpiling Cucumber in CommonJS and ESM
⚡️ What's your motivation?
Spent 4 hours slogging through this.
🏷️ What kind of change is this?
♻️ Anything particular you want feedback on?
Is this rewrite clear to others?
📋 Checklist:
This text was originally generated from a template, then edited by hand. You can modify the template here.