Update Guide

Because spartan uses a hybrid architecture, updates work differently for brain (npm packages) and helm (code you own). Here's how to update each part safely.

Brain and CLI packages are installed from npm. Keep them on the same version and update with:

After updating brain and cli packages, run the health check tool to automatically apply any necessary migrations:

The health check will update import paths, migrate deprecated APIs, and flag any breaking changes that need manual attention. See the health checks documentation for details.

Helm code lives in your repository. You own it, which means updates work differently.

Option 1: Manual Updates (Recommended)

If you've customized your helm components, update them manually:

1. Check the changelog for component changes
2. Review the updated component code on GitHub
3. Apply changes to your customized components
4. Test your changes

This approach preserves your customizations while incorporating new features or fixes.

Option 2: Automated Migration

The CLI can replace helm components with the latest versions:

1. Check for updates: Review the changelog to see what's changed
2. Update brain and cli: Run pnpm/npm/yarn/bun update @spartan-ng/brain @spartan-ng/cli
3. Run health checks: Let the CLI apply automated migrations
4. Update helm manually: Review and apply changes to customized components
5. Test: Run your e2e tests to verify everything works

Brain and helm versions don't need to match exactly. The brain package handles behavior and accessibility, while helm handles styling. As long as you're using compatible versions (typically within the same major version), they'll work together.

If you're on an older version of spartan, check the health check output for compatibility warnings.