search

kulshekhar / ts-jest

A Jest transformer with source map support that lets you use Jest to test projects written in TypeScript.
https://kulshekhar.github.io/ts-jest
MIT License
6.89k stars 453 forks source link

[Bug]: docs confusion - deprecated presets #4433

Open dandv opened 2 weeks ago

dandv commented 2 weeks ago

Version

29.2.0

Steps to reproduce

The documentation at https://kulshekhar.github.io/ts-jest/docs/getting-started/presets#the-presets states

⚠️ The list of preset below is now deprecated in favor of util functions.

Expected behavior

Should that be "presets" (plural)?

What exactly does that mean?

How can the "util functions" be used?

Actual behavior

https://kulshekhar.github.io/ts-jest/docs/getting-started/presets#basic-usage then says,

// Replace ts-jest with the preset you want to use from the above list

If all presets in the list are deprecated, should that comment be updated?

Also, is the example at https://kulshekhar.github.io/ts-jest/docs/guides/esm-support#use-esm-presets outdated? It uses preset: 'ts-jest/presets/default-esm', // or other ESM presets.

I'm just trying to use the latest ESM preset that supports Top-Level Await, with least hassle.

ahnpnl commented 2 weeks ago

I put the link to Advanced section, but it seems like not too obvious. Do you have any suggestions about wording to instruct to read Advanced section.

Or maybe we should even rename Advanced to be something else.

Other places indeed need to be updated with util functions

ahnpnl commented 2 weeks ago

I saw Docusaurus at https://docusaurus.io/docs/migration/v3 has a block "HOW TO UPGRADE". I'm thinking about adding similar block, like "HOW TO MIGRATE"

dandv commented 2 weeks ago

Do you have any suggestions about wording to instruct to read Advanced section.

If I understand correctly that presets should be used by calling functions like createDefaultEsmPreset as shown in the example at the very bottom of the page, then my suggestions would be to:

  1. Start the Presets page with "The current best practice for using presets is to call one of the utility functions below to create (and optionally extend) presets. Legacy presets are listed at the bottom of the page."
  2. Move the list of utility function from "Advanced" section to the top after the paragraph above, along with the example. The example should work out of the box for TypeScript + TLA, keeping in mind that most users really don't care about transforms or ESM or whatever is going on under the hood. They just want Jest to work TypeScript files, to support Top Level Await, and to not have to change their import syntax to accommodate ESM/TLA in tests.
  3. For users who do care, the section can then explain that example and these utility functions:
    • what is the advantage of using this much more verbose syntax instead of the simple presets?
    • what does .transform do?
    • what other properties are available on the object returned by create...Preset()?
    • what other keys besides transform must, or should, be used? (link to reference page)
  4. Rename the "Basic usage" section to "Legacy preset usage".
  5. Move the table of presets under this Legacy section.
ahnpnl commented 2 weeks ago

I also looked at Jest documentation, specificly API page. I think we can also create kind of like table of content at the top of the page which contains function names. Each item in table of content will link to the description as well as explanation below