Tern LogoTern

Core Concepts

Tern helps you plan, execute, and refine large-scale code migrations. Here’s how it works.

Migrations

A migration is your top-level project. Think “Upgrade to React 18” or “Migrate from Enzyme to React Testing Library.”

Each migration:

  • Has a name and start date
  • Links to one or more repos
  • Contains a hierarchy of tasks
  • Lives in your organization

Migrations help you organize complex work that touches multiple files across multiple repositories.

Tasks

Tasks are units of work inside a migration. They’re hierarchical - parent tasks can contain subtasks for breaking down complex migrations.

Each task has a search query (to find matching code), notes with transformation instructions (Task Instructions), and optional parent task for organization. Example: “Convert Button component tests” with search file:Button.test.tsx and transformation steps.

Task Hierarchies

Tasks can nest to organize work:

React 18 Migration
├── Breaking Changes
│   ├── Migrate ReactDOM.render to createRoot
│   └── Add children prop to FC types
├── Dependency Upgrades
│   ├── Upgrade React packages
│   └── Upgrade MobX to 7.4.0+
└── Test Updates
    └── Migrate Enzyme to React Testing Library

This structure helps you see the big picture, track progress, and understand dependencies between changes.

Workflows

When you have transformation instructions that need to run on many files, workflows execute them consistently. Each file gets the same steps, but with its own context - Tern stores information between steps so later steps can use what earlier steps learned. Validation runs after each step to catch failures early.

Example: 500 files with 5 transformation steps means 2,500 individual executions, all running the same logic but handling each file’s specific patterns.

Repos

Migrations often touch multiple codebases - upgrading a shared library affects all services that use it, or you’re standardizing patterns across a monorepo. Associate multiple repos with a migration and Tern searches all of them when finding matches for your tasks.

Your code stays local. Tern links to repos on your filesystem via the CLI and runs all searches and transformations there.

Next Steps