Your First Upgrade - Ensemble Edge

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

pnpm install fails

Symptoms:

pnpm error Cannot read properties of undefined

Solution:

# Clean install
rm -rf node_modules pnpm-lock.yaml
pnpm store prune
pnpm install

Tests failing after upgrade

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;

Routes not working after upgrade

Solution: Rebuild and restart dev server

pnpm run build
npx wrangler dev --local-protocol http

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:

# Check your Conductor version
pnpm list @ensemble-edge/conductor

# Upgrade to latest
pnpm install @ensemble-edge/conductor@latest

Build fails with module errors

Symptoms:

Module "fs/promises" has been externalized

Solution: These warnings are normal for Cloudflare Workers. They can be ignored.

Wrangler hangs or requests timeout

Symptoms: Dev server starts but all requests hangSolution: Use ensemble conductor start which handles this automatically:

ensemble conductor start

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.

TypeScript errors

Solution: Update type definitions

pnpm install --save-dev @cloudflare/workers-types@latest

Migration Strategies

Strategy 1: Direct Upgrade (Recommended)

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

Check the release notes: GitHub Releases
Search GitHub Issues: Known Issues
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.

​Quick Upgrade

​For Most Projects

​Testing Your Upgrade

​Automated Tests

​Manual Testing Checklist

​Performance Check

​Troubleshooting Common Issues

​Migration Strategies

​Strategy 1: Direct Upgrade (Recommended)

​Strategy 2: Fresh Template Comparison

​Strategy 3: Side-by-Side Testing

​Rollback Procedure

​New Feature Discovery

​Latest Template Structure

​Compare Your Project

​Adopt New Patterns

​Post-Upgrade Optimization

​1. Update Test Coverage

​2. Performance Tuning

​3. Update Documentation

​Best Practices

​Keep Dependencies Updated

​Pin Versions in Production

​Test Before Deploying

​Keep Release Notes

​Getting Help

​Issues After Upgrade

​Reporting Bugs

​Summary

​Quick Upgrade Path

​If Issues Occur

​After Upgrade

​Next Steps

Your First Project

Your First Website

Testing Guide

Changelog

Quick Upgrade

For Most Projects

Testing Your Upgrade

Automated Tests

Manual Testing Checklist

Performance Check

Troubleshooting Common Issues

Migration Strategies

Strategy 1: Direct Upgrade (Recommended)

Strategy 2: Fresh Template Comparison

Strategy 3: Side-by-Side Testing

Rollback Procedure

New Feature Discovery

Latest Template Structure

Compare Your Project

Adopt New Patterns

Post-Upgrade Optimization

1. Update Test Coverage

2. Performance Tuning

3. Update Documentation

Best Practices

Keep Dependencies Updated

Pin Versions in Production

Test Before Deploying

Keep Release Notes

Getting Help

Issues After Upgrade

Reporting Bugs

Summary

Quick Upgrade Path

If Issues Occur

After Upgrade

Next Steps