How to Fix npm run build Failures After Merging a Worktree in the AI Website Cloner Template

When npm run build fails after merging a worktree in the AI Website Cloner Template, it indicates that parallel builder agents have introduced TypeScript errors, missing assets, or configuration drift that breaks the Next.js production pipeline.

The AI Website Cloner Template utilizes isolated Git worktrees to enable multiple builder agents to develop components simultaneously. When these worktree branches merge back into the main branch, the repository must compile cleanly with npm run build—otherwise the website clone is considered broken. Understanding the precise failure points in this parallel development workflow is essential for restoring a production-ready build.

How the Parallel Build Pipeline Works

Worktree Creation and Agent Isolation

Each builder agent operates in a sandboxed Git worktree with a fresh branch, isolating changes from the main codebase. According to the @opencode-ai/sdk worktree API (documented in node_modules/@opencode-ai/sdk/dist/v2/gen/types.gen.d.ts), this architecture prevents collisions between concurrent component implementations while allowing parallel extraction and building.

Component Specification and Validation

Before code generation, the extractor creates a spec file under docs/research/components/<Component>.spec.md containing exact CSS values, asset paths, and interaction models. Builders must verify their implementation against this spec using npx tsc --noEmit before finishing, as mandated in .windsurf/workflows/clone-website.md.

Merge and Verification Protocol

After a worktree branch merges into main, the workflow immediately runs npm run build to guarantee production readiness. The CI pipeline in .github/workflows/ci.yml subsequently re-runs this build check on every push, ensuring that merged worktrees never introduce regressions.

Common Root Causes of Build Failures After Worktree Merge

TypeScript Compilation Errors

The most frequent failure mode involves error TSxxxx messages from the TypeScript compiler. Check for missing imports, mismatched prop types, or undefined interfaces by running npm run typecheck or npx tsc --noEmit locally.

Missing Static Assets

ENOENT errors for files in public/images/ indicate that the extraction script (scripts/download-assets.mjs) failed to download referenced assets. Verify that all images referenced in component specs exist in the public/ directory.

Tailwind CSS Configuration Drift

Builds fail when Tailwind v4 tokens (defined using oklch in src/app/globals.css) are missing or when postcss.config.mjs contains invalid paths. Ensure the content array in tailwind.config.cjs includes all src/**/*.tsx files.

shadcn/ui Component Mismatches

Errors like Component 'Button' does not exist occur when src/components/ui/button.tsx is missing or exports mismatch the spec. Compare the implementation against docs/research/components/<Component>.spec.md for exact API compliance.

Git Worktree Residue

Stray .git directories from previous worktrees confuse the Next.js compiler. Run git worktree prune to clean stale references before building.

Unresolved Merge Conflicts

Conflict markers (<<<<<<< HEAD) accidentally committed during the merge will break the build. Inspect merged files for these artifacts using git diff.

Step-by-Step Troubleshooting Workflow

First, verify repository state and clean worktree references:

git status
git worktree list
git worktree prune

Run the TypeScript checker to catch compilation errors without waiting for a full build:

npm run typecheck

# Alternative: npx tsc --noEmit

Fix any import errors in src/components/ and ensure all props match their interface definitions.

Verify static assets are present:

ls public/images

# If missing, regenerate:

node scripts/download-assets.mjs

Execute the production build locally to identify specific failure points:

npm run build

If the build fails, note the file and line number (e.g., src/app/layout.tsx:42:5), then compare the component against its specification in docs/research/components/.

Check Tailwind configuration:

npm run lint

# Verify tailwind.config.cjs includes src/**/*.tsx

Run the complete validation suite:

npm run check

# Runs lint, typecheck, and build sequentially

Preventive Measures for Clean Worktree Merges

• Always run npx tsc --noEmit inside the worktree before merging to catch TypeScript errors early.
• Maintain exhaustive spec files in docs/research/components/ to ensure all assets and design tokens are documented.
• Resolve merge conflicts immediately—never commit files containing <<<<<<< markers.
• Prune stale worktrees after each merge using git worktree prune to prevent .git directory pollution.
• Validate against CI by running .github/workflows/ci.yml steps locally before pushing changes upstream.

Summary

• Parallel builder agents use Git worktrees to isolate component development, but merges must pass npm run build to be considered valid.
• TypeScript compilation errors, missing assets in public/images/, and Tailwind configuration drift are the primary causes of post-merge build failures.
• Systematic verification using npm run typecheck, git worktree prune, and npm run check resolves most issues before they reach CI.
• Spec-driven development requires comparing all implementations against their docs/research/components/*.spec.md files to ensure exact compliance.
• Preventive hygiene includes pruning worktrees and validating builds inside the worktree before merging.

Frequently Asked Questions

Why does npm run build fail only after merging but not in the worktree?

The main branch may contain conflicting code that wasn't present in the isolated worktree, or the merge process introduced conflict markers. Additionally, the public/ directory or global CSS variables in src/app/globals.css might differ between branches, causing asset resolution failures only visible after integration.

How do I reset a broken worktree without losing the main branch?

Use the OpenCode SDK command opencode worktree reset --branch <branch-name> to reset the specific worktree while preserving main branch integrity. This command is documented in node_modules/@opencode-ai/sdk/dist/v2/gen/sdk.gen.d.ts at line 484. Alternatively, manually remove the worktree directory and run git worktree prune to clean up references.

What should I check first when the build fails with "Cannot find module" errors?

Verify that the missing module is a shadcn/ui component in src/components/ui/ and that the import path matches the alias defined in your configuration. Check that the component file wasn't excluded during merge or that the public/ assets it references weren't deleted by git worktree prune or merge conflicts.

Can I run the build verification inside the worktree before merging?

Yes, and you should. Run npx tsc --noEmit and npm run build inside the worktree directory before executing the merge. This catches errors that would otherwise break the main branch, though you must still verify that global files like src/app/layout.tsx and src/app/globals.css remain compatible after integration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}