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
npm install @ensemble-edge/conductor@latest

# 2. Test everything works
npm test
npm run build
npx wrangler dev --local-protocol http

# 3. Deploy when ready
npm run deploy
Starting the dev server:
  • Dev Container: npx wrangler dev --local-protocol http --ip 0.0.0.0
  • Local: npx wrangler dev --local-protocol http
The --ip 0.0.0.0 flag is needed in containers to bind to all network interfaces.
That’s it! Most upgrades are seamless.

​
Testing Your Upgrade

​
Automated Tests

# Run the test suite
npm test

# Expected: All tests should pass

​
Manual Testing Checklist

  • npm install completes without errors
  • npm test shows all tests passing
  • npm 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 npm run build

# After upgrade
time npm run build

# Should be similar or faster

​
Troubleshooting Common Issues

Symptoms:
npm error Cannot read properties of undefined
Solution:
# Clean install
rm -rf node_modules package-lock.json
npm cache clean --force
npm 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
npm 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
npm list @ensemble-edge/conductor

# Upgrade to latest
npm 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 the --local-protocol http flag:
npx wrangler dev --local-protocol http
This properly binds network access for the Workers runtime.
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
npm install --save-dev @cloudflare/workers-types@latest

​
Migration Strategies

Best for: Most projects, minor version upgrades 
npm install @ensemble-edge/conductor@latest
npm test && npm 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
npx @ensemble-edge/conductor@latest 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
npm install @ensemble-edge/conductor@latest

# Test thoroughly
npm test
npm run build
npx wrangler dev --local-protocol http

# Deploy to preview environment
npx wrangler 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
npm install @ensemble-edge/conductor@<previous-version>

# 3. Restore package-lock.json from git
git checkout HEAD~1 package-lock.json

# 4. Clean reinstall
rm -rf node_modules
npm install

# 5. Test
npm test && npm 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
npx @ensemble-edge/conductor@latest 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
npm run test:coverage

# Goal: Maintain or improve coverage after upgrade

​
2. Performance Tuning

# Check bundle size
npm 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
npm outdated

# Update Conductor and related packages
npm update @ensemble-edge/conductor
npm update @cloudflare/workers-types
npm 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
npm test
npm run build
npx wrangler dev --local-protocol http

# Test in preview environment first
npx wrangler deploy --env preview

# Verify preview works, then deploy to production
npx wrangler 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
npm list @ensemble-edge/conductor
node --version
npm --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
npm install @ensemble-edge/conductor@latest && npm test && npm run build

​
If Issues Occur

# Clean install
rm -rf node_modules package-lock.json && npm install

​
After Upgrade

  • ✅ Run tests: npm test
  • ✅ Build: npm run build
  • ✅ Test locally: npx wrangler dev --local-protocol http
  • ✅ Test in preview: npx wrangler deploy --env preview
  • ✅ Deploy to production: npx wrangler deploy

​
Next Steps

Your First Project

Start fresh with the latest template

Dynamic Pages

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.