dev-booster 1.17.2 → 1.18.1

package/template/.devbooster/hub/knowledge/nextjs-pitfalls.md

@@ -0,0 +1,226 @@
+# ▲ Next.js Pitfalls
+
+> **Purpose:** Common pitfalls and issues in Next.js 16+ projects
+> **Primary official sources:** [Next.js TypeScript configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/typescript) · [Next.js 16 upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-16) · [Next.js Image configuration](https://nextjs.org/docs/app/api-reference/components/image#configuration-options)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, router and rendering model, local rules, existing abstractions, configuration, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Table of Contents
+
+1. [Framework-level Masking — ignoreBuildErrors](#framework-level-masking)
+2. [Legacy Build-time Lint Masking — Next.js 15 and Earlier](#legacy-build-time-lint-masking)
+3. [Broken Lint Script After a Next.js 16 Upgrade](#broken-lint-script-after-a-nextjs-16-upgrade)
+4. [Invalid next.config Properties](#invalid-nextconfig-properties)
+5. [TSConfig Changes Triggered by Next.js](#tsconfig-changes-triggered-by-nextjs)
+6. [New Lint Findings After an Upgrade](#new-lint-findings-after-an-upgrade)
+7. [Warnings Need Triage](#warnings-need-triage)
+8. [Choose Server and Client Boundaries Deliberately](#choose-server-and-client-boundaries-deliberately)
+9. [Use Route Loading and Error Boundaries Before Rebuilding Them](#use-route-loading-and-error-boundaries-before-rebuilding-them)
+10. [Avoid Hydration Mismatches by Preserving Initial Output](#avoid-hydration-mismatches-by-preserving-initial-output)
+
+---
+
+## Framework-level Masking
+
+### Problem
+The `typescript.ignoreBuildErrors: true` option in `next.config.*` skips Next.js's built-in TypeScript type-checking step during production builds. It does not run the check and suppress its errors, so it can allow type errors to reach deployment.
+
+*Source: [Next.js TypeScript configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/typescript)*
+
+> The official Next.js documentation warns: "If disabled, be sure you are running type checks as part of your build or deploy process, otherwise this can be very dangerous."
+
+### Code (symptom)
+```js
+// next.config.js — bypasses Next.js type checking
+typescript: { ignoreBuildErrors: true }
+```
+
+### Fix
+Remove the flag; `false` is the default:
+```js
+module.exports = {
+  typescript: {
+    ignoreBuildErrors: false,
+  },
+}
+```
+
+If a project temporarily keeps the flag, run an explicit type check such as `tsc --noEmit` in CI or the deployment pipeline.
+
+---
+
+## Legacy Build-time Lint Masking
+
+**Evidence:** Field-validated in a real audit.
+
+### Applicability
+Next.js 15 and earlier. The `eslint.ignoreDuringBuilds` option was supported in these versions and allowed production builds to complete with ESLint errors.
+
+*Source: [Next.js 15 ESLint configuration](https://nextjs.org/docs/15/app/api-reference/config/next-config-js/eslint)*
+
+### Code (symptom)
+```js
+module.exports = {
+  eslint: {
+    ignoreDuringBuilds: true,
+  },
+}
+```
+
+### Why it matters
+This setting bypasses Next.js's built-in build-time lint failure. It may have been introduced as a temporary deployment workaround, but it hides lint failures unless ESLint runs independently in CI or another verified workflow.
+
+### Version boundary
+Next.js 16 removed `next lint`, build-time linting, and the `eslint` key in `next.config.*`. For Next.js 16+, remove this legacy config and run ESLint directly as a separate validation command.
+
+---
+
+## Broken Lint Script After a Next.js 16 Upgrade
+
+### Problem
+Starting with Next.js 16, `next lint` is removed. `next build` no longer runs linting, and the `eslint` key in `next.config.*` is removed.
+
+Invoking the removed command can produce an error such as:
+```
+Invalid project directory provided, no such directory: .../lint
+```
+
+### Fix
+Run ESLint directly and make linting a separate CI or deployment step:
+```json
+{
+  "scripts": {
+    "lint": "eslint ."
+  }
+}
+```
+
+For flat-config setup and migration details, see [ESLint Migration](./eslint-migration.md).
+
+---
+
+## Invalid next.config Properties
+
+### Problem
+A property in an unsupported location in `next.config.*` can produce a configuration warning or be ignored. For example, `unoptimized` is not a top-level Next.js config option.
+
+### Code (symptom)
+```js
+// Invalid location
+module.exports = { unoptimized: true }
+
+// Valid location
+module.exports = { images: { unoptimized: true } }
+```
+
+### Fix
+Use the documented `images.unoptimized` option:
+```js
+module.exports = {
+  images: {
+    unoptimized: true,
+  },
+}
+```
+
+---
+
+## TSConfig Changes Triggered by Next.js
+
+### Problem
+When TypeScript is added to a project, `next dev` and `next build` can create or update `tsconfig.json` with recommended settings and generated-type includes.
+
+### Handling
+- Review the complete `tsconfig.json` diff and identify why each change was made.
+- Keep required generated-type includes, such as `.next/types/**/*.ts`, when the project uses Next.js route-aware types.
+- Validate compiler-option changes, including `moduleResolution`, against the project's Next.js and TypeScript versions before accepting or reverting them.
+- Commit intentional configuration changes so they are visible in review.
+
+---
+
+## New Lint Findings After an Upgrade
+
+### Problem
+After migrating to ESLint flat config or updating Next.js, ESLint, or plugins, new rules or changed analysis can reveal existing issues or introduce upgrade-specific incompatibilities.
+
+### Common examples
+- A callback referenced before declaration
+- Non-deterministic logic during render, such as `Math.random()` in a component body
+- An unused import that was previously not reported
+
+### Handling
+1. Analyze each finding individually.
+2. Classify it as a pre-existing issue now detected, a configuration change, or an upgrade regression.
+3. Apply a specific fix or document a narrowly justified exception.
+
+---
+
+## Warnings Need Triage
+
+### Problem
+A successful build can still emit warnings about configuration, deprecations, or behavior that affects production.
+
+### Checklist
+After a framework upgrade:
+1. Run `next build` and capture the full output.
+2. Review warnings as well as errors.
+3. Determine the source, impact, and owner of each warning.
+4. Fix the warning or document an accepted disposition according to the project's release policy.
+
+### Rule of thumb
+**A passing build with warnings requires triage; warnings are neither automatically deploy-blocking nor automatically acceptable.**
+
+---
+
+## Choose Server and Client Boundaries Deliberately
+
+### Decision
+In the App Router, components are Server Components by default. Add `'use client'` only when the component or one of its direct responsibilities requires client-side capabilities such as state, Effects, browser APIs, or event handlers.
+
+### Verify first
+- Identify the active router; do not apply App Router guidance to a Pages Router project.
+- Keep the client boundary as narrow as the existing architecture permits.
+- Inspect existing component boundaries and shared providers before moving a component to the client.
+- Pass serializable props across the Server-to-Client boundary.
+
+Do not convert a server-rendered subtree to a Client Component merely to solve a small interactive concern. Extract the interactive leaf when that preserves the project’s established composition pattern.
+
+*Sources: [Next.js — Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components) · [Next.js — use client](https://nextjs.org/docs/app/api-reference/directives/use-client)*
+
+---
+
+## Use Route Loading and Error Boundaries Before Rebuilding Them
+
+### Decision
+For App Router route segments, inspect existing `loading.*`, `error.*`, and shared layout conventions before adding component-local loading or error state. These files define framework-native boundaries for the segment and its descendants.
+
+### Verify first
+- Confirm whether the loading state is route-level, component-level, or owned by an existing client query abstraction.
+- Preserve existing fallback, retry, error-reporting, and accessibility conventions.
+- Do not use `loading.*` as a substitute for errors in a client-side mutation or interaction; use the project’s local feedback pattern there.
+- Confirm the required error boundary shape for the installed Next version before creating one.
+
+Use the smallest boundary that gives the intended user experience. A project may intentionally prefer a shared route skeleton or a local component state; preserve either approach when valid.
+
+*Sources: [Next.js — Loading UI and Streaming](https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming) · [Next.js — Error Handling](https://nextjs.org/docs/app/building-your-application/routing/error-handling)*
+
+---
+
+## Avoid Hydration Mismatches by Preserving Initial Output
+
+### Symptom
+The server-rendered HTML differs from the first client render, producing a hydration warning, discarded markup, or visible flicker.
+
+### Verify first
+Look for browser-only values (`window`, storage, viewport), time, randomness, locale, and data that changes between the server and first client render. Confirm whether the component is intended to render consistently on both sides.
+
+### Fix
+Render the same initial output on server and client, then read browser-only state after mount when necessary. For an intentionally client-only widget, isolate it behind the project’s established client boundary rather than scattering hydration suppressions.
+
+Do not use `suppressHydrationWarning` as a general fix; it is a narrow escape hatch and does not reconcile the underlying output.
+
+*Source: [Next.js — React Hydration Error](https://nextjs.org/docs/messages/react-hydration-error)*

package/template/.devbooster/hub/knowledge/nodejs-patterns.md

@@ -0,0 +1,148 @@
+# Node.js Runtime Patterns
+
+> **Purpose:** Diagnose and prevent common Node.js runtime, module, environment, and script failures.
+> **Primary official sources:** [Node.js documentation](https://nodejs.org/docs/latest/api/) · [npm package.json documentation](https://docs.npmjs.com/cli/v11/configuring-npm/package-json) · [npm scripts documentation](https://docs.npmjs.com/cli/v11/using-npm/scripts)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing abstractions, configuration, runtime environment, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Table of Contents
+
+1. [Runtime and Engines Misalignment](#runtime-and-engines-misalignment)
+2. [ESM and CommonJS Interoperability](#esm-and-commonjs-interoperability)
+3. [Environment Loading and Validation](#environment-loading-and-validation)
+4. [Unhandled Async Failures](#unhandled-async-failures)
+5. [Portable npm Scripts and Lifecycle Hooks](#portable-npm-scripts-and-lifecycle-hooks)
+6. [Version Manager, CI, and Container Alignment](#version-manager-ci-and-container-alignment)
+
+---
+
+## Runtime and Engines Misalignment
+
+### Symptom
+A command works on one machine but fails in CI or production with syntax errors, unsupported APIs, native-module errors, or an `EBADENGINE` warning/error.
+
+### Verify first
+```sh
+node --version
+npm --version
+node -p "process.version"
+```
+Compare those values with the root `package.json` `engines`, the CI runtime setup, container base image, and any version-manager file. `engines` expresses compatibility metadata; enforcement depends on the package manager and its configuration. See [npm `engines`](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#engines).
+
+### Fix
+- Define a tested Node range in `engines`; use an exact version only when reproducibility requires it.
+- Select a Node version explicitly in CI and containers rather than relying on a runner or image default.
+- Rebuild native dependencies after changing Node versions; do not reuse artifacts built against an incompatible ABI.
+- Keep local version-manager configuration aligned with the supported range.
+
+---
+
+## ESM and CommonJS Interoperability
+
+### Symptom
+`require is not defined`, `ERR_REQUIRE_ESM`, missing named exports, or different behavior between development and production builds.
+
+### Verify first
+Inspect the closest `package.json` for `"type"`, the file extension (`.mjs`, `.cjs`, `.js`), and the dependency's documented exports. Node determines module interpretation from these inputs. See [Node.js modules: packages](https://nodejs.org/docs/latest/api/packages.html) and [ECMAScript modules](https://nodejs.org/docs/latest/api/esm.html).
+
+### Fix
+- Choose one module system for new application code and declare it deliberately with `type` or explicit extensions.
+- In ESM, import CommonJS through its default export when necessary, then read properties from that value.
+- In CommonJS, use `import()` for an ESM-only dependency because synchronous `require()` has compatibility limits.
+- Do not depend on undocumented deep imports or inferred named exports; use the dependency's public export map.
+
+```js
+// CommonJS loading an ESM package
+const loadTool = () => import('an-esm-only-package')
+
+// ESM consuming CommonJS
+import legacyPackage from 'legacy-package'
+const { createClient } = legacyPackage
+```
+
+---
+
+## Environment Loading and Validation
+
+### Symptom
+A service starts with `undefined` configuration, uses development credentials in another environment, or fails only after handling traffic.
+
+### Verify first
+Identify where configuration is loaded, which process owns it, and whether the expected variables are present without printing secrets:
+
+```sh
+node -e "console.log(Boolean(process.env.REQUIRED_SETTING))"
+```
+Node exposes the process environment through [`process.env`](https://nodejs.org/docs/latest/api/process.html#processenv). Recent Node releases also document loading `.env` files with [`--env-file`](https://nodejs.org/docs/latest/api/cli.html#--env-fileconfig); verify availability in the exact Node version in use before relying on it.
+
+### Fix
+- Load configuration before importing or initializing code that reads it.
+- Validate required variables, types, allowed values, and cross-field constraints at process startup; fail with variable names, never secret values.
+- Treat environment values as strings until parsed and validated.
+- Keep secrets out of source control and inject them through the deployment environment or an approved secret mechanism.
+
+---
+
+## Unhandled Async Failures
+
+### Symptom
+A request hangs, an error appears as an unhandled rejection, or the process exits unexpectedly after an async operation fails.
+
+### Verify first
+Trace every promise-returning call to an `await`/`return`/`.catch()`. Review the runtime's unhandled-rejection behavior for the deployed Node version: [Node.js `unhandledRejection`](https://nodejs.org/docs/latest/api/process.html#event-unhandledrejection).
+
+### Fix
+- Await promises inside `try`/`catch` where recovery or translation is needed.
+- Return promises from wrapper functions so callers can observe failures.
+- At process boundaries, log actionable context, release resources, and exit or restart according to the service's supervision model.
+- Do not use a global rejection handler as a substitute for local error handling; it is an observability and last-resort shutdown boundary.
+
+```js
+async function readConfiguration() {
+  try {
+    return await fetchConfiguration()
+  } catch (error) {
+    throw new Error('Configuration could not be loaded', { cause: error })
+  }
+}
+```
+
+---
+
+## Portable npm Scripts and Lifecycle Hooks
+
+### Symptom
+A script passes on one operating system but fails in CI, or an install unexpectedly runs build, download, or publish-related code.
+
+### Verify first
+Review `scripts` and lifecycle names in `package.json`, then run the exact package-manager command used by CI. npm exposes lifecycle context through environment variables and has command-specific lifecycle behavior; see [npm scripts](https://docs.npmjs.com/cli/v11/using-npm/scripts) and [lifecycle scripts](https://docs.npmjs.com/cli/v11/using-npm/scripts#life-cycle-operation-order).
+
+### Fix
+- Prefer Node-based scripts or cross-platform tooling over shell-specific syntax, utilities, and environment assignments.
+- Make each script's inputs and outputs explicit; use package binaries through the package manager rather than assuming global installations.
+- Keep `prepare`, `prepack`, `prepublishOnly`, and install hooks small and intentional. Verify which commands trigger each hook before placing builds or side effects there.
+- Run install commands with lifecycle scripts disabled only as a diagnostic or controlled security measure, not as a permanent workaround for an unknown hook.
+
+---
+
+## Version Manager, CI, and Container Alignment
+
+### Problem
+Node is pinned locally but not in CI or the deployment image, creating a runtime matrix that is neither tested nor supported.
+
+### Fix
+Use one documented source of truth for the supported Node range, and make every execution environment select a compatible runtime:
+
+| Environment | Check |
+| --- | --- |
+| Local development | Version-manager configuration and `node --version` |
+| CI | Explicit setup action/task and cache key including Node and lockfile |
+| Container | Explicit base-image tag and rebuild after runtime changes |
+| Deployment | Platform runtime setting or image runtime |
+
+### Verify first
+Print `node --version` at the start of CI and from the built container. Install from the committed lockfile, then run the same test/build commands that validate local development. For supported release lines and schedules, use the [Node.js release page](https://nodejs.org/en/about/previous-releases).

package/template/.devbooster/hub/knowledge/package-manager-patterns.md

@@ -0,0 +1,143 @@
+# Package Manager Patterns
+
+> **Purpose:** Resolve reproducibility, dependency-resolution, workspace-scope, and security-report issues across npm, Yarn, and pnpm.
+> **Primary official sources:** [npm CLI documentation](https://docs.npmjs.com/cli/) · [Yarn documentation](https://yarnpkg.com/configuration/manifest) · [pnpm documentation](https://pnpm.io/)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, package manager, lockfile, workspace layout, configuration, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Table of Contents
+
+1. [Detect the Manager and Lockfile](#detect-the-manager-and-lockfile)
+2. [Override and Resolution Semantics](#override-and-resolution-semantics)
+3. [Peer Dependency Conflicts](#peer-dependency-conflicts)
+4. [Serialized Installs](#serialized-installs)
+5. [Audit Findings](#audit-findings)
+6. [Workspace Root Versus Package Scope](#workspace-root-versus-package-scope)
+7. [Frozen Lockfile Validation](#frozen-lockfile-validation)
+
+---
+
+## Detect the Manager and Lockfile
+
+### Symptom
+An install rewrites the lockfile, resolves a different tree, or fails because a command was run with the wrong manager.
+
+### Verify first
+Inspect the repository root for `packageManager` in `package.json`, manager configuration files, and lockfiles such as `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`. The Corepack documentation explains the `packageManager` field and shims: [Node.js Corepack](https://nodejs.org/docs/latest/api/corepack.html).
+
+### Fix
+- Use the manager declared by the repository; do not introduce or regenerate another manager's lockfile.
+- Treat one committed lockfile as the install-resolution authority for a repository.
+- When the intended manager is ambiguous, inspect CI and contributor documentation before changing dependencies.
+- Pin the manager release through the repository's supported mechanism, then ensure CI uses the same release family.
+
+---
+
+## Override and Resolution Semantics
+
+### Problem
+A transitive dependency needs a security or compatibility fix, but editing a lockfile directly is fragile and will be overwritten.
+
+### Verify first
+Identify the full dependency path and confirm the replacement version is compatible. Then use the manager's native manifest field:
+
+| Manager | Manifest mechanism | Official reference |
+| --- | --- | --- |
+| npm | `overrides` | [npm `overrides`](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#overrides) |
+| Yarn | `resolutions` | [Yarn manifest `resolutions`](https://yarnpkg.com/configuration/manifest#resolutions) |
+| pnpm | `pnpm.overrides` | [pnpm overrides](https://pnpm.io/package_json#pnpmoverrides) |
+
+### Fix
+- Put the override where that manager resolves dependencies, normally the root manifest for a workspace repository.
+- Scope it as narrowly as the manager supports; document the reason and remove it when upstream constraints no longer require it.
+- Reinstall with the declared manager, review the lockfile diff, and test the affected dependency path.
+- Do not assume the fields are interchangeable: selector syntax, allowed locations, and direct-dependency rules differ by manager.
+
+---
+
+## Peer Dependency Conflicts
+
+### Symptom
+Installation reports incompatible peers, installs multiple host versions, or runtime plugins fail because they are connected to an unexpected host package.
+
+### Verify first
+Read the peer range from the package reporting the conflict and identify the actual host version selected by the lockfile. A peer dependency expresses compatibility with a package supplied by the consumer; see [npm peer dependencies](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#peerdependencies) and [pnpm peer dependencies](https://pnpm.io/npmrc#strict-peer-dependencies).
+
+### Fix
+1. Prefer versions whose peer ranges overlap.
+2. Upgrade or replace the dependent package if it does not support the selected host.
+3. Use a documented compatibility bridge only after testing the integration.
+4. Avoid permanently suppressing peer checks. A flag can unblock diagnosis, but it does not make an unsupported runtime combination safe.
+
+---
+
+## Serialized Installs
+
+### Symptom
+Concurrent jobs or processes corrupt a lockfile, contend for package-manager state, or publish nondeterministic dependency changes.
+
+### Fix
+- Make dependency updates a serialized workflow: one writer updates the manifest and lockfile, then commits both together.
+- Keep CI installs read-only with respect to the lockfile.
+- Avoid sharing mutable package-manager caches or store directories across concurrent jobs unless the tool and cache backend support it safely.
+- Separate dependency-update automation from build/test jobs that only consume the committed resolution.
+
+### Verify first
+Run a clean install twice in separate workspaces, then confirm the lockfile and dependency tree do not change. Use the manager's own listing/why command to verify the selected version.
+
+---
+
+## Audit Findings
+
+### Symptom
+An audit reports vulnerabilities and a bulk auto-fix proposes major upgrades, lockfile churn, or removal of required packages.
+
+### Verify first
+For each finding, determine whether the vulnerable package is reachable in the shipped runtime, which version introduces the fix, and whether the advisory applies to the supported deployment path. npm documents its audit command and report format in [npm audit](https://docs.npmjs.com/auditing-package-dependencies-for-security-vulnerabilities).
+
+### Fix
+- Prioritize direct, runtime-reachable, exploitable dependencies.
+- Upgrade the owning direct dependency when possible; use a narrowly scoped override only when necessary.
+- Review major-version changes and test behavior instead of blindly accepting forceful remediation.
+- Record accepted risk with scope and review conditions when no compatible fix exists.
+
+An audit is an input to risk assessment, not proof that an application is exploitable or safe.
+
+---
+
+## Workspace Root Versus Package Scope
+
+### Problem
+A command runs against the wrong package, configuration appears ignored, or a dependency is added to the root when it belongs to an application/library package.
+
+### Verify first
+Confirm the current directory, workspace declaration, and package target. npm documents workspace targeting in [npm workspaces](https://docs.npmjs.com/cli/v11/using-npm/workspaces); Yarn and pnpm have equivalent workspace-aware command support.
+
+### Fix
+- Put runtime and library dependencies in the package that imports them.
+- Keep root tooling dependencies at the root only when the root owns the command or configuration.
+- Use explicit workspace selectors for install, run, test, and publish operations.
+- Avoid assuming a command's default scope; root and workspace behavior is manager- and command-specific.
+
+---
+
+## Frozen Lockfile Validation
+
+### Symptom
+CI succeeds after silently modifying a lockfile, or a clean checkout cannot reproduce the committed dependency tree.
+
+### Fix
+Use the manager's immutable/frozen validation mode in CI:
+
+| Manager | Typical validation command | Reference |
+| --- | --- | --- |
+| npm | `npm ci` | [npm ci](https://docs.npmjs.com/cli/v11/commands/npm-ci) |
+| Yarn | `yarn install --immutable` | [Yarn install](https://yarnpkg.com/cli/install) |
+| pnpm | `pnpm install --frozen-lockfile` | [pnpm install](https://pnpm.io/cli/install) |
+
+### Verify first
+Start from a clean checkout, run the applicable command, then confirm no manifest or lockfile changes are produced. Use the exact manager release declared by the repository.