> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration planning & strategy

> Plan a ButterCMS migration with a three-phase framework (plan, execute, verify), pre/post checklists, risk assessment strategies, and timeline guidance.

<Tip>
  Migrating from a specific platform? We have step-by-step guides for [Contentful](./contentful-to-buttercms) and [WordPress](./wordpress-to-buttercms).
</Tip>

## When to consider migration

Before embarking on your migration journey, ask yourself these key questions:

* **Is your current CMS lagging?** - Frequent errors, crashes, or difficulty implementing modern features
* **Is your system struggling to handle growth?** - Slowdowns as you add content, storage limits, bottlenecks in workflows
* **Slow load times affecting user experience?** - Pages taking more than a few seconds to load
* **Is your data lacking safety?** - Security breaches, missing basic security features, unpatched vulnerabilities
* **You need more adaptability** - Difficulty publishing across channels, can't create/manage APIs, limited custom content types

## The three phases of migration

Every successful content migration follows three essential phases:

### Phase 1: planning

Your objective is to properly plan what needs to be migrated, how the migration will be performed, and how success will be verified.

**Key planning activities:**

1. **Define migration goals** - What do you want to achieve with the new CMS?
2. **Audit existing content** - Create a complete inventory of pages, posts, media, and metadata
3. **Map content to ButterCMS** - Identify how content will fit into Pages, Collections, and Blog Posts
4. **Identify dependencies** - Links, references, categories, tags, authors
5. **Plan for SEO preservation** - URL structure, redirects, meta tags
6. **Set acceptance criteria** - How will you verify the migration was successful?

<Tip>Below is an example content inventory for a hypothetical site using WordPress and
how those items might map to ButterCMS. For information on the various content types,
check out our [core concepts article](../../core-concepts/content-types/overview).</Tip>

### Content inventory template

| Content Type      | Current System  | ButterCMS Equivalent     | Count | Priority |
| ----------------- | --------------- | ------------------------ | ----- | -------- |
| Blog Posts        | WordPress Posts | Blog Engine or Page Type | -     | High     |
| Static Pages      | WordPress Pages | Single Pages             | -     | High     |
| Categories        | WP Categories   | Collections              | -     | Medium   |
| Tags              | WP Tags         | Collections              | -     | Medium   |
| Authors           | WP Users        | Collections              | -     | Medium   |
| Media             | Media Library   | Media Library            | -     | High     |
| Custom Post Types | CPTs            | Page Types               | -     | Varies   |

### Phase 2: execution

Once planning is complete, execute the migration:

1. **Execute and verify backup** of your original site
2. **Disable crawlability** during migration
3. **Execute test migration** on a staging environment
4. **Verify all acceptance criteria** on staging
5. **Perform the real migration** of entire content inventory
6. **Enable the new site** and restore crawlability

<Warning>
  **Never migrate directly to production first.** Always use a staging environment to test and verify before going live.
</Warning>

### Phase 3: Verification & monitoring

After migration, thorough verification is essential:

1. Go through your acceptance criteria
2. Manually test content for any overlooked issues
3. Check performance and loading times
4. Track SEO rankings and indexing
5. Monitor analytics for any anomalies

## Migration planning checklist

### Pre-migration checklist

* [ ] Define the goals of the migration
* [ ] Back up the original site
* [ ] Check deployment and rollback capability
* [ ] Prepare analytics tracking for the new site
* [ ] Complete list of URLs and internal links
* [ ] Identify absolute vs relative URL references
* [ ] Audit asset files and references
* [ ] Review CMS-specific plugins to replicate
* [ ] Document custom styling and content annotations
* [ ] Identify interactive content requirements
* [ ] Plan for popup and signup form migration
* [ ] Plan migration of comments if applicable
* [ ] Note character encoding requirements
* [ ] Document original HTML tag structure
* [ ] List categories and tags
* [ ] Document SEO keywords
* [ ] Plan table of contents migration for series
* [ ] Document author information
* [ ] Plan user data migration if applicable

### Execution checklist

* [ ] Execute and verify backup
* [ ] Disable site crawlability
* [ ] Run test migration on staging
* [ ] Verify acceptance criteria on staging
* [ ] Update DNS if changing domains
* [ ] Perform full content migration
* [ ] Enable new site
* [ ] Restore crawlability

### Post-migration checklist

* [ ] Review all acceptance criteria
* [ ] Manual content testing
* [ ] Performance verification
* [ ] SEO verification
* [ ] Analytics monitoring
* [ ] Retire or redirect old content

## Minimizing migration risks

### Risk assessment

Before beginning, conduct a thorough risk assessment:

* Identify potential issues (data loss, functionality breakdowns, compatibility problems)
* Analyze the impact each issue could have on your business
* Create mitigation strategies for each risk

### Pilot testing

Start small with a non-critical section:

* Select a subset of content for initial migration
* Document any issues encountered
* Use learnings to inform full-scale migration

### Fallback plan

Always have a contingency:

* Maintain a fully functional version of your old CMS
* Define clear rollback criteria
* Document the rollback process

### Regular backups

Implement a robust backup strategy:

* Full site backups before major migration steps
* Incremental data backups throughout the process
* Regular testing of backup restoration

## Setting migration goals

### Define clear objectives

Ask yourself:

1. **Performance Goals** - What load time improvements do you expect?
2. **Developer Experience** - What technical capabilities do you need?
3. **Content Team Experience** - How will the authoring workflow improve?
4. **Scalability Goals** - What growth do you anticipate?
5. **Security Requirements** - What compliance or security standards must you meet?

### Establish success metrics

Define measurable targets based on your requirements. Here are example metrics to consider:

| Goal Area     | Metric              | Target                 |
| ------------- | ------------------- | ---------------------- |
| Performance   | Page load time      | \< 3 seconds           |
| SEO           | Preserved rankings  | Within 5% of baseline  |
| Content       | Migration accuracy  | 100% content preserved |
| Uptime        | Migration downtime  | \< 4 hours             |
| Team adoption | Training completion | 100% team trained      |

## Timeline considerations

### Typical migration phases

| Phase                 | Activities                                                   |
| --------------------- | ------------------------------------------------------------ |
| **Discovery**         | Content audit, requirements gathering, ButterCMS setup       |
| **Design**            | Content model design, schema creation, mapping documentation |
| **Development**       | API integration, frontend updates, migration scripts         |
| **Content Migration** | Data transfer, validation, review                            |
| **Testing**           | QA, UAT, performance testing                                 |
| **Launch**            | Go-live, monitoring, optimization                            |

<Tip>
  Break your migration into smaller milestones. This reduces risk and allows for course corrections along the way.
</Tip>