feat(many): migrate from npm to pnpm Phase 1 by balzss · Pull Request #2172 · instructure/instructure-ui

balzss · 2025-10-06T11:37:03Z

Summary

Implement Phase 1 of pnpm migration with workspace protocol and core tooling updates. Migrate from npm to pnpm v10.18.3 as the package manager. All packages now use the workspace:* protocol for internal dependencies, which pnpm automatically resolves to actual versions on publish.

Changes

Package Manager Configuration

Add pnpm-workspace.yaml defining workspace packages
Add .npmrc with pnpm configuration (hoisted node linker, strict peer deps)
Update lerna.json to use pnpm as npm client
Update root package.json with pnpm engines, overrides, and devDependencies
Update .gitignore for pnpm artifacts
Remove package-lock.json (replaced by pnpm-lock.yaml)

Workspace Dependencies

Convert all 94 internal @instructure/* dependencies from exact versions to workspace:*
Create scripts/convert-to-workspace-protocol.js for automated conversion

Build & Tooling

Update scripts/bootstrap.js to use pnpm and run builds sequentially
Update packages/ui-scripts/lib/commands/bump.js to use pnpm install
Update packages/ui-scripts/lib/utils/npm.js to use pnpm whoami
Fix babel-plugin-transform-imports for pnpm workspace module resolution
Fix generate-all-tokens for pnpm workspace package resolution
Add @types/react and jsdom to root devDependencies (were phantom dependencies)
Fix TypeScript type build and project references
Optimize scripts/clean.js for better performance:
- Parallelize deletions with async/await and Promise.all() (17% faster)
- Fix broken --nuke_node mode with native shell command (10-100x faster)
- Improves bootstrap time and fixes timeout issues when cleaning node_modules
Fix markdown hot reload in dev server:
- pnpm's module resolution prevents webpack-dev-server's onListening callback from firing
- Implement standalone markdown watcher using concurrently to run in parallel with webpack
- Add packages/docs/buildScripts/watch-markdown.mjs with chokidar file watching
- Update start:watch script to run markdown watcher alongside webpack bundle --watch
- Add concurrently dependency for parallel process management with colored output
- Markdown file changes now trigger hot reload during development

regression-test Workspace Decoupling

Change regression-test to use link: protocol instead of workspace overlap
Separate regression-test workspace (React 19) from main workspace (React 18)
Mirrors how external consumers import from built @instructure/ui bundle

CI/CD

Update all GitHub Actions workflows to use pnpm v10

Documentation

Update CLAUDE.md with pnpm commands throughout (tech stack, quick start, essential commands, workflows)
Update all contributor documentation with pnpm commands:
- docs/contributor-docs/dev-commands.md (complete command reference)
- docs/contributor-docs/release.md (release process)
- docs/contributor-docs/adding-icons.md
- docs/contributor-docs/codemods.md
- docs/contributor-docs/building-instui.md
- docs/contributor-docs/contributing.md
Update testing documentation:
- docs/testing/vitest-unit-testing.md
- docs/testing/cypress-component-testing.md
Update getting started guide:
- docs/getting-started/usage.md
Update package documentation:
- packages/ui-scripts/README.md (CLI reference)
- packages/docs/README.md
- regression-test/README.md
Add docs/contributor-docs/pnpm-migration-plan.md as comprehensive migration reference

Breaking Changes

None for package consumers.

For contributors: install pnpm and use pnpm commands instead of npm.

Test plan

npm install -g pnpm@latest
git checkout feat/pnpm-migration
rm -rf node_modules regression-test/node_modules && pnpm install
pnpm run bootstrap       # Verify TypeScript build succeeds
pnpm run dev             # Verify dev server and markdown hot reload work
pnpm run test:vitest     # Verify unit tests pass

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

github-actions · 2025-10-06T11:42:37Z

PR Preview Action v1.6.2
Preview removed because the pull request was closed.
2025-11-05 01:08 UTC

docs/contributor-docs/pnpm-migration-plan.md

Copilot

Pull Request Overview

Implements Phase 1 of pnpm migration with workspace protocol and core tooling updates. Migrate from npm to pnpm v10.18.3 as the package manager. All packages now use the workspace:* protocol for internal dependencies, which pnpm automatically resolves to actual versions on publish.

Package manager configuration with pnpm-workspace.yaml and .npmrc
Convert all 94 internal @instructure/* dependencies from exact versions to workspace:*
Update build & tooling scripts to use pnpm commands and fix workspace module resolution

Reviewed Changes

Copilot reviewed 171 out of 177 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pnpm-workspace.yaml	Define workspace packages configuration
lerna.json	Update to use pnpm as npm client
package.json	Add pnpm engines, overrides, devDependencies and update scripts
scripts/clean.js	Optimize performance with parallel deletions and native shell commands
scripts/bootstrap.js	Update to use pnpm and sequential builds
packages/*/package.json	Convert internal dependencies to workspace:* protocol
regression-test/*	Decouple workspace using link: protocol and update imports
babel-plugin-transform-imports	Fix for pnpm workspace module resolution
docs/*	Update documentation to use pnpm commands

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-14T18:14:52Z

regression-test/src/app/button/page.tsx


 export default function ButtonPage() {
-  const myElementRef = useRef<HTMLButtonElement>(null)
+  const myElementRef = useRef<any>(null)


The ref type should be more specific than any. Use HTMLButtonElement | null for better type safety.

Suggested change

const myElementRef = useRef<any>(null)

const myElementRef = useRef<HTMLButtonElement | null>(null)

Copilot · 2025-10-14T18:14:53Z

regression-test/src/app/button/page.tsx

+  ] as const
+  const sizes = ['small', 'medium', 'large'] as const


Consider defining these arrays outside the component to avoid recreation on each render, improving performance.

Copilot · 2025-10-14T18:14:53Z

regression-test/src/app/button/page.tsx

        ))}
      </div>
-      <Button renderIcon={IconAddLine}>Icon Button</Button>
+      <Button renderIcon={<IconAddLine />}>Icon Button</Button>


The icon should be passed as a component reference rather than an element to allow the Button component to control rendering. Use renderIcon={IconAddLine} instead.

Suggested change

<Button renderIcon={<IconAddLine />}>Icon Button</Button>

<Button renderIcon={IconAddLine}>Icon Button</Button>

matyasf

pnpm run dev runs, but the docs app does not load for me (its stuck in loading, like it would be blocked by a firewall
there are a couple of npm references left, e.g. "build:watch": "npm run ts:check is in lots of places
Please double check ui-scrips scripts, e.g. publish.js, tag.js still uses npm, deprecate, dangerfile.js

packages/__docs__/package.json

matyasf · 2025-10-15T09:40:20Z

packages/babel-plugin-transform-imports/lib/index.js

    if (matches && matches[1]) {
      const packageName = matches[1]
-      const sourceIndex = require.resolve(packageName)
+      // For pnpm workspaces, resolve from the project root to find workspace packages


Why is this needed with pnpm?

regression-test/src/app/view/page.tsx

matyasf · 2025-10-15T09:59:04Z

scripts/clean.js

+  if (args.length > 0 && args[0] === '--nuke_node') {
+    // eslint-disable-next-line no-console
+    console.info('Deleting node_modules recursively...')
+    removeNodeModules()
+  }


Is this still needed? Can there be node_modules folders in packages?

balzss · 2025-10-15T15:27:36Z

pnpm run dev runs, but the docs app does not load for me (its stuck in loading, like it would be blocked by a firewall

this turned out to be a harder issue than anticipated, i think something happened with webpack processing the symlinked files that pnpm uses which causes an infinite loop, i'm investigating...

matyasf · 2025-10-28T13:25:00Z

There are still some npm references, search the codebase for 'npm and "npm. They are in publish.js, deprecarte.js, tag.js

matyasf

See my comments. I've tested most scripts, all seem to work, nice job!

joyenjoyer

great job, I tried most of the commands, they work well
please check the ui-scripts folder for npm and change those too

Copilot

Pull Request Overview

Copilot reviewed 179 out of 185 changed files in this pull request and generated 8 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-10-30T10:00:08Z

scripts/clean.js

+    execSync(
+      'find . -name "node_modules" -type d -prune -exec rm -rf {} + 2>/dev/null || true',
+      { stdio: 'inherit' }
+    )


The shell command uses unescaped user input from process.cwd() context and relies on shell globbing. On Windows or with special characters in paths, this could fail or behave unexpectedly. Consider using Node.js APIs instead of shell commands for cross-platform reliability.

Copilot · 2025-10-30T10:00:09Z

packages/ui-icons/package.json

-    "prepare-build": "npm run build-icons",
-    "build-icons": "ui-scripts build-icons --svgoConfig svgo.config.js --config icons.config.js",
+    "prepare-build": "pnpm run build-icons",
+    "build-icons": "pnpm exec ui-scripts build-icons --skipOptimization --config icons.config.js",


The --skipOptimization flag is used by default with a TODO comment indicating this is temporary. Consider creating a separate script for optimized builds (like build-icons:optimize) and making the default behavior explicit rather than temporary.

Copilot · 2025-10-30T10:00:09Z

packages/babel-plugin-transform-imports/lib/index.js

+            // If any transform fails, we can't safely transform this import
+            allTransformsSucceeded = false
          }


When a transform fails, allTransformsSucceeded is set to false but the loop continues processing remaining imports. This could lead to partial transforms in the memberTransforms array that are later discarded. Consider breaking early or restructuring to avoid unnecessary work.

Copilot · 2025-10-30T10:00:09Z

package.json

+      "react": "^18",
+      "react-dom": "^18",
+      "@types/react": "^18"


The pnpm overrides use caret ranges (^18) which allow minor and patch updates, while devDependencies specify exact versions (18.3.1). This inconsistency could lead to version mismatches. Consider using exact versions in overrides to match the devDependencies, or document why flexible versions are needed.

Suggested change

"react": "^18",

"react-dom": "^18",

"@types/react": "^18"

"react": "18.3.1",

"react-dom": "18.3.1",

"@types/react": "18.3.26"

Copilot · 2025-10-30T10:00:10Z

packages/ui-scripts/lib/build/generate-all-tokens.js

+        const packageMatch = sourceTokens.match(
+          /^(@instructure\/)?([\w-]+)(.*)$/
+        )


[nitpick] The regex pattern [\w-]+ matches word characters and hyphens, but doesn't account for scoped package names with slashes or special characters that might exist in subpaths. Consider a more explicit pattern or validate the expected format in the error message.

Copilot · 2025-10-30T10:00:10Z

regression-test/package.json

  },
  "dependencies": {
-    "instructure-ui": "file:../packages",
+    "@instructure/ui": "link:../packages/ui",


[nitpick] The regression-test uses link: protocol instead of workspace:* like other packages. While this may be intentional for the separate workspace, consider documenting why a different protocol is used here compared to the main workspace pattern.

Copilot · 2025-10-30T10:00:10Z

packages/__docs__/buildScripts/watch-markdown.mjs

+function debouncedProcess(filePath) {
+  const now = Date.now()
+  const lastProcessed = processedFiles.get(filePath)
+
+  if (lastProcessed && now - lastProcessed < DEBOUNCE_MS) {
+    return // Skip if file was processed recently
+  }


The debounce implementation doesn't clear old entries from the processedFiles Map, which will grow unbounded during long-running watch sessions. Consider periodically cleaning up entries older than DEBOUNCE_MS or using a proper debounce library.

Copilot · 2025-10-30T10:00:11Z

scripts/clean.js


-const fs = require('fs')
+const fs = require('fs').promises
+const fsSync = require('fs')


Unused variable fsSync.

Implement pnpm migration with workspace protocol and core tooling updates: Configuration: - Add pnpm-workspace.yaml defining workspace packages - Add .npmrc with pnpm configuration (hoisted node linker, strict peer deps) - Update lerna.json to use pnpm as npm client - Update root package.json with pnpm engines, overrides, and devDependencies - Update .gitignore for pnpm artifacts - Delete package-lock.json (replaced by pnpm-lock.yaml) Workspace Dependencies: - Convert all internal @instructure/* dependencies from exact versions to workspace:* - Update 94 package.json files across all packages - Create scripts/convert-to-workspace-protocol.js for automated conversion Build Tooling: - Update scripts/bootstrap.js to use pnpm and run builds sequentially - Update packages/ui-scripts/lib/commands/bump.js to use pnpm install - Update packages/ui-scripts/lib/utils/npm.js to use pnpm whoami - Fix babel-plugin-transform-imports for pnpm workspace module resolution - Fix generate-all-tokens for pnpm workspace package resolution - Optimize clean script performance - Restore markdown hot reload in dev server Regression Test App (npm): - Keep regression-test using npm to simulate external package consumption - Change @instructure/ui dependency to file: protocol (from link:) - Remove pnpm-lock.yaml and pnpm-workspace.yaml - Generate package-lock.json with npm install - Update .github/workflows/visual-regression.yml to use npm commands - Update README.md with npm commands and explanation - Add .npmrc explaining npm-only approach Documentation: - Update all internal npm references to pnpm across the codebase 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>