chore: upgrade syntax highlighting dependencies, `prism-react-renderer` to v2, `react-live` to v4 #9316

harryzcy · 2023-09-17T03:29:07Z

Breaking changes

Docusaurus v3 bumps 2 major dependencies related to code syntax highlighting

prism-react-renderer v1 => v2
react-live v2 => v4

`prism-react-renderer` v2

The prism-react-renderer v2 release notes are not super exhaustive, but there are 2 major changes to be aware of for Docusaurus users.

Theme API

The API for prism-react-renderer is changed. Previously, to import a theme, you would use const customTheme = require('prism-react-renderer/themes/<themeName>');.

But now, prism-react-renderer exports all themes as a single variable themes. So now you would import like the following:

import { themes } from "prism-react-renderer";
const customTheme = themes.github; // or other theme names

Default languages

Previously, react-prism-render included more languages by default: https://github.com/FormidableLabs/prism-react-renderer/blob/v1.3.5/src/vendor/prism/includeLangs.js

From v2+, less languages are included: https://github.com/FormidableLabs/prism-react-renderer/blob/prism-react-renderer%402.1.0/packages/generate-prism-languages/index.ts#L9

You may need to add the languages you need to the Docusaurus config:

const siteConfig = {
  themeConfig: {
    prism: {
      additionalLanguages: ["bash", "diff", "json"],
    }
  }
};

Reminder: the list of languages supported by prism: https://prismjs.com/#supported-languages

Note: make sure to restart the Docusaurus dev server after adding a language, or you'll get a console error: runtime~main.js:39 Uncaught Error: Cannot find module './prism-scss'

`react-live` v4

Docusaurus upgrades react-live from v2 to v4. This shouldn't affect much Docusaurus users but newer versions might have new useful features to check.

Major version release notes:

v3: swap code transpiler from Bublé to Sucrase, swap internal editor
v4: upgrade codebase to TypeScript

Motivation

Upgrade major code syntax highlighting libraries to be on newer versions and have access to latest features.

Some code blocks will have improved highlighting for free.

For example, on the Docusaurus websites our visual regression tests noticed those improvements: https://app.argos-ci.com/meta-open-source/docusaurus/builds/249

Test Plan

CI + visual tests

Test links

https://deploy-preview-9316--docusaurus-2.netlify.app/

Related issues/PRs

fix #8940

The `prism` prop for Hightlight is declared as optional, but omitting it gives errors. So it's now passed in.

netlify · 2023-09-17T06:13:15Z

✅ [V2]

Name	Link
🔨 Latest commit	`bcc6bdf`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/65203ceb78e37e0008f8eb68
😎 Deploy Preview	https://deploy-preview-9316--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

github-actions · 2023-09-17T06:14:03Z

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 73	🟢 97	🟢 92	🟢 100	🟠 89	Report
/docs/installation	🟠 72	🟢 98	🟢 92	🟢 100	🟠 89	Report

slorber

Thanks

That's a good idea to do this upgrade for Docusaurus v3

We'll also have to update the docs as well:

We'll also want to upgrade react-live to avoid a duplicate prism version. React-Live v4 uses prism-react-renderer v2
https://github.com/FormidableLabs/react-live
Supersed this PR: #6589

Also we'll need some notes to explain users how to handle this breaking change. Can you write down some notes to explain what users should do when upgrading, and link to relevant external resources explaining breaking changes in depth?

Also related but apparently react-live upgrade breaks SSR support, and regression is still not fixed today (cf #6246 (comment)). Is it safe to upgrade or can it annoy our users? 🤷‍♂️ We need to study that. I think it should be fine because afaik we SSR a "loading..." placeholder for the preview, and bypass SSR for now.

examples/classic/package.json

packages/docusaurus-theme-common/src/utils/codeBlockUtils.ts

packages/docusaurus-theme-common/package.json

examples/classic/docusaurus.config.js

examples/classic-typescript/docusaurus.config.js

examples/classic-typescript/package.json

yarn.lock

harryzcy · 2023-09-19T16:47:57Z

Also we'll need some notes to explain users how to handle this breaking change. Can you write down some notes to explain what users should do when upgrading, and link to relevant external resources explaining breaking changes in depth?

@slorber where should this go?

slorber · 2023-09-20T14:23:32Z

Also we'll need some notes to explain users how to handle this breaking change. Can you write down some notes to explain what users should do when upgrading, and link to relevant external resources explaining breaking changes in depth?

@slorber where should this go?

I usually put a ## Breaking changes section at the top of each PR with some notes and external ref links.

This makes it easier to aggregate all those notes into the final v3.0 blog post on release. It doesn't have to be super polished but please note down things that we might have forgotten in a few weeks, and that Docusaurus users should be aware of when upgrading ;) Links to upgraded packages release notes and breaking change docs can be useful for example.

See for example PRs listed in v3 beta:
https://github.com/facebook/docusaurus/releases/tag/v3.0.0-beta.0

slorber · 2023-09-20T14:25:56Z

Apparently we have some pages that produce errors now 😅 site can't build in production mode.

Try:

harryzcy · 2023-09-20T22:37:31Z

I'll take another look. ~~I can't reproduce it locally for some reason~~

Edit: reference: PrismJS/prism#1400 (comment)

harryzcy · 2023-09-25T17:04:18Z

now I can't reproduce error TS2578: Unused "@ts-expect-error" directive. error locally...

argos-ci · 2023-10-06T12:33:56Z

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	🧿 Changes detected (Review)	37 changes	Oct 6, 2023, 5:14 PM

slorber · 2023-10-06T13:04:14Z

Seems to be working now

But our visual regression tests tool reports many unexpected changes to syntax highlighting:

https://app.argos-ci.com/meta-open-source/docusaurus/builds/247/60618995

Will investigate.
@carloskelly13 any idea what could be happening here?

slorber · 2023-10-06T13:05:04Z

packages/docusaurus-theme-classic/src/theme/prism-include-languages.ts

+    if (lang === 'php') {
+      // eslint-disable-next-line global-require
+      require('prismjs/components/prism-markup-templating.js');
+    }


wondering why do we need this now?

Not sure why it's not an issue previously, but the error is mentioned here: PrismJS/prism#1400 (comment). Without it, there's a TypeError: Cannot read property 'tokenizePlaceholders' of undefined

slorber · 2023-10-06T15:14:09Z

Looks like we have weird hydrations issues here:
https://deploy-preview-9316--docusaurus-2.netlify.app/docs/docusaurus-core

slorber · 2023-10-06T15:36:00Z

packages/docusaurus-theme-classic/src/theme/CodeBlock/Content/String.tsx

-          {...defaultProps}
+          prism={Prism}


I think this is the issue, we used the "vendored prism library" and should keep using it so passing a prism instance is not needed now. I'll remove it.

slorber · 2023-10-06T17:15:04Z

LGTM thanks 🎉 will be in Docusaurus v3

1. remove package-lock.json => reason package-lock.json is an automatically generated file that stores dependency information. This ensures a faster build process by eliminating the need to resolve dependencies every time you build your project 2. remove src/theme/SearchBar by https://github.com/praveenn77/docusaurus-lunr-search?tab=readme-ov-file#upgrading-from-docusaurus-v2-to-v3 3. update prismThemes by facebook/docusaurus#9316

chore: upgrade prism-react-renderer to v2

0b713f0

harryzcy requested review from slorber, lex111 and Josh-Cena as code owners September 17, 2023 03:29

facebook-github-bot added the CLA Signed Signed Facebook CLA label Sep 17, 2023

harryzcy added 5 commits September 16, 2023 23:55

chore: update usage of prism-react-renderer api

549fbb3

fix(website): use new prism-react-renderer api

f174bd7

fix: update prism import path

37ea8b0

fix: update function type and use prism-react-renderer exposed types

51d65df

fix: bug with prism-react-renderer

de2e168

The `prism` prop for Hightlight is declared as optional, but omitting it gives errors. So it's now passed in.

slorber added Argos Add this label to run UI visual regression tests. See argos.yml GH action. pr: breaking change Existing sites may not build successfully in the new version. Description contains more details. labels Sep 19, 2023

slorber requested changes Sep 19, 2023

View reviewed changes

harryzcy added 6 commits September 19, 2023 11:57

fix: revert version in examples

1ae1629

fix: revert less restrictive typing

42ae5fe

fix: typing for PrismThemeEntry

f7d1336

chore: bump react-live

59a8c79

fix: typing errors caused by react-live

05cbb63

docs: update website on theme usage

9e47fa0

harryzcy added 2 commits September 19, 2023 12:51

fix: missing closing quote

56fbd1b

chore: upgrade react-live again

000ee6d

fix: eslint rule that doesn't need to be disabled

f2874aa

slorber added this to the 3.0 milestone Sep 25, 2023

fix: pages build issue

3763ed5

harryzcy added 3 commits September 25, 2023 12:47

chore: Merge branch 'main' into prism-react-renderer-v2

5f7abda

fix: error TS2578: Unused "@ts-expect-error" directive

7b603e6

fix: ts-expect-error issue again

f4cac9e

slorber added 3 commits October 6, 2023 14:01

Merge branch 'main' into prism-react-renderer-v2

df94ec3

regen lockfile

e062e62

prism-react-renderer 2.1.0

4140168

slorber reviewed Oct 6, 2023

View reviewed changes

slorber added 3 commits October 6, 2023 17:37

Use vendored prism, remove prism props

6abdf22

Add missing prism languages

00c4947

add scss language

bcc6bdf

slorber changed the title ~~chore: upgrade prism-react-renderer to v2~~ chore: upgrade prism-react-renderer to v2, react-live to v4 Oct 6, 2023

slorber changed the title ~~chore: upgrade prism-react-renderer to v2, react-live to v4~~ chore: upgrade syntax highlighting dependencies, prism-react-renderer to v2, react-live to v4 Oct 6, 2023

slorber merged commit dceaae4 into facebook:main Oct 6, 2023
29 of 31 checks passed

slorber mentioned this pull request Oct 6, 2023

chore(live-code): replace with react-runner #6589

Closed

harryzcy deleted the prism-react-renderer-v2 branch October 6, 2023 21:28

JoshuaKGoldberg mentioned this pull request Oct 17, 2023

chore(deps): update dependency prism-react-renderer to v2 typescript-eslint/typescript-eslint#7427

Closed

1 task

This was referenced Oct 19, 2023

chore: v3.0.0-rc.0 release #9418

Merged

chore: v3.0.0-rc.1 release #9453

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: upgrade syntax highlighting dependencies, `prism-react-renderer` to v2, `react-live` to v4 #9316

chore: upgrade syntax highlighting dependencies, `prism-react-renderer` to v2, `react-live` to v4 #9316

harryzcy commented Sep 17, 2023 •

edited by slorber

netlify bot commented Sep 17, 2023 •

edited

github-actions bot commented Sep 17, 2023 •

edited

slorber left a comment •

edited

harryzcy commented Sep 19, 2023

slorber commented Sep 20, 2023

slorber commented Sep 20, 2023 •

edited

harryzcy commented Sep 20, 2023 •

edited

harryzcy commented Sep 25, 2023

argos-ci bot commented Oct 6, 2023 •

edited

slorber commented Oct 6, 2023

slorber Oct 6, 2023

harryzcy Oct 6, 2023 •

edited

slorber commented Oct 6, 2023

slorber Oct 6, 2023

slorber commented Oct 6, 2023

chore: upgrade syntax highlighting dependencies, prism-react-renderer to v2, react-live to v4 #9316

chore: upgrade syntax highlighting dependencies, prism-react-renderer to v2, react-live to v4 #9316

Conversation

harryzcy commented Sep 17, 2023 • edited by slorber

Breaking changes

prism-react-renderer v2

Theme API

Default languages

react-live v4

Motivation

Test Plan

Test links

Related issues/PRs

netlify bot commented Sep 17, 2023 • edited

✅ [V2]

github-actions bot commented Sep 17, 2023 • edited

⚡️ Lighthouse report for the deploy preview of this PR

slorber left a comment • edited

Choose a reason for hiding this comment

harryzcy commented Sep 19, 2023

slorber commented Sep 20, 2023

slorber commented Sep 20, 2023 • edited

harryzcy commented Sep 20, 2023 • edited

harryzcy commented Sep 25, 2023

argos-ci bot commented Oct 6, 2023 • edited

slorber commented Oct 6, 2023

slorber Oct 6, 2023

Choose a reason for hiding this comment

harryzcy Oct 6, 2023 • edited

Choose a reason for hiding this comment

slorber commented Oct 6, 2023

slorber Oct 6, 2023

Choose a reason for hiding this comment

slorber commented Oct 6, 2023

chore: upgrade syntax highlighting dependencies, `prism-react-renderer` to v2, `react-live` to v4 #9316

chore: upgrade syntax highlighting dependencies, `prism-react-renderer` to v2, `react-live` to v4 #9316

harryzcy commented Sep 17, 2023 •

edited by slorber

`prism-react-renderer` v2

`react-live` v4

netlify bot commented Sep 17, 2023 •

edited

github-actions bot commented Sep 17, 2023 •

edited

slorber left a comment •

edited

slorber commented Sep 20, 2023 •

edited

harryzcy commented Sep 20, 2023 •

edited

argos-ci bot commented Oct 6, 2023 •

edited

harryzcy Oct 6, 2023 •

edited