Development: change frontend package manager to pnpm (#9363)

.devcontainer/Dockerfile

@@ -149,7 +149,7 @@ RUN --mount=type=cache,target=/root/.cache/uv,id=pip-cache \
     && apt-get install --yes --quiet ${BUILD_PACKAGES}
 
 RUN set -eux \
-  && npm update npm -g
+  && npm update -g pnpm
 
 # add users, setup scripts
 # Mount the compiled frontend to expected location

.devcontainer/vscode/tasks.json

@@ -33,7 +33,7 @@
 			"label": "Start: Frontend Angular",
 			"description": "Start the Frontend Angular Dev Server",
 			"type": "shell",
-			"command": "npm start",
+			"command": "pnpm start",
 			"isBackground": true,
 			"options": {
 				"cwd": "${workspaceFolder}/src-ui"
@@ -173,8 +173,8 @@
 		},
 		{
 			"label": "Maintenance: Install Frontend Dependencies",
-			"description": "Install frontend (npm) dependencies",
+			"description": "Install frontend (pnpm) dependencies",
-			"type": "npm",
+			"type": "pnpm",
 			"script": "install",
 			"path": "src-ui",
 			"group": "clean",
@@ -185,7 +185,7 @@
 			"description": "Clean install frontend dependencies and build the frontend for production",
 			"label": "Maintenance: Compile frontend for production",
 			"type": "shell",
-			"command": "npm ci && ./node_modules/.bin/ng build --configuration production",
+			"command": "pnpm install && ./node_modules/.bin/ng build --configuration production",
 			"group": "none",
 			"presentation": {
 				"echo": true,

.github/dependabot.yml

@@ -1,14 +1,15 @@
-# https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#package-ecosystem
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
 
 version: 2
 # Required for uv support for now
 enable-beta-ecosystems: true
 updates:
 
-  # Enable version updates for npm
+  # Enable version updates for pnpm
   - package-ecosystem: "npm"
     target-branch: "dev"
-    # Look for `package.json` and `lock` files in the `/src-ui` directory
+    # Look for `pnpm-lock.yaml` file in the `/src-ui` directory
     directory: "/src-ui"
     open-pull-requests-limit: 10
     schedule:

.github/workflows/ci.yml

@@ -190,29 +190,33 @@ jobs:
       - pre-commit
     steps:
       - uses: actions/checkout@v4
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
       -
         name: Use Node.js 20
         uses: actions/setup-node@v4
         with:
           node-version: 20.x
-          cache: 'npm'
+          cache: 'pnpm'
-          cache-dependency-path: 'src-ui/package-lock.json'
+          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
       - name: Cache frontend dependencies
         id: cache-frontend-deps
         uses: actions/cache@v4
         with:
           path: |
-            ~/.npm
+            ~/.pnpm-store
             ~/.cache
-          key: ${{ runner.os }}-frontenddeps-${{ hashFiles('src-ui/package-lock.json') }}
+          key: ${{ runner.os }}-frontenddeps-${{ hashFiles('src-ui/pnpm-lock.yaml') }}
       -
         name: Install dependencies
         if: steps.cache-frontend-deps.outputs.cache-hit != 'true'
-        run: cd src-ui && npm ci
+        run: cd src-ui && pnpm install
       -
         name: Install Playwright
         if: steps.cache-frontend-deps.outputs.cache-hit != 'true'
-        run: cd src-ui && npx playwright install --with-deps
+        run: cd src-ui && pnpm playwright install --with-deps
 
   tests-frontend:
     name: "Frontend Tests (Node ${{ matrix.node-version }} - ${{ matrix.shard-index }}/${{ matrix.shard-count }})"
@@ -227,32 +231,36 @@ jobs:
         shard-count: [4]
     steps:
       - uses: actions/checkout@v4
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
       -
         name: Use Node.js 20
         uses: actions/setup-node@v4
         with:
           node-version: 20.x
-          cache: 'npm'
+          cache: 'pnpm'
-          cache-dependency-path: 'src-ui/package-lock.json'
+          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
       - name: Cache frontend dependencies
         id: cache-frontend-deps
         uses: actions/cache@v4
         with:
           path: |
-            ~/.npm
+            ~/.pnpm-store
             ~/.cache
-          key: ${{ runner.os }}-frontenddeps-${{ hashFiles('src-ui/package-lock.json') }}
+          key: ${{ runner.os }}-frontenddeps-${{ hashFiles('src-ui/pnpm-lock.yaml') }}
       - name: Re-link Angular cli
-        run: cd src-ui && npm link @angular/cli
+        run: cd src-ui && pnpm link @angular/cli
       -
         name: Linting checks
-        run: cd src-ui && npm run lint
+        run: cd src-ui && pnpm run lint
       -
         name: Run Jest unit tests
-        run: cd src-ui && npm run test -- --max-workers=2 --shard=${{ matrix.shard-index }}/${{ matrix.shard-count }}
+        run: cd src-ui && pnpm run test --max-workers=2 --shard=${{ matrix.shard-index }}/${{ matrix.shard-count }}
       -
         name: Run Playwright e2e tests
-        run: cd src-ui && npx playwright test --shard ${{ matrix.shard-index }}/${{ matrix.shard-count }}
+        run: cd src-ui && pnpm exec playwright test --shard ${{ matrix.shard-index }}/${{ matrix.shard-count }}
       -
         name: Upload frontend test results to Codecov
         uses: codecov/test-results-action@v1
@@ -276,30 +284,35 @@ jobs:
       - tests-frontend
     steps:
       - uses: actions/checkout@v4
+      -
+        name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
       -
         name: Use Node.js 20
         uses: actions/setup-node@v4
         with:
           node-version: 20.x
-          cache: 'npm'
+          cache: 'pnpm'
-          cache-dependency-path: 'src-ui/package-lock.json'
+          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
       -
         name: Cache frontend dependencies
         id: cache-frontend-deps
         uses: actions/cache@v4
         with:
           path: |
-            ~/.npm
+            ~/.pnpm-store
             ~/.cache
           key: ${{ runner.os }}-frontenddeps-${{ hashFiles('src-ui/package-lock.json') }}
       -
         name: Re-link Angular cli
-        run: cd src-ui && npm link @angular/cli
+        run: cd src-ui && pnpm link @angular/cli
       -
         name: Build frontend and upload analysis
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-        run: cd src-ui && ng build --configuration=production
+        run: cd src-ui && pnpm run build --configuration=production
 
   build-docker-image:
     name: Build Docker image for ${{ github.ref_name }}

.pre-commit-config.yaml

@@ -32,7 +32,7 @@ repos:
     rev: v2.4.0
     hooks:
       - id: codespell
-        exclude: "(^src-ui/src/locale/)|(^src-ui/e2e/)|(^src/paperless_mail/tests/samples/)"
+        exclude: "(^src-ui/src/locale/)|(^src-ui/pnpm-lock.yaml)|(^src-ui/e2e/)|(^src/paperless_mail/tests/samples/)"
         exclude_types:
           - pofile
           - json

Dockerfile

@@ -4,15 +4,17 @@
 # Stage: compile-frontend
 # Purpose: Compiles the frontend
 # Notes:
-#  - Does NPM stuff with Typescript and such
+#  - Does PNPM stuff with Typescript and such
 FROM --platform=$BUILDPLATFORM docker.io/node:20-bookworm-slim AS compile-frontend
 
 COPY ./src-ui /src/src-ui
 
 WORKDIR /src/src-ui
 RUN set -eux \
-  && npm update npm -g \
+  && npm update -g pnpm \
-  && npm ci
+  && npm install -g corepack@latest \
+  && corepack enable \
+  && pnpm install
 
 ARG PNGX_TAG_VERSION=
 # Add the tag to the environment file if its a tagged dev build

docs/development.md

@@ -140,7 +140,7 @@ To build the front end once use this command:
 ```bash
 # src-ui/
 
-$ npm install
+$ pnpm install
 $ ng build --configuration production
 ```
 
@@ -176,7 +176,7 @@ To add a new development package `uv add --dev <package>`
 ## Front end development
 
 The front end is built using AngularJS. In order to get started, you need Node.js (version 14.15+) and
-`npm`.
+`pnpm`.
 
 !!! note
 
@@ -185,7 +185,7 @@ The front end is built using AngularJS. In order to get started, you need Node.j
 1.  Install the Angular CLI. You might need sudo privileges to perform this command:
 
     ```bash
-    npm install -g @angular/cli
+    pnpm install -g @angular/cli
     ```
 
 2.  Make sure that it's on your path.
@@ -193,7 +193,7 @@ The front end is built using AngularJS. In order to get started, you need Node.j
 3.  Install all necessary modules:
 
     ```bash
-    npm install
+    pnpm install
     ```
 
 4.  You can launch a development server by running:

src-ui/.npmrc

@@ -0,0 +1 @@
+shamefully-hoist=true

src-ui/angular.json

@@ -178,7 +178,8 @@
     "schematicCollections": [
       "@angular-eslint/schematics"
     ],
-    "analytics": false
+    "analytics": false,
+    "packageManager": "pnpm"
   },
   "schematics": {
     "@angular-eslint/schematics:application": {

src-ui/jest.config.js

@@ -7,7 +7,9 @@ module.exports = {
     'abstract-name-filter-service',
     'abstract-paperless-service',
   ],
-  transformIgnorePatterns: [`<rootDir>/node_modules/(?!.*\\.mjs$|lodash-es)`],
+  transformIgnorePatterns: [
+    `<rootDir>/node_modules/.pnpm/(?!.*\\.mjs$|lodash-es)`,
+  ],
   moduleNameMapper: {
     '^src/(.*)': '<rootDir>/src/$1',
   },

src-ui/package.json

@@ -2,6 +2,7 @@
   "name": "paperless-ui",
   "version": "0.0.0",
   "scripts": {
+    "preinstall": "npx only-allow pnpm",
     "ng": "ng",
     "start": "ng serve",
     "build": "ng build",
@@ -71,5 +72,14 @@
     "ts-node": "~10.9.1",
     "typescript": "^5.5.4"
   },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@parcel/watcher",
+      "canvas",
+      "esbuild",
+      "lmdb",
+      "msgpackr-extract"
+    ]
+  },
   "typings": "./src/typings.d.ts"
 }

src-ui/playwright.config.ts

@@ -21,7 +21,7 @@ export default defineConfig({
   /* Run your local dev server before starting the tests */
   webServer: {
     port,
-    command: 'npm run start',
+    command: 'pnpm run start',
     reuseExistingServer: !process.env.CI,
     timeout: 2 * 60 * 1000,
   },