chore(frontend): migrate to pnpm and add lint tooling (#942)

## Summary

- migrate frontend install/test/lint workflows from npm to pnpm
- add eslint and stylelint workspace configuration
- update local/dev docker and helper scripts for pnpm-based frontend
flow
- remove npm lockfile and commit pnpm lockfile

This pull request migrates the frontend tooling from npm to pnpm,
introduces new linting tools (ESLint and Stylelint) for the frontend,
and updates related configuration and CI/CD workflows. The changes
modernize dependency management, improve code quality enforcement, and
streamline development and CI processes.

**Frontend package management migration:**

* Migrated the frontend from npm to pnpm by updating scripts in
`Makefile`, `Dockerfile`, CI workflows, and `frontend/package.json`, and
replacing `package-lock.json` with `pnpm-lock.yaml` in
`.prettierignore`. Corepack is now used to manage pnpm installation.
(`[[1]](diffhunk://#diff-76ed074a9305c04054cdebb9e9aad2d818052b07091de1f20cad0bbac34ffb52L21-R21)`,
`[[2]](diffhunk://#diff-76ed074a9305c04054cdebb9e9aad2d818052b07091de1f20cad0bbac34ffb52L32-R51)`,
`[[3]](diffhunk://#diff-76ed074a9305c04054cdebb9e9aad2d818052b07091de1f20cad0bbac34ffb52L70-R78)`,
`[[4]](diffhunk://#diff-76ed074a9305c04054cdebb9e9aad2d818052b07091de1f20cad0bbac34ffb52R90-R93)`,
`[[5]](diffhunk://#diff-76ed074a9305c04054cdebb9e9aad2d818052b07091de1f20cad0bbac34ffb52L113-R122)`,
`[[6]](diffhunk://#diff-76ed074a9305c04054cdebb9e9aad2d818052b07091de1f20cad0bbac34ffb52L135-R141)`,
`[[7]](diffhunk://#diff-dd2c0eb6ea5cfc6c4bd4eac30934e2d5746747af48fef6da689e85b752f39557L8-R11)`,
`[[8]](diffhunk://#diff-13bd9d7a30bf46656bc81f1ad5b908a627f9247be3f7d76df862b0578b534fc6R19-R22)`,
`[[9]](diffhunk://#diff-b803fcb7f17ed9235f1e5cb1fcd2f5d3b2838429d4368ae4c57ce4436577f03fR57-R70)`,
`[[10]](diffhunk://#diff-b803fcb7f17ed9235f1e5cb1fcd2f5d3b2838429d4368ae4c57ce4436577f03fR87-R121)`,
`[[11]](diffhunk://#diff-b803fcb7f17ed9235f1e5cb1fcd2f5d3b2838429d4368ae4c57ce4436577f03fR191-R208)`,
`[[12]](diffhunk://#diff-1ed7245e0c7c634928b52839600c3d493c9d29150d369e9ab20979e61e7f8f97L24-R24)`,
`[[13]](diffhunk://#diff-9f7d6b98294fa2c5e3b126728d626151528ac1fce8eaf8858e403b6096e86ce5L2-R2)`,
`[[14]](diffhunk://#diff-da6498268e99511d9ba0df3c13e439d10556a812881c9d03955b2ef7c6c1c655L20-R49)`)

**Linting and formatting improvements:**

* Added ESLint and Stylelint for the frontend, including configuration
files `frontend/eslint.config.js` and `frontend/stylelint.config.mjs`,
and integrated them into the Makefile and CI workflows. Updated VS Code
recommendations and settings to enable ESLint and auto-fix on save.
(`[[1]](diffhunk://#diff-8b60be22f06ef19ea3a74fcfb99817cadbc339930dcb44aeeb7ee968098f447dR1-R38)`,
`[[2]](diffhunk://#diff-ed88dcf2af5b09a17a7cee7d1c08fd560a0816b0f0e7e07f12cc073f64768d02R1-R13)`,
`[[3]](diffhunk://#diff-2633572b1eb62578838877abeb39ff8053af5fa47a1a731129b889db37e59610R1-R9)`,
`[[4]](diffhunk://#diff-24ad71c8613ddcf6fd23818cb3bb477a1fb6d83af4550b0bad43099813088686L11-R20)`,
`[[5]](diffhunk://#diff-76ed074a9305c04054cdebb9e9aad2d818052b07091de1f20cad0bbac34ffb52L70-R78)`,
`[[6]](diffhunk://#diff-76ed074a9305c04054cdebb9e9aad2d818052b07091de1f20cad0bbac34ffb52R90-R93)`,
`[[7]](diffhunk://#diff-b803fcb7f17ed9235f1e5cb1fcd2f5d3b2838429d4368ae4c57ce4436577f03fR87-R121)`)

**Dependency and tool updates:**

* Updated frontend dependencies in `package.json` (including `preact`,
dev tools, and linting packages), and added `stylelint` and related
configs.
(`[frontend/package.jsonR4-R13](diffhunk://#diff-da6498268e99511d9ba0df3c13e439d10556a812881c9d03955b2ef7c6c1c655R4-R13)`)

**Project hygiene and ignore files:**

* Updated `.gitignore` in the frontend to ignore `node_modules`,
`dist/`, and `.astro` directories.
(`[frontend/.gitignoreR1-R3](diffhunk://#diff-8e548ede50532796f028e75d8f3384d5bdb57b9fbe2bda95521774d0c46d0f97R1-R3)`)

**Minor improvements:**

* Improved test and build script consistency by using pnpm throughout,
and made minor formatting updates (e.g., numeric literals in
`frontend/vitest.config.js`).
(`[frontend/vitest.config.jsL8-R9](diffhunk://#diff-211d3e0ed8954e3626dc7543c7b4bfc87e73d0b4b25abf5829a13a11eaafb788L8-R9)`)

These changes collectively modernize the frontend developer experience,
improve code quality, and ensure consistent dependency management across
local and CI environments.

Author: gildesmarais

.devcontainer/Dockerfile

@@ -16,6 +16,10 @@ RUN apk add --no-cache \
     yaml-dev \
     tzdata
 
+RUN if ! command -v corepack >/dev/null 2>&1; then npm install -g corepack; fi \
+  && corepack enable \
+  && corepack prepare "pnpm@latest" --activate
+
 ARG USER=vscode
 ARG UID=1000
 ARG GID=1000

.devcontainer/devcontainer.json

@@ -8,11 +8,16 @@
     "vscode": {
       "extensions": [
         "rebornix.ruby",
-        "esbenp.prettier-vscode"
+        "esbenp.prettier-vscode",
+        "dbaeumer.vscode-eslint"
       ],
       "settings": {
         "editor.formatOnSave": true,
         "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.codeActionsOnSave": {
+          "source.fixAll.eslint": "explicit"
+        },
+        "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"],
         "prettier.configPath": "./frontend/prettier.config.js",
         "ruby.format": "rubocop",
         "ruby.lint": { "rubocop": true },

.github/workflows/ci.yml

@@ -54,15 +54,20 @@ jobs:
         with:
           bundler-cache: true
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          cache: true
+          cache_dependency_path: frontend/pnpm-lock.yaml
+          package_json_file: frontend/package.json
+
       - name: Setup Node.js for OpenAPI lint tooling
         uses: actions/setup-node@v6
         with:
           node-version-file: ".tool-versions"
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
 
       - name: Install frontend dependencies for OpenAPI client verification
-        run: npm ci
+        run: pnpm install --frozen-lockfile
         working-directory: frontend
 
       - name: Verify generated OpenAPI spec and client are up to date
@@ -79,33 +84,41 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          cache: true
+          cache_dependency_path: frontend/pnpm-lock.yaml
+          package_json_file: frontend/package.json
+
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
           node-version-file: ".tool-versions"
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       - name: Typecheck frontend
-        run: npm run typecheck
+        run: pnpm run typecheck
+
+      - name: Lint CSS with Stylelint
+        run: pnpm exec stylelint "**/*.css"
 
       - name: Check formatting
-        run: npm run format:check
+        run: pnpm run format:check
 
       - name: Audit dependencies
-        run: npm audit --audit-level=moderate
+        run: pnpm audit --audit-level=moderate
 
       - name: Run frontend tests
-        run: npm run test:ci
+        run: pnpm run test:ci
 
       - name: Install Playwright Chromium
-        run: npx playwright install --with-deps chromium
+        run: pnpm exec playwright install --with-deps chromium
 
       - name: Run frontend smoke test
-        run: npm run test:e2e
+        run: pnpm run test:e2e
 
   docker-build-smoke-image:
     needs:
@@ -175,19 +188,24 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v6
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          cache: true
+          cache_dependency_path: frontend/pnpm-lock.yaml
+          package_json_file: frontend/package.json
+
       - name: Setup Node.js for Docker build
         uses: actions/setup-node@v6
         with:
           node-version-file: ".tool-versions"
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
 
       - name: Install frontend dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
         working-directory: frontend
 
       - name: Build frontend static assets
-        run: npm run build
+        run: pnpm run build
         working-directory: frontend
 
       - name: Set up QEMU

Dockerfile

@@ -5,10 +5,10 @@ ARG NODE_BASE_IMAGE=node:22-alpine@sha256:8094c002d08262dba12645a3b4a15cd6cd627d
 FROM ${NODE_BASE_IMAGE} AS frontend-builder
 
 WORKDIR /app/frontend
-COPY frontend/package*.json ./
-RUN npm ci
+COPY frontend/package.json frontend/pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
 COPY frontend/ ./
-RUN npm run build
+RUN pnpm run build
 
 # Stage 2: Ruby Build
 FROM ${RUBY_BASE_IMAGE} AS builder

Makefile

@@ -18,7 +18,7 @@ setup: ## Full development setup
 	fi
 	@mkdir -p tmp/rack-cache-body tmp/rack-cache-meta
 	@echo "Setting up frontend..."
-	@cd frontend && npm install
+	@cd frontend && CI=1 pnpm install --frozen-lockfile
 	@echo "Setup complete!"
 
 dev: ## Start development server with live reload
@@ -29,26 +29,26 @@ dev-ruby: ## Start Ruby server only
 	@bin/dev-ruby
 
 dev-frontend: ## Start frontend dev server only
-	@cd frontend && npm run dev
+	@cd frontend && pnpm run dev
 
 test: ## Run all tests (Ruby + Frontend)
 	bundle exec rspec
-	@cd frontend && npm run test:ci
+	@cd frontend && pnpm run test:ci
 
 test-ruby: ## Run Ruby tests only
 	bundle exec rspec
 
 test-frontend: ## Run frontend tests only
-	@cd frontend && npm run test:ci
+	@cd frontend && pnpm run test:ci
 
 test-frontend-unit: ## Run frontend unit tests only
-	@cd frontend && npm run test:unit
+	@cd frontend && pnpm run test:unit
 
 test-frontend-contract: ## Run frontend contract tests only
-	@cd frontend && npm run test:contract
+	@cd frontend && pnpm run test:contract
 
 test-frontend-e2e: ## Run frontend Playwright smoke tests
-	@cd frontend && npm run test:e2e
+	@cd frontend && pnpm run test:e2e
 
 check-frontend: ## Run frontend typecheck, format, and test checks
 	$(MAKE) lint-js
@@ -67,11 +67,15 @@ lint-ruby: ## Run Ruby linter (RuboCop) - errors when issues found
 	bundle exec rake yard:verify_public_docs
 	@echo "Ruby linting complete!"
 
-lint-js: ## Run JavaScript/Frontend linter (Prettier) - errors when issues found
+lint-js: ## Run JavaScript/Frontend linting (TypeScript + ESLint + Stylelint + Prettier) - errors when issues found
 	@echo "Running TypeScript typecheck..."
-	@cd frontend && npm run typecheck
+	@cd frontend && pnpm run typecheck
+	@echo "Running ESLint..."
+	@cd frontend && pnpm run lint
+	@echo "Running Stylelint..."
+	@cd frontend && pnpm exec stylelint "../public/shared-ui.css" "**/*.css"
 	@echo "Running Prettier format check..."
-	@cd frontend && npm run format:check
+	@cd frontend && pnpm run format:check
 	@echo "JavaScript linting complete!"
 
 lintfix: lintfix-ruby lintfix-js ## Auto-fix all linting issues (Ruby + Frontend)
@@ -83,8 +87,10 @@ lintfix-ruby: ## Auto-fix Ruby linting issues
 	@echo "Ruby lintfix complete!"
 
 lintfix-js: ## Auto-fix JavaScript/Frontend linting issues
+	@echo "Running ESLint auto-fix..."
+	@cd frontend && pnpm run lint:fix
 	@echo "Running Prettier formatting..."
-	@cd frontend && npm run format
+	@cd frontend && pnpm run format
 	@echo "JavaScript lintfix complete!"
 
 quick-check: ## Fast local checks (Ruby lint/docs + frontend format/typecheck)
@@ -110,10 +116,10 @@ openapi-verify: ## Regenerate OpenAPI and fail if public/openapi.yaml or fronten
 	$(MAKE) openapi-client-verify
 
 openapi-client: ## Generate frontend OpenAPI client/types from public/openapi.yaml
-	@cd frontend && npm run openapi:generate
+	@cd frontend && pnpm run openapi:generate
 
 openapi-client-verify: ## Generate frontend OpenAPI client and fail if generated files are stale
-	@cd frontend && npm run openapi:verify
+	@cd frontend && pnpm run openapi:verify
 
 openapi-lint: openapi-lint-redocly openapi-lint-spectral ## Lint public/openapi.yaml with Redocly and Spectral
 
@@ -132,5 +138,5 @@ clean: ## Clean temporary files
 
 frontend-setup: ## Setup frontend dependencies
 	@echo "Setting up frontend dependencies..."
-	@cd frontend && npm install
+	@cd frontend && CI=1 pnpm install --frozen-lockfile
 	@echo "Frontend setup complete!"

bin/dev

@@ -28,7 +28,7 @@ cleanup() {
 
   # Kill frontend dev server and its children
   if [ ! -z "$FRONTEND_PID" ]; then
-    # Kill the npm process and its children
+    # Kill the frontend package-manager process and its children
     pkill -P $FRONTEND_PID 2>/dev/null || true
     kill $FRONTEND_PID 2>/dev/null || true
     wait $FRONTEND_PID 2>/dev/null || true
@@ -79,7 +79,7 @@ fi
 
 # Start frontend dev server
 cd frontend
-npm run dev &
+pnpm run dev &
 FRONTEND_PID=$!
 
 # Verify frontend server started

bin/dev-with-frontend

@@ -49,7 +49,7 @@ echo "Starting frontend dev server with API proxy..."
 cd frontend
 
 # Start frontend dev server (it will proxy API calls to Ruby server)
-npm run dev &
+pnpm run dev &
 FRONTEND_PID=$!
 
 # Wait a moment for the frontend server to start

frontend/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist/
+.astro

frontend/.prettierignore

@@ -1,5 +1,5 @@
 # Frontend package files
-package-lock.json
+pnpm-lock.yaml
 yarn.lock
 
 # Generated and transient frontend output

frontend/eslint.config.js

@@ -0,0 +1,38 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import reactHooks from 'eslint-plugin-react-hooks';
+import eslintPluginUnicorn from 'eslint-plugin-unicorn';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: ['.astro/**', 'dist/**', 'node_modules/**', 'src/api/generated/**', 'test-results/**'],
+  },
+  {
+    files: ['src/**/*.{js,jsx,ts,tsx}', 'e2e/**/*.ts', './*.{js,ts}'],
+    extends: [
+      js.configs.recommended,
+      ...tseslint.configs.recommended,
+      eslintPluginUnicorn.configs.recommended,
+    ],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+        ...globals.vitest,
+      },
+    },
+    plugins: {
+      'react-hooks': reactHooks,
+    },
+    rules: {
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+      'unicorn/filename-case': 'off',
+      'unicorn/better-regex': 'warn',
+    },
+  }
+);