Plan: Migrate from Yarn/NPM to pnpm

Migrate the monorepo from Yarn or NPM to pnpm. This migration enforces strict dependency management by fixing ghost dependencies individually, updating Dockerfiles, and migrating GitHub Actions.

Constraints

• Do not commit any changes to git without explicit instruction.
• Prefer pnpm add / pnpm add -D when adding dependencies to preserve lockfile integrity.
• never use pnpm@latest, always try to use the same version as specified in the root package.json file using corepack without version.

Steps

Upgrade NodeJS

Only in case the node version in .node-version is < 20.19.5, upgrade Node.js to version 20.20.0. Search all project files for version references and ensure the correct runtime is installed if it is not already present.

Install pnpm >= v10.28.1

1. Add .pnpm-store to .gitignore if not present.

2. Create pnpm-workspace.yaml with this content if not already present:

cleanupUnusedCatalogs: false
linkWorkspacePackages: true
packageImportMethod: clone-or-copy

3. Import monorepo workspaces into pnpm-workspace.yaml from the existing package.json and remove the yarn workspacesfield.

4. Update local dependencies in all package.json to use the "workspace:" protocol

5. Extract custom packageExtensions from .yarnrc.yml if any

6. Remove ".yarnrc", ".yarnrc.yml", "yarn.config.cjs", ".yarn", ".pnp.cjs", ".pnp.loader.cjs", "node_modules"

7. Install pnpm, run these commands in repository root:

# Import existing lockfile (yarn.lock or package-lock.json) to pnpm
corepack pnpm@latest import yarn.lock && rm yarn.lock

# Install the chosen pnpm via corepack
corepack use pnpm@latest

# Install dependencies using the imported lockfile
pnpm install --frozen-lockfile

# Build and test the monorepo
pnpm -r build
pnpm -r code-review # or pnpm -r test, pnpm -r typecheck, ... lookup code review tasks in root package.json

Ensure that root package.json is updated with "packageManager": "pnpm@<version>" using commit SHA and engines field is set.

Move resolutions to overrides

Move all resolutions from the root and sub-package package.json files into the pnpm.overrides section of the root package.json.

Migrate NPM tasks to pnpm

Replace yarn workspace <pkg> <cmd> with pnpm --filter <pkg> <cmd> and all other yarn calls with pnpm in all package.json files.

Update Dockerfiles

Modify all Dockerfiles to install pnpm (same version as in root package.json using corepack when possible) and use pnpm dlx turbo and pnpm install --frozen-lockfile. Prefer to use corepack (without version) to install pnpm instead of installing it via npm: pnpm version is specified in the root package.json file.

Check docker-compose.yaml files for any references to yarn and update them to use pnpm accordingly.

Update CI/CD Workflows

Update workflows in .github/workflows/ to use pnpm using corepack, set cache: "pnpm", and replace yarn commands. Prefer to use corepack (without version) to install pnpm instead of installing it via npm: pnpm version is specified in the root package.json file.

Ensure that the cache-dependency-path in GitHub Actions points to pnpm-lock.yaml to ensure reliable caching after the migration.

Update DX GitHub Action

Update any Github Action that uses web_app_deploy.yaml or function_app_deploy.yaml (grep these exact strings in .github folder) to pagopa/dx/.github/workflows/release-azure-appsvc-v1.yaml@main

1. Replace workflow referenced in the uses key with the new release-azure-appsvc-v1.yaml workflow.

2. Remove the use_staging_slot input.

3. Replace the function_app_name input with web_app_name.

4. Set disable_auto_staging_deploy input to true.

deploy_app:
  uses: pagopa/dx/.github/workflows/release-azure-appsvc-v1.yaml@main
  name: Deploy My App
  with:
    workspace_name: "my-app"
    environment: "app-prod"
    resource_group_name: "my-resource-group"
    web_app_name: "my-app-func-01"
    disable_auto_staging_deploy: true

Fix Ghost Dependencies

Execute pnpm install and pnpm -r build. For every "module not found" error, explicitly add the missing dependency until all builds succeed without using public-hoist-pattern.

Peer Dependency Issues: pnpm is strict about peer dependencies; some packages might require pnpm.peerDependencyRules in the root package.json if upstream packages have poorly defined peers.

Clean Up

Remove any remaining references to yarn in .gitignore

Minor Fixes

Upgrade vscode settings and all README.md to reflect changes.

Dependency Check Removal

Remove dependency-check from devDependencies and eliminate any related build scripts in all package.json files.

Finishing Up

IMPORTANT: once done, run pnpm build and pnpm code-review at the root of the monorepo and fix any issues until everything pass successfully across the monorepo. Do not skip this step and ensure all tests are green.