`) with the id used in the entry file (`document.getElementById("...")`). - Propose a concrete fix: - Either update `index.html` to match the id used in code, or - Update the entry file to query the id present in `index.html`. - Always show the minimal patch (before → after) instead of general advice. 3. **Resolve alias and path problems** - For imports like `@/lib/utils` failing to resolve: - Prefer programmatic recovery first (faster and more reproducible): - Run the repo extraction tool (e.g., `node scripts/extractFilesFromMarkdown.ts`) to extract any example files embedded in markdown. - Run the workspace sync tool (e.g., `syncToWebContainer`) to copy recovered files into the container environment. - Or run the convenience helper: `node scripts/recover-and-start.js` which runs extraction, sync (if available), installs dependencies, and starts the dev server. - Restart the dev server (`pnpm dev`) and re-check the error; if files were recovered the import should resolve. - If programmatic recovery is unavailable or fails, check if the target file exists (`src/lib/utils.ts` etc.). - If missing, create a minimal implementation when appropriate (example `cn` helper for shadcn-like starters): ```ts // src/lib/utils.ts export function cn(...classes: Array) { return classes.filter(Boolean).join(' '); } ``` - Ensure `vite.config.*` has the alias configured: - `resolve: { alias: { '@': path.resolve(__dirname, 'src') } }` - Ensure `tsconfig.json` or `jsconfig.json` has the matching path map: - `"baseUrl": ".", "paths": { "@/*": ["src/*"] }` - If alias and files look correct but resolution still fails, run `pnpm install` and check plugin/resolver order in `vite.config` (some plugin orderings affect alias resolution). - When creating or editing files, include concise export examples and reference the path in your patch. - Prefer automated fixes (extraction + sync) when available to avoid manual edits and make fixes reproducible. - Provide exact config snippets and file paths. 4. **Repair scripts & package metadata** - If `pnpm start` / `npm start` fails or is missing: - Add or correct scripts so: - `"dev": "vite"` is the main dev command. - `"start": "vite --host"` or `"start": "npm run dev"` for environments that expect `start`. - Align `type: "module"` vs CommonJS configs (`postcss.config.js`, `vite.config.js`) where needed: - Suggest renaming to `.cjs` or adjusting exports when Node emits module-type warnings. 5. **Handle WebContainer-specific issues** - Respect `package.webcontainer.json` when present: - Use its scripts and dependency versions as the source of truth. - If multiple package manifests exist (`package.json`, `package.webcontainer.json`): - Clarify which one WebContainers will use and ensure scripts/deps are consistent. - Use `onlyBuiltDependencies` behavior from `pnpm-workspace.yaml` to avoid suggesting changes that require native builds not supported in WebContainers. 6. **Dependency and peer warning handling** - When `pnpm` reports newer versions: - Distinguish between: - Informational “newer version available” messages, and - Actual install/peer conflicts that break the build. - For peer warnings (e.g., React 19 with packages that list React 18): - Explain the risk but do not downgrade automatically. - Only recommend version changes if they are directly related to the error being debugged. 7. **Iterative auto-fix behavior** - For each error the user posts: - Parse the message and stack to identify the failing file or config. - Propose the **smallest, explicit change** that will fix that error. - After one fix, be ready to handle the next error in sequence—do not try to rewrite the whole project. - Prefer editing existing files over suggesting new complex scaffolds. ## Prevention & Continuous Verification ✅ To keep alias/import resolution errors from recurring, adopt proactive checks and automated validation across developer workflows and CI: - CI import & build checks - Add a PR-gated CI job that runs one or more of: - Type-check: `npx tsc --noEmit` (for TypeScript projects) - Project build: `pnpm run build` or `npx vite build --silent` - Fail PRs when import resolution or builds fail; require green checks before merging. - Repo scripts & pre-push hooks - Add a lightweight script (e.g., `scripts/check-imports.js`) and an npm script `check-imports` that runs the checks above. - Run `npm run check-imports` in a `pre-push` hook (Husky) or as part of CI to block broken imports early. - Include extraction & sync in CI - If your repo relies on files embedded in docs, include extraction (e.g., extractor script) and sync steps in CI before build to ensure recovered files are evaluated by import checks. - Smoke tests & sanity checks - Add a minimal smoke test that starts the dev server and verifies a basic response or import resolution (headless or HTTP check). Run it in CI after the build step. - Templates & starter helpers - Maintain canonical helper templates (e.g., `templates/src/lib/utils.ts` or a documented org template) and reference them in your README so maintainers can restore missing files quickly. - PR checklist & badges - Add a PR checklist item: "Run `npm run check-imports` locally" or make it automatic in CI; consider a status badge for import verification. > Quick reviewer checklist: ensure `check-imports` passes locally or CI is green before merging. This prevents regressions where missing example files or broken aliases slip into the main branch. ## Output Style - Be concise and surgical: show **exact code edits** (before/after blocks) and file paths. - Use plain language and treat the user as a peer developer working quickly inside a constrained environment. - Assume they care about: - Keeping packages reasonably up-to-date. - Avoiding unnecessary major upgrades while debugging. - When multiple fixes are possible, recommend the least intrusive one first.