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

​
Quick Upgrade

​
For Most Projects

# 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

# 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: 
# Before upgrade
time pnpm run build

# After upgrade
time pnpm run build

# Should be similar or faster

​
Troubleshooting Common Issues

Symptoms:
pnpm error Cannot read properties of undefined
Solution:
# Clean install
rm -rf node_modules pnpm-lock.yaml
pnpm store prune
pnpm install
Symptoms:
TypeError: this.ctx.waitUntil is not a function
Solution: Update your test files to include proper ExecutionContext mock:
const ctx = {
  waitUntil: (promise: Promise<any>) => promise,
  passThroughOnException: () => {}
} as ExecutionContext;
Solution: Rebuild and restart dev server
pnpm run build
npx wrangler dev --local-protocol http
Symptoms:
GET /blog/my-post → 404 Not Found
Solution: Check your route configuration and ensure you’re using the latest version:
# Check your Conductor version
pnpm list @ensemble-edge/conductor

# Upgrade to latest
pnpm install @ensemble-edge/conductor@latest
Symptoms:
Module "fs/promises" has been externalized
Solution: These warnings are normal for Cloudflare Workers. They can be ignored.
Symptoms: Dev server starts but all requests hangSolution: Use ensemble conductor start which handles this automatically:
ensemble conductor start
Symptoms:
WARNING: Unexpected fields found in build field: "watch_dirs"
Solution: This is harmless and can be ignored. It’s a cosmetic warning.
Solution: Update type definitions
pnpm install --save-dev @cloudflare/workers-types@latest

​
Migration Strategies

Best for: Most projects, minor version upgrades 
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 
# 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 
# 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: 
# 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

# 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

# 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

# Run tests with coverage
pnpm run test:coverage

# Goal: Maintain or improve coverage after upgrade

​
2. Performance Tuning

# 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

# 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

// 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

# 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: 
# 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
  2. Search GitHub Issues: Known Issues
  3. Review troubleshooting guide: See troubleshooting section above

​
Reporting Bugs

If you find issues after upgrading: 
# 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

​
Summary

​
Quick Upgrade Path

# For most users
pnpm install @ensemble-edge/conductor@latest && pnpm test && pnpm run build

​
If Issues Occur

# 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

Your First Project

Start fresh with the latest template

Your First Website

Learn about dynamic routing features

Testing Guide

Update your test patterns

Changelog

See full version history
Questions? Check the troubleshooting section or report an issue.