Performance Optimization and Cleanup

CLAUDE.md

@@ -141,6 +141,7 @@ See [Testing Workflows Locally](docs/testing-github-workflows-locally.md) for us
 - [Git Workflow Guide](docs/git-workflow-guide.md) - PR process, commit squashing, real examples
 - [CI Troubleshooting](docs/ci-troubleshooting.md) - Common failures and fixes
 - [Development Guidelines](docs/development-guidelines.md) - Code quality standards
+- [Performance Optimization](docs/performance-optimization.md) - e18e principles, optimization decisions, and rationale
 
 **Renovate PRs:**
 - [RENOVATE_PR_COMMENTS.md](docs/RENOVATE_PR_COMMENTS.md) - Comment format guidelines

Dockerfile

@@ -15,11 +15,12 @@ RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
 COPY . .
 
 # install dependencies
-# FIXME: use --offline instead of --prefer-offline
+# --prefer-offline: use cache when possible, fall back to network for new deps
 RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
     pnpm install --prefer-offline --frozen-lockfile --filter='!@hello-world-web/*tests'
 
-RUN pnpm run build
+# Build with production optimizations (enables minification in Rollup)
+RUN NODE_ENV=production pnpm run build
 
 # # create production deployment
 RUN --mount=type=cache,id=pnpm,target=/pnpm/store \

README.md

@@ -278,6 +278,16 @@ pnpm run ci
 
 To test GitHub Actions workflows locally using `act`, see [Testing Workflows Locally](docs/testing-github-workflows-locally.md).
 
+### Documentation
+
+For development guidelines, optimization strategies, and workflow documentation, see:
+
+- [Development Guidelines](docs/development-guidelines.md) - Code quality standards and best practices
+- [Performance Optimization](docs/performance-optimization.md) - e18e principles, optimization decisions, and rationale
+- [Git Workflow Guide](docs/git-workflow-guide.md) - PR process and commit guidelines
+- [CI Troubleshooting](docs/ci-troubleshooting.md) - Common CI failures and fixes
+- [Testing Workflows Locally](docs/testing-github-workflows-locally.md) - Using `act` to test GitHub Actions
+
 ### E2E (End-to-End) tests
 
 * [Playwright](https://playwright.dev/) with [playwright-bdd](https://github.com/vitalets/playwright-bdd)

docs/development-guidelines.md

@@ -49,6 +49,10 @@ function getTestData(page: any): TestData {
 - Run `pnpm install` after any package.json changes
 - Commit pnpm-lock.yaml changes
 - Test thoroughly after major updates
+- Keep TypeScript versions aligned across all workspace packages
+- Run `pnpm run lint:knip` regularly to detect unused dependencies
+
+See [Performance Optimization](./performance-optimization.md) for details on dependency cleanup and optimization strategies.
 
 ## TypeScript Configuration
 
@@ -167,10 +171,32 @@ env: {
 }
 ```
 
+## Performance Considerations
+
+When adding or modifying code, consider performance impact:
+
+### Build Time
+- Use minification only in production builds (`NODE_ENV=production`)
+- Enable source maps for both dev and production
+- Leverage Docker layer caching with `pnpm fetch`
+
+### Runtime Performance
+- Add compression for text-based responses
+- Set appropriate cache headers for static assets
+- Implement proper error handling to prevent crashes
+
+### Bundle Size
+- Run `du -sh packages/*/lib/**/*.js` to check bundle sizes after builds
+- Target < 150KB for client bundles (minified + gzipped)
+- Use code splitting for large features
+
+See [Performance Optimization](./performance-optimization.md) for comprehensive guidelines and e18e principles.
+
 ## Key Files to Understand
 
 - `.github/workflows/`: CI/CD configuration
 - `packages/e2e-tests/`: E2E test suite with Playwright-BDD
 - `knip.json`: Unused code detection config
 - `eslint.config.mjs`: Code style rules
 - `pnpm-workspace.yaml`: Monorepo configuration
+- `docs/performance-optimization.md`: Performance optimization principles and decisions