> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ensemble.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Your First Upgrade

> Step-by-step guide to upgrading Conductor to the latest version

**Target Audience**: Existing Conductor users upgrading to the latest version
**Difficulty**: Easy (5-10 minutes)
**Prerequisites**: Existing Conductor project

## Quick Upgrade

### For Most Projects

```bash theme={null}
# 1. Update your dependency
pnpm install @ensemble-edge/conductor@latest

# 2. Test everything works
pnpm test
ensemble conductor start

# 3. Deploy when ready
ensemble deploy
```

That's it! Most upgrades are seamless.

## Testing Your Upgrade

### Automated Tests

```bash theme={null}
# Run the test suite
pnpm test

# Expected: All tests should pass
```

### Manual Testing Checklist

* [ ] `pnpm install` completes without errors
* [ ] `pnpm test` shows all tests passing
* [ ] `pnpm run build` succeeds
* [ ] Dev server starts (see note above for dev container vs local)
* [ ] Homepage loads: `curl http://localhost:8787/`
* [ ] Static pages work (test 2-3 pages)
* [ ] Dynamic pages work (if using)
* [ ] API endpoints respond (if using)
* [ ] Authentication works (if configured)

### Performance Check

Compare build times before and after:

```bash theme={null}
# Before upgrade
time pnpm run build

# After upgrade
time pnpm run build

# Should be similar or faster
```

## Troubleshooting Common Issues

<AccordionGroup>
  <Accordion title="pnpm install fails">
    **Symptoms**:

    ```
    pnpm error Cannot read properties of undefined
    ```

    **Solution**:

    ```bash theme={null}
    # Clean install
    rm -rf node_modules pnpm-lock.yaml
    pnpm store prune
    pnpm install
    ```
  </Accordion>

  <Accordion title="Tests failing after upgrade">
    **Symptoms**:

    ```
    TypeError: this.ctx.waitUntil is not a function
    ```

    **Solution**:
    Update your test files to include proper ExecutionContext mock:

    ```typescript theme={null}
    const ctx = {
      waitUntil: (promise: Promise<any>) => promise,
      passThroughOnException: () => {}
    } as ExecutionContext;
    ```
  </Accordion>

  <Accordion title="Routes not working after upgrade">
    **Solution**: Rebuild and restart dev server

    ```bash theme={null}
    pnpm run build
    npx wrangler dev --local-protocol http
    ```
  </Accordion>

  <Accordion title="Dynamic routes return 404">
    **Symptoms**:

    ```
    GET /blog/my-post → 404 Not Found
    ```

    **Solution**: Check your route configuration and ensure you're using the latest version:

    ```bash theme={null}
    # Check your Conductor version
    pnpm list @ensemble-edge/conductor

    # Upgrade to latest
    pnpm install @ensemble-edge/conductor@latest
    ```
  </Accordion>

  <Accordion title="Build fails with module errors">
    **Symptoms**:

    ```
    Module "fs/promises" has been externalized
    ```

    **Solution**: These warnings are normal for Cloudflare Workers. They can be ignored.
  </Accordion>

  <Accordion title="Wrangler hangs or requests timeout">
    **Symptoms**: Dev server starts but all requests hang

    **Solution**: Use `ensemble conductor start` which handles this automatically:

    ```bash theme={null}
    ensemble conductor start
    ```
  </Accordion>

  <Accordion title="Wrangler warnings">
    **Symptoms**:

    ```
    WARNING: Unexpected fields found in build field: "watch_dirs"
    ```

    **Solution**: This is harmless and can be ignored. It's a cosmetic warning.
  </Accordion>

  <Accordion title="TypeScript errors">
    **Solution**: Update type definitions

    ```bash theme={null}
    pnpm install --save-dev @cloudflare/workers-types@latest
    ```
  </Accordion>
</AccordionGroup>

## Migration Strategies

### Strategy 1: Direct Upgrade (Recommended)

**Best for**: Most projects, minor version upgrades

```bash theme={null}
pnpm install @ensemble-edge/conductor@latest
pnpm test && pnpm run build
```

**Pros**: Fast, simple, usually works
**Cons**: May miss new features

### Strategy 2: Fresh Template Comparison

**Best for**: Major version jumps, learning new features

```bash theme={null}
# In a temporary directory
ensemble conductor init temp-project

# Compare your project with the new template
diff -r your-project/src temp-project/src
diff -r your-project/pages temp-project/pages

# Copy useful patterns from new template
```

**Pros**: Learn new features, see latest best practices
**Cons**: More time-consuming

### Strategy 3: Side-by-Side Testing

**Best for**: Critical production systems

```bash theme={null}
# Clone your project
git clone your-repo temp-test

# Upgrade in the clone
cd temp-test
pnpm install @ensemble-edge/conductor@latest

# Test thoroughly
pnpm test
ensemble conductor start

# Deploy to preview environment
ensemble deploy --env preview

# Verify in production-like environment
# Then upgrade main project
```

**Pros**: Safest approach
**Cons**: Most time-consuming

## Rollback Procedure

If you need to rollback after an upgrade:

```bash theme={null}
# 1. Check your previous version
git log package.json

# 2. Reinstall the old version
pnpm install @ensemble-edge/conductor@<previous-version>

# 3. Restore pnpm-lock.yaml from git
git checkout HEAD~1 pnpm-lock.yaml

# 4. Clean reinstall
rm -rf node_modules
pnpm install

# 5. Test
pnpm test && pnpm run build
```

## New Feature Discovery

After upgrading, check the latest template to discover new features:

### Latest Template Structure

```bash theme={null}
# Generate a new project in a temp directory
ensemble conductor init temp-project

# Explore the template
cd temp-project
tree pages/
tree agents/
tree ensembles/
```

### Compare Your Project

```bash theme={null}
# Compare pages directory
diff -r your-project/pages temp-project/pages

# Compare agent patterns
diff -r your-project/agents temp-project/agents

# Compare ensemble patterns
diff -r your-project/ensembles temp-project/ensembles
```

### Adopt New Patterns

Look for:

* New page handler patterns
* Improved agent configurations
* Better ensemble orchestration
* Updated test patterns

## Post-Upgrade Optimization

### 1. Update Test Coverage

```bash theme={null}
# Run tests with coverage
pnpm run test:coverage

# Goal: Maintain or improve coverage after upgrade
```

### 2. Performance Tuning

```bash theme={null}
# Check bundle size
pnpm run build
# Review dist/index.mjs size

# Optimize if needed
# - Remove unused imports
# - Use dynamic imports for large dependencies
# - Lazy load pages/agents
```

### 3. Update Documentation

Update your project's README with:

* [ ] Current Conductor version
* [ ] New features you're using
* [ ] Any project-specific upgrade notes

## Best Practices

### Keep Dependencies Updated

```bash theme={null}
# Check for Conductor updates regularly
pnpm outdated

# Update Conductor and related packages
pnpm update @ensemble-edge/conductor
pnpm update @cloudflare/workers-types
pnpm update wrangler
```

### Pin Versions in Production

```json theme={null}
// package.json
{
  "dependencies": {
    "@ensemble-edge/conductor": "1.8.1"  // Exact version
  }
}
```

Use exact versions in production, flexible versions in development:

* Development: `"^1.8.1"` (allows 1.8.x updates)
* Production: `"1.8.1"` (exact version only)

### Test Before Deploying

```bash theme={null}
# Always test before production deployment
pnpm test
ensemble conductor start

# Test in preview environment first
ensemble deploy --env preview

# Verify preview works, then deploy to production
ensemble deploy
```

### Keep Release Notes

Track your upgrades in a changelog:

```markdown theme={null}
# CHANGELOG.md

## 2025-11-19
- Upgraded Conductor to latest version
- All tests passing
- Deployed to production successfully
```

## Getting Help

### Issues After Upgrade

1. **Check the release notes**: [GitHub Releases](https://github.com/ensemble-edge/conductor/releases)
2. **Search GitHub Issues**: [Known Issues](https://github.com/ensemble-edge/conductor/issues)
3. **Review troubleshooting guide**: See troubleshooting section above

### Reporting Bugs

If you find issues after upgrading:

```bash theme={null}
# Gather diagnostic info
pnpm list @ensemble-edge/conductor
node --version
pnpm --version

# Include in bug report:
# - Conductor version
# - Error messages
# - Minimal reproduction
# - Expected vs actual behavior
```

[Report an issue on GitHub](https://github.com/ensemble-edge/conductor/issues/new)

## Summary

### Quick Upgrade Path

```bash theme={null}
# For most users
pnpm install @ensemble-edge/conductor@latest && pnpm test && pnpm run build
```

### If Issues Occur

```bash theme={null}
# Clean install
rm -rf node_modules pnpm-lock.yaml && pnpm install
```

### After Upgrade

* ✅ Run tests: `pnpm test`
* ✅ Test locally: `ensemble conductor start`
* ✅ Test in preview: `ensemble deploy --env preview`
* ✅ Deploy to production: `ensemble deploy`

## Next Steps

<CardGroup cols={2}>
  <Card title="Your First Project" icon="rocket" href="/conductor/getting-started/your-first-project">
    Start fresh with the latest template
  </Card>

  <Card title="Your First Website" icon="file" href="/conductor/getting-started/your-first-website">
    Learn about dynamic routing features
  </Card>

  <Card title="Testing Guide" icon="check-circle" href="/conductor/building/testing-observability">
    Update your test patterns
  </Card>

  <Card title="Changelog" icon="list" href="https://github.com/ensemble-edge/conductor/blob/master/CHANGELOG.md">
    See full version history
  </Card>
</CardGroup>

**Questions?** Check the [troubleshooting section](#troubleshooting-common-issues) or [report an issue](https://github.com/ensemble-edge/conductor/issues).