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

cypress/webpack.config.cjs

@@ -1,9 +1,62 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 const path = require('path')
+const fs = require('fs')
+
+// Generate aliases for all @instructure/* workspace packages
+// This is needed because Cypress tests run from the root workspace
+// and need to resolve workspace package imports during testing
+function getWorkspaceAliases() {
+  const packagesDir = path.resolve(__dirname, '../packages')
+  const packages = fs.readdirSync(packagesDir)
+  const aliases = {}
+
+  packages.forEach((pkg) => {
+    const pkgPath = path.join(packagesDir, pkg)
+    if (fs.statSync(pkgPath).isDirectory()) {
+      const pkgJsonPath = path.join(pkgPath, 'package.json')
+      if (fs.existsSync(pkgJsonPath)) {
+        const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'))
+        const pkgName = pkgJson.name
+        if (pkgName && pkgName.startsWith('@instructure/')) {
+          // Alias package name to its source directory
+          aliases[pkgName] = pkgPath
+          // Also alias deep imports (e.g., '@instructure/ui-button/src/...')
+          aliases[`${pkgName}/src`] = path.join(pkgPath, 'src')
+        }
+      }
+    }
+  })
+
+  return aliases
+}
 
 module.exports = {
   mode: 'development',
   resolve: {
     extensions: ['.ts', '.tsx', '.js'],
+    alias: getWorkspaceAliases(),
     fallback: {
       fs: false,
       module: false,
@@ -20,4 +73,4 @@ module.exports = {
       }
     ]
   }
-}
+}