Migrate Perseus to pnpm (#2202)

## Summary:

This PR migrates this repo from `yarn` to [pnpm](pnpm.io). The version of Yarn we are using is very outdated and is no longer supported. Khan Academy has made an engineering-wide decision to adopt pnpm as its "package manager of choice" and so let's adopt!

Notable changes:

  * Use `workspace:` syntax for in-repo dependencies
  * Use `catalog:` syntax for peer/dev dependencies (easier "global" upgrade of these) - and Github _just_ added support for `catalog:` support Dependabot [_yesterday_](https://github.blog/changelog/2025-02-04-dependabot-now-supports-pnpm-workspace-catalogs-ga/)!!
  * Build system is simplified because we don't have to worry about build order
  * 

Issue: LEMS-2825

## Test plan:

`pnpm build`
`pnpm dev`
`pnpm start` # storybook
`pnpm cypress:ci`

Author: jeremywiebe

Reviewers: mark-fitzgerald, jeremywiebe, benchristel, handeyeco, jeresig, jandrade, kevinb-khan

Required Reviewers:

Approved By: mark-fitzgerald, handeyeco, benchristel

Checks: ✅ Publish npm snapshot (ubuntu-latest, 20.x), ✅ Check for .changeset entries for all changed files (ubuntu-latest, 20.x), ✅ Cypress (ubuntu-latest, 20.x), ✅ Lint, Typecheck, Format, and Test (ubuntu-latest, 20.x), ✅ Publish Storybook to Chromatic (ubuntu-latest, 20.x), ✅ Check builds for changes in size (ubuntu-latest, 20.x)

Pull Request URL: #2202

Author: jeremywiebe

.changeset/empty-lemons-agree.md

@@ -0,0 +1,19 @@
+---
+"perseus-build-settings": minor
+"@khanacademy/perseus-dev-ui": minor
+"@khanacademy/kas": minor
+"@khanacademy/keypad-context": minor
+"@khanacademy/kmath": minor
+"@khanacademy/math-input": minor
+"@khanacademy/perseus": minor
+"@khanacademy/perseus-core": minor
+"@khanacademy/perseus-editor": minor
+"@khanacademy/perseus-linter": minor
+"@khanacademy/perseus-score": minor
+"@khanacademy/pure-markdown": minor
+"@khanacademy/simple-markdown": minor
+---
+
+Tooling:
+
+- Switching to `pnpm`.

.devcontainer/devcontainer.json

@@ -12,7 +12,7 @@
 	"forwardPorts": [6006],
 
 	// Use 'postCreateCommand' to run commands after the container is created.
-	"postCreateCommand": "yarn install"
+	"postCreateCommand": "pnpm install"
 
 	// Configure tool-specific properties.
 	// "customizations": {},

.github/actions/shared-node-cache/action.yml

@@ -12,12 +12,17 @@ inputs:
 runs:
     using: "composite"
     steps:
-        - name: Set up node
+        - uses: pnpm/action-setup@v4
+          name: Install pnpm
+          with:
+              run_install: false
+
+        - name: Use Node.js ${{ inputs.node-version }}
           uses: actions/setup-node@v4
           with:
               node-version: ${{ inputs.node-version }}
-              cache: yarn
+              cache: pnpm
 
-        - name: yarn install
+        - name: pnpm install
           shell: sh
-          run: yarn install
+          run: pnpm install ---frozen-lockfile

.github/workflows/maintenance.yml

@@ -47,13 +47,13 @@ jobs:
 
                       ## Reviewing notes:
 
-                      There should only be changes to the `yarn.lock` file in
+                      There should only be changes to the `pnpm-lock.yaml` file in
                       this PR. Check that there is only 1 `caniuse-lite` package
-                      reference in the `yarn.lock` file (the intent of this
+                      reference in the `pnpm-lock.yaml` file (the intent of this
                       update is to ensure that `caniuse-lite` is on the latest
                       version and that there aren't multiple, conflicting
                       versions that different tools might see).
 
                       If everything looks fine, please approve this PR and then
-                      land it (either with the Big Green Merge Button ™️ or by
+                      land it (either with the Big Green Merge Button™️ or by
                       using `git land <this pr #>` in a terminal).

.github/workflows/node-ci.yml

@@ -35,11 +35,17 @@ jobs:
               with:
                   fetch-depth: 0
 
+            - uses: pnpm/action-setup@v4
+              name: Install pnpm
+              with:
+                  run_install: false
+
             - name: Force Node version
               uses: actions/setup-node@v4
               with:
                   node-version: ${{ matrix.node-version }}
-                  cache: yarn
+                  # Note that we don't specify 'cache: pnpm' here because we
+                  # don't install node_modules in this workflow/job!
 
             - name: Get changed files
               uses: Khan/actions@get-changed-files-v2
@@ -60,7 +66,7 @@ jobs:
                   ssh-private-key: ${{ secrets.KHAN_ACTIONS_BOT_SSH_PRIVATE_KEY }}
 
             - name: Verify changeset entries
-              uses: Khan/[email protected]
+              uses: Khan/actions@check-for-changeset-v1
               with:
                   changed_files: ${{ steps.match.outputs.filtered }}
 
@@ -86,55 +92,55 @@ jobs:
 
             - name: Check formatting
               run: |
-                  yarn -s prettier --check .
+                  pnpm prettier --check .
 
             - id: js-files
               name: Find .js(x)/.ts(x) changed files
               uses: Khan/actions@filter-files-v1
               with:
                   changed-files: ${{ steps.changed.outputs.files }}
                   extensions: ".js,.jsx,.ts,.tsx"
-                  files: "yarn.lock"
+                  files: "pnpm-lock.yaml"
 
             - id: eslint-reset
               uses: Khan/actions@filter-files-v1
               name: Files that would trigger a full eslint run
               with:
                   changed-files: ${{ steps.changed.outputs.files }}
-                  files: ".eslintrc.js,package.json,yarn.lock,.eslintignore"
+                  files: ".eslintrc.js,package.json,pnpm-lock.yaml,.eslintignore"
 
             # Linting / type checking
             - name: Eslint
               uses: Khan/actions@full-or-limited-v0
               with:
                   full-trigger: ${{ steps.eslint-reset.outputs.filtered }}
-                  full: yarn lint packages
+                  full: pnpm lint packages
                   limited-trigger: ${{ steps.js-files.outputs.filtered }}
-                  limited: yarn lint {}
+                  limited: pnpm lint {}
 
             - name: Typecheck
               if: (success() || failure()) && steps.js-files.outputs.filtered != '[]'
-              run: yarn typecheck
+              run: pnpm typecheck
 
             - name: Build types
               if: (success() || failure()) && steps.js-files.outputs.filtered != '[]'
-              run: yarn build:types
+              run: pnpm build:types
 
             # Run tests for our target matrix
             - id: jest-reset
               uses: Khan/actions@filter-files-v1
               name: Files that would trigger a full jest run
               with:
                   changed-files: ${{ steps.changed.outputs.files }}
-                  files: "jest.config.js,package.json,yarn.lock,test.config.js,test.transform.js"
+                  files: "jest.config.js,package.json,pnpm-lock.yaml,test.config.js,test.transform.js"
 
             - name: Jest
               uses: Khan/actions@full-or-limited-v0
               with:
                   full-trigger: ${{ steps.jest-reset.outputs.filtered }}
-                  full: yarn jest
+                  full: pnpm jest
                   limited-trigger: ${{ steps.js-files.outputs.filtered }}
-                  limited: yarn jest --passWithNoTests --findRelatedTests {}
+                  limited: pnpm jest --passWithNoTests --findRelatedTests {}
 
             # We use STOPSHIP internally to mark code that's not safe to go live yet.
             # We use an if block because we want to return the exact inverse of what
@@ -153,13 +159,20 @@ jobs:
             - name: Checking out latest commit
               uses: actions/checkout@v4
 
+            # MUST be before we install node_modules as that depends on finding
+            # Cypress binaries in this cache!
+            - uses: actions/cache@v4
+              with:
+                  path: ~/.cache/Cypress
+                  key: cypress-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+
             - name: Install & cache node_modules
               uses: ./.github/actions/shared-node-cache
               with:
                   node-version: ${{ matrix.node-version }}
 
             - name: Run tests
-              run: yarn cypress:ci
+              run: pnpm cypress:ci
 
             - name: Upload Screenshots
               uses: actions/upload-artifact@v4
@@ -219,6 +232,7 @@ jobs:
               uses: actions/checkout@v4
               with:
                   fetch-depth: "0"
+
             - name: Ensure main branch is available
               run: |
                   REF=$(git rev-parse HEAD)
@@ -301,7 +315,7 @@ jobs:
 
                       Example:
                       ```sh
-                      yarn add @khanacademy/perseus@${{
+                      pnpm add @khanacademy/perseus@${{
                       steps.publish-snapshot.outputs.npm_snapshot_tag }}
                       ```
 

.github/workflows/release.yml

@@ -48,7 +48,7 @@ jobs:
 
             - name: Build Storybook
               # Generate a static version of storybook inside "storybook-static/"
-              run: yarn build-storybook
+              run: pnpm build-storybook
 
             - name: Deploy to GitHub pages
               uses: JamesIves/[email protected]
@@ -62,7 +62,7 @@ jobs:
               id: changesets
               uses: changesets/action@v1
               with:
-                  publish: yarn publish:ci
+                  publish: pnpm publish:ci
               env:
                   # We use a Personal Access Token here rather than the GITHUB_TOKEN
                   # so that it will trigger our other actions. The token has to be on

.prettierignore

@@ -27,7 +27,8 @@
 .nvmrc
 .prettierignore
 LICENSE
-yarn.lock
+pnpm-lock.yaml
+pnpm-workspace.yaml
 
 coverage/
 docs/

.storybook/main.ts

@@ -1,4 +1,4 @@
-import viteConfig from "../dev/vite.config";
+import viteConfig from "../vite.config";
 import {mergeConfig} from "vite";
 
 import type {StorybookConfig} from "@storybook/react-vite";
@@ -59,6 +59,11 @@ const config: StorybookConfig = {
     viteFinal: async (config, {configType}) => {
         return mergeConfig(config, {
             ...viteConfig,
+            define: {
+                // This is used to determine if we are running in a
+                // Dev/Storybook environment.
+                "process.env.STORYBOOK": "true",
+            },
             build: {
                 // Vite 5 has a bug with how it builds `url(data: )` urls when
                 // it inlines SVGs. Given this is mostly used for static
@@ -72,7 +77,7 @@ const config: StorybookConfig = {
             },
             // Fix from: https://github.com/storybookjs/storybook/issues/25256#issuecomment-1866441206
             assetsInclude: ["/sb-preview/runtime.js"],
-            plugins: [...viteConfig.plugins, lessWrapper],
+            plugins: [...(viteConfig.plugins ?? []), lessWrapper],
         });
     },
     staticDirs: ["../static"],

.storybook/preview.tsx

@@ -1,9 +1,11 @@
 import * as React from "react";
 import {color} from "@khanacademy/wonder-blocks-tokens";
 import {RenderStateRoot} from "@khanacademy/wonder-blocks-core";
-import {Dependencies} from "@khanacademy/perseus";
 
-import {DependenciesContext} from "../packages/perseus/src/dependencies";
+import {
+    setDependencies,
+    DependenciesContext,
+} from "../packages/perseus/src/dependencies";
 import {
     storybookTestDependencies,
     storybookDependenciesV2,
@@ -14,7 +16,7 @@ import type {Preview} from "@storybook/react";
 // IMPORTANT: This code runs ONCE per story file, not per story within that file.
 // If you want code to run once per story, see `StorybookWrapper`.
 
-Dependencies.setDependencies(storybookTestDependencies);
+setDependencies(storybookTestDependencies);
 
 const preview: Preview = {
     // These decorators apply to all stories, both inside and outside the

README.md

@@ -18,23 +18,23 @@ This repo is a constellation of sub-repos for showing exercise content. Please s
 ### Prerequisites
 
 - [Node.js v20](https://nodejs.org/en/blog/announcements/v20-release-announce)
-- [Yarn](https://yarnpkg.com/lang/en/docs/install/)
+- [pnpm](https://pnpm.io/)
 
 ### Installation
 
 To install Perseus, you need to run the following commands:
 
-#### `yarn`
+#### `pnpm install`
 
 Installs project dependencies and tooling
 
 ### Using Storybook
 
-The components and widgets of Perseus are developed using [Storybook](https://github.com/storybookjs/storybook). After you clone the project and get dependencies installed, the next step is to start storybook by running `yarn storybook`. This will start a server and give you a playground to use each component.
+The components and widgets of Perseus are developed using [Storybook](https://github.com/storybookjs/storybook). After you clone the project and get dependencies installed, the next step is to start storybook by running `pnpm storybook`. This will start a server and give you a playground to use each component.
 
 ### Using Changesets
 
-We use [changesets](https://github.com/changesets/changesets) to help manage our versioning/releases. Before pushing a new PR, add a changeset by running `yarn changeset`. Commit and submit that with the PR.
+We use [changesets](https://github.com/changesets/changesets) to help manage our versioning/releases. Before pushing a new PR, add a changeset by running `pnpm changeset`. Commit and submit that with the PR.
 
 ### Updating Dependencies
 
@@ -53,13 +53,13 @@ cd packages/perseus-editor
 2. Run the following command to update the dev dependencies and the peer dependencies.
 ```
 // All dependencies
-yarn add --dev [dependency name]
+pnpm add --dev [dependency name]
 // Include this too if webapp is using this dependency
-yarn add --peer [dependency name]
+pnpm add --peer [dependency name]
 
 // Example
-yarn add --dev @khanacademy/wonder-blocks-button
-yarn add --peer @khanacademy/wonder-blocks-button
+pnpm add --dev @khanacademy/wonder-blocks-button
+pnpm add --peer @khanacademy/wonder-blocks-button
 ```
 
 ## Contributing
@@ -79,14 +79,14 @@ Perseus is a monorepo - a single repository that ships multiple npm packages. Ge
 3. ☢️ We don’t use deploy branches in Perseus
 4. Start a dev server
 
-    a. `yarn start` will start [Storybook](https://storybook.js.org/) on [localhost:6006](http://localhost:6006)
+    a. `pnpm start` will start [Storybook](https://storybook.js.org/) on [localhost:6006](http://localhost:6006)
 
-    b. `yarn dev` will start the custom Dev UI on
+    b. `pnpm dev` will start the custom Dev UI on
     [localhost:5173](http://localhost:5173/)
 
 5. Do stuff
-6. `yarn test` will run [Jest](https://jestjs.io/)/[RTL](https://testing-library.com/docs/react-testing-library/intro/) tests; `yarn cypress` will run [Cypress](https://www.cypress.io/) tests
-7. `yarn changeset` will walk you through creating a [changeset](https://github.com/changesets/changesets) (we generally stick to [semver](https://semver.org/))
+6. `pnpm test` will run [Jest](https://jestjs.io/)/[RTL](https://testing-library.com/docs/react-testing-library/intro/) tests; `pnpm cypress` will run [Cypress](https://www.cypress.io/) tests
+7. `pnpm changeset` will walk you through creating a [changeset](https://github.com/changesets/changesets) (we generally stick to [semver](https://semver.org/))
 8. ☢️ Empty changesets should be considered an exception to the rule and should generally be avoided
 9. `git add` and `git commit`
 10. `git pull-request` will walk you through creating a pull request