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

> Fix npm run build failures after merging a worktree in the AI Website Cloner Template. Resolve TypeScript errors, missing assets, or config drift breaking the Next.js pipeline.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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:

```bash
git status
git worktree list
git worktree prune

```

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

```bash
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:

```bash
ls public/images

# If missing, regenerate:

node scripts/download-assets.mjs

```

Execute the production build locally to identify specific failure points:

```bash
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:

```bash
npm run lint

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

```

Run the complete validation suite:

```bash
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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx) and [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css) remain compatible after integration.