Breaking Change in jsii-pacmak v1.98.0

[biffgaut]

What's the change?

In jsii-pacmak v1.98.0 we had to make a potentially breaking change.
jsii-pacmak now takes a peer dependency on jsii-rosetta instead of a regular dependency.

What is the impact?

If you are using yarn v1 aka Classic or npm v3 to v6 you will likely see executions of jsii-pacmak failing.
If you are using a modern package manager or if you are using (recent) versions of projen to manage your jsii projects, you likely won't see any impact.

Why did you make that change?

jsii-pacmak uses jsii-rosetta to transliterate examples in docblocks from TypeScript to the target language.
Since we started publishing modern versions of jsii-rosetta that align with TypeScript releases, pacmak potentially used a different version of rosetta and typescript to transliterate these examples. In most cases this would not have been an issue; but can cause confusion why some examples work and others don't. Making jsii-rosetta a peer dependency allows you to use exactly the version you need to.

How do I fix it?

Add "jsii-rosetta": "<version>" into devDependencies in your package.json file.
With <version> matching the version of jsii, e.g. ^1.98.0 or 5.4.x

If you are using a modern package manager, you likely won't see any impact but should still add jsii-rosetta explicitly.
If you are using (recent) versions of projen to manage your jsii projects, jsii-rosetta is already added automatically.
If you are using yarn v1 aka Classic or npm v3 to v6 you will likely see failing builds. Add jsii-rosetta as described to resolve the issue.

---

Describe the bug

Late in the day on 4/30/2024 all our builds started failing:

 Error: Cannot find module 'jsii-rosetta'

We ensured we were using the most recently published version of 1-bookworm-slim-node20 (also published yesterday). Looking at yesterday's JSII release, it's clear that this is driven by this PR. Specifically the PR says that users of yarn v1 will need to install jsii-rosetta manually. The JSII image comes with yarn v1.22.19. There are also npm requirements posted, but it appears that the current images meet those requirements.

Since the latest version of yarn is still 1.22, I'm not sure what can be done to address the yarn requirement listed in the PR. The 2.x versions of yarn appear to still be beta.

It looks like it will be straightforward to update our build process to either update yarn or install jsii-rosetta, but it would be nice if the image was preconfigured with versions of the toolset required to build without additional installation.

Expected Behavior

That our JSII build steps continued to work after a minor release of JSII.

Current Behavior

An additional library jsii-rosetta is required which is not automatically installed by the versions of the package managers installed on the most recent JSII docker images.

Reproduction Steps

yarn run jsii-pacmak

Possible Solution

No response

Additional Information/Context

No response

SDK version used

CDK v2.138.0

Environment details (OS name and version, etc.)

jsii/superchain:1-bullseye-slim-node20

[mrgrain]

Unfortunately yarn 1 aka Classic is outdated software that does not receive any updates anymore. It has significantly diverged from the rest of the ecosystem.

Modern Yarn is currently at v4: https://yarnpkg.com/blog/release/4.0

Installation for modern Yarn is quite a bit different; it used a new Node tool called corepack as described here:
https://yarnpkg.com/getting-started/install

So the superchain image does indeed ship with modern yarn, it's just not enabled by default (yet). Maybe we should!

[biffgaut]

It appears that adding the line

    "jsii-rosetta": "^1.92.0",

to our package.json file was all that was required.

FWIW - We need to use 1.92 to match major releases with our outdated version of JSII itself, you should match your major version of JSII. And, yes, upon discovering this we will be updating our JSII packages shortly.

[github-actions]

This issue is now closed. Comments on closed issues are hard for our team to see.
If you need more assistance, please open a new issue that references this one.