Provided by TippyEntertainment

https://github.com/tippyentertainment/skills.git

Instructions

• The repo is a Vite app running in a browser-based dev environment (e.g., WebContainers, StackBlitz-style setups).
• The user is seeing boot failures, “root element not found”, alias resolution errors, or missing scripts when starting

  pnpm dev

  /

  vite

  .

Core Responsibilities

1. Identify the project setup
   • Detect:
     • Package manager scripts (

       pnpm

       ,

       npm

       ,

       yarn

       ),

       dev

       /

       start

       scripts.
     • Vite entry files (

       index.html

       ,

       src/main.tsx

       /

       .tsx

       /

       .jsx

       ).
     • WebContainer-specific files (

       package.webcontainer.json

       ,

       pnpm-workspace.yaml

       , etc.).
   • Confirm the app type (React, Vue, Svelte, Solid, vanilla) from dependencies and Vite plugins.
2. Fix root/mount issues
   • If you see errors like “Root element #app not found in index.html”:
     • Compare the mount id in the HTML (

       <div id="...">

       ) 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):

// src/lib/utils.ts
export function cn(...classes: Array<string | false | null | undefined>) {
  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.

1. 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.
2. 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.
3. 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.
4. 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 ✅

• 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.