feat(many): migrate from npm to pnpm Phase 1

Implement Phase 1 of 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 10.18.3 as packageManager
- Update engines requirement to pnpm >=10
- 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

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

CI/CD:
- Update all GitHub Actions workflows to use pnpm version 10
- Add pnpm/action-setup@v4
- Update caching to use pnpm lock files
- Configure registry-url for npm publishing
- Fix visual-regression.yml: use pnpm workspace protocol instead of global linking
- Fix visual-regression.yml: explicitly install Cypress binary before tests
- Add Cypress binary caching with lockfile hash (cypress-io/github-action#1138)

TypeScript References:
- Fix TypeScript project references in 10 packages (ui-drawer-layout, ui-expandable,
  ui-file-drop, ui-instructure, ui-link, ui-number-input, ui-popover, ui-radio-input,
  ui-text-area, ui-text-input)
- Add missing tsconfig.build.json references to match package.json dependencies

Regression Test Updates:
- Update regression-test app to use @instructure/ui meta package
- Convert all component imports to use single import from @instructure/ui
- Update InstUISettingsProvider import path

Documentation:
- Add pnpm-migration-plan.md with complete migration strategy
- Add pnpm-phase1-test-plan.md with testing procedures
- Add pnpm-phase1-investigation.md analyzing implementation
- Update building-instui.md and contributing.md with pnpm instructions

Notes:
- All Babel builds and token generation working successfully with pnpm
- Cypress binary installation resolved by explicit `cypress install` step
- Phase 2 will focus on fixing phantom dependencies and removing workarounds

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: balzss

.github/workflows/deploy.yml

@@ -13,11 +13,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - name: Install Node 22
         uses: actions/setup-node@v4
         with:
           node-version: '22'
-      - run: npm ci && npm run bootstrap
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile && pnpm run bootstrap
       - name: Set build directory and deployment path based on branch
         id: set-build-dir
         run: |
@@ -37,7 +39,7 @@ jobs:
               ;;
           esac
       - name: Build docs-app
-        run: npm run build:docs
+        run: pnpm run build:docs
       - name: Deploy to GitHub Pages
         uses: JamesIves/github-pages-deploy-action@v4
         with:
@@ -57,13 +59,15 @@ jobs:
     if: github.ref == 'refs/heads/master'
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - name: Install Node 22
         uses: actions/setup-node@v4
         with:
           node-version: '22'
-      - run: npm ci && npm run bootstrap
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile && pnpm run bootstrap
       - name: Build docs-app
-        run: npm run build:docs
+        run: pnpm run build:docs
       - name: Deploy to GitHub Pages
         uses: JamesIves/github-pages-deploy-action@v4
         with:

.github/workflows/manual-release-from-pr.yml

@@ -8,20 +8,21 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
-          cache: 'npm'
+          cache: 'pnpm'
       - name: Install packages
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: Set up project
-        run: npm run bootstrap
+        run: pnpm run bootstrap
       - name: Release to NPM
         env:
           NPM_TOKEN: ${{secrets.NPM_TOKEN}}
           NPM_EMAIL: ${{secrets.NPM_EMAIL}}
           NPM_USERNAME: ${{secrets.NPM_USERNAME}}
-        run: npm run release -- --prRelease
+        run: pnpm run release -- --prRelease
       - name: Get commit message
         run: | # puts the first line of the last commit message to the commmit_message env var
           echo "commmit_message=$(git log --format=%B -n 1 ${{ github.event.after }} | head -n 1)" >> $GITHUB_ENV

.github/workflows/manual-release-to-npm.yml

@@ -8,20 +8,22 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - uses: pnpm/action-setup@v4
       - name: Install Node 22
         uses: actions/setup-node@v4
         with:
           node-version: '22'
+          cache: 'pnpm'
       - name: Install packages
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: Set up project
-        run: npm run bootstrap
+        run: pnpm run bootstrap
       - name: Release to NPM
         env:
           NPM_TOKEN: ${{secrets.NPM_TOKEN}}
           NPM_EMAIL: ${{secrets.NPM_EMAIL}}
           NPM_USERNAME: ${{secrets.NPM_USERNAME}}
-        run: npm run release
+        run: pnpm run release
       - name: Get commit message
         run: | # puts the first line of the last commit message to the commmit_message env var
           echo "commmit_message=$(git log --format=%B -n 1 ${{ github.event.after }} | head -n 1)" >> $GITHUB_ENV

.github/workflows/pr-validation.yml

@@ -8,46 +8,51 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
-          cache: 'npm'
+          cache: 'pnpm'
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: Bootstrap project
-        run: npm run bootstrap
+        run: pnpm run bootstrap
       - name: Lint commits
-        run: npm run lint:commits
+        run: pnpm run lint:commits
       - name: Lint code
-        run: npm run lint:changes
+        run: pnpm run lint:changes
   vitest-tests:
     name: Vitest unit tests
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
-          cache: 'npm'
+          cache: 'pnpm'
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: Bootstrap project
-        run: npm run bootstrap
+        run: pnpm run bootstrap
       - name: Run vitest unit tests
-        run: npm run test:vitest
+        run: pnpm run test:vitest
   cypress:
     name: Cypress component tests
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
-          cache: 'npm'
+          cache: 'pnpm'
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
+      - name: Install Cypress binary
+        run: npx cypress install
       - name: Bootstrap project
-        run: npm run bootstrap
+        run: pnpm run bootstrap
       - name: Run Cypress components tests
-        run: npm run cy:component
+        run: pnpm run cy:component
 

.github/workflows/preview.yml

@@ -14,15 +14,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - name: Install Node 22
         uses: actions/setup-node@v4
         with:
           node-version: '22'
-      - name: Npm install and bootstrap
-        run: npm ci && npm run bootstrap
+          cache: 'pnpm'
+      - name: Install and bootstrap
+        run: pnpm install --frozen-lockfile && pnpm run bootstrap
         if: github.event.action != 'closed' # don't run install and bootstrap unnecessarily when pr is closed
       - name: Build docs-app
-        run: npm run build:docs
+        run: pnpm run build:docs
         if: github.event.action != 'closed'
       - uses: rossjrw/pr-preview-action@v1
         with:

.github/workflows/release.yml

@@ -11,22 +11,23 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
-          cache: 'npm'
+          cache: 'pnpm'
       - name: Install packages.
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: Set up project.
-        run: npm run bootstrap
+        run: pnpm run bootstrap
       - name: Run tests.
-        run: USE_REACT_STRICT_MODE=0 npm run test:vitest
+        run: USE_REACT_STRICT_MODE=0 pnpm run test:vitest
       - name: Release to NPM
         env:
           NPM_TOKEN: ${{secrets.NPM_TOKEN}}
           NPM_EMAIL: ${{secrets.NPM_EMAIL}}
           NPM_USERNAME: ${{secrets.NPM_USERNAME}}
-        run: npm run release
+        run: pnpm run release
   tag:
     needs: release
     if: "startsWith(github.event.head_commit.message, 'chore(release)')"

.github/workflows/visual-regression.yml

@@ -13,18 +13,32 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+      - name: Cache Cypress binary
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/Cypress
+          key: ${{ runner.os }}-cypress-${{ hashFiles('regression-test/pnpm-lock.yaml') }}
       - name: Build InstUI
-        run: npm ci && npm run bootstrap
-      - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile && pnpm run bootstrap
+      - name: Install regression-test dependencies
+        run: pnpm install --frozen-lockfile
+        working-directory: regression-test
+      - name: Install Cypress binary
+        run: pnpm exec cypress install
         working-directory: regression-test
       - name: Run Cypress tests
         uses: cypress-io/github-action@v6
         env:
           ELECTRON_EXTRA_LAUNCH_ARGS: "--remote-debugging-port=9222"
         with:
-          build: npm run build
-          start: npm start
+          install: false
+          build: pnpm run build
+          start: pnpm start
           working-directory: regression-test
       - name: Upload cypress artifact for chromatic
         uses: actions/upload-artifact@v4
@@ -42,11 +56,15 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - name: Install dependencies
-        run: npm ci
+          cache: 'pnpm'
+      - name: Build InstUI
+        run: pnpm install --frozen-lockfile && pnpm run bootstrap
+      - name: Install regression-test dependencies
+        run: pnpm install --frozen-lockfile
         working-directory: regression-test
       - name: Download Cypress test results
         uses: actions/download-artifact@v4

.gitignore

@@ -1,5 +1,6 @@
 node_modules/
 npm-debug.log
+pnpm-debug.log
 lerna-debug.log
 ./build-storybook.log
 coverage/
@@ -9,10 +10,10 @@ __build__
 .idea
 .DS_Store
 .viminfo
-.npmrc
 .env
 .env.test
 .tmp/
+.pnpm-store/
 
 tsconfig.build.tsbuildinfo
 
@@ -31,3 +32,6 @@ tsconfig.build.tsbuildinfo
 .claude/commands/*
 !.claude/commands/commit.md
 !.claude/commands/pr.md
+
+# Playwright MCP
+.playwright-mcp

.npmrc

@@ -0,0 +1,13 @@
+# Strict peer dependencies (recommended)
+auto-install-peers=false
+strict-peer-dependencies=true
+
+# Workspace protocol
+link-workspace-packages=true
+
+# Use hoisted node linker initially for compatibility
+node-linker=hoisted
+
+# Can enable later for stricter isolation:
+# node-linker=isolated
+# shamefully-hoist=false

CLAUDE.md

@@ -12,7 +12,7 @@ InstUI is a React component library and design system. **Lerna 8 monorepo** with
   - Example: https://instructure.design/markdowns/Alert.md
   - Example: https://instructure.design/markdowns/Button.md
 
-**Tech Stack:** Node.js >=22, npm, React 18.3.1+, TypeScript 5.8.3, Emotion (CSS-in-JS), Vitest, Cypress, Chromatic
+**Tech Stack:** Node.js >=22, pnpm, React 18.3.1+, TypeScript 5.8.3, Emotion (CSS-in-JS), Vitest, Cypress, Chromatic
 
 ## Repository Structure
 
@@ -38,8 +38,8 @@ InstUI is a React component library and design system. **Lerna 8 monorepo** with
 ## Quick Start
 
 ```bash
-npm run bootstrap  # First time setup (clean, build icons, compile, generate tokens)
-npm run dev        # Start dev server at http://localhost:9090
+pnpm run bootstrap  # First time setup (clean, build icons, compile, generate tokens)
+pnpm run dev        # Start dev server at http://localhost:9090
 ```
 
 Most changes hot-reload automatically when dev server is running.
@@ -48,20 +48,20 @@ Most changes hot-reload automatically when dev server is running.
 
 ```bash
 # Development
-npm run dev          # Dev server (http://localhost:9090)
-npm run build:types  # Build TypeScript declarations
+pnpm run dev          # Dev server (http://localhost:9090)
+pnpm run build:types  # Build TypeScript declarations
 
 # Testing
-npm run test:vitest  # Unit tests
-npm run cy:component # Cypress component tests
+pnpm run test:vitest  # Unit tests
+pnpm run cy:component # Cypress component tests
 
 # Linting
-npm run lint:fix     # Auto-fix linting issues
-npm run ts:check     # TypeScript references check
+pnpm run lint:fix     # Auto-fix linting issues
+pnpm run ts:check     # TypeScript references check
 
 # Troubleshooting
-npm run clean && npm run bootstrap       # Fix build issues
-npm run clean-node && npm install        # Nuclear option (removes all node_modules)
+pnpm run clean && pnpm run bootstrap       # Fix build issues
+pnpm run clean-node && pnpm install        # Nuclear option (removes all node_modules)
 ```
 
 ## Code Style
@@ -102,7 +102,7 @@ npm run clean-node && npm install        # Nuclear option (removes all node_modu
 1. Find component in `/packages/ui-[name]/src/[Component]/`
 2. Check Component README for API details
 3. Make changes
-4. Run tests: `npm run test:vitest`
+4. Run tests: `pnpm run test:vitest`
 5. Update README if the functionality has changed (e.g., a new prop was added)
 6. Use `/commit` to create commit
 
@@ -150,13 +150,13 @@ All components **MUST**:
 ### Running Tests
 
 ```bash
-npm run test:vitest  # Unit tests
-npm run cy:component # Cypress tests
+pnpm run test:vitest  # Unit tests
+pnpm run cy:component # Cypress tests
 
 # Visual regression tests (in regression-test directory)
 cd regression-test
-npm run dev              # Start at localhost:3000
-npm run cypress-chrome   # Run with GUI
+pnpm run dev              # Start at localhost:3000
+pnpm run cypress-chrome   # Run with GUI
 ```
 
 ### Adding Visual Regression Test