---
title: Set up and run the code migration
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

In [our demo](https://docs.kentico.com/modules/upgrade-with-kenticopilot/kenticopilot-code-migration-overview.md), you can see how KentiCopilot speeds up codebase migration from Kentico Xperience 13 (KX13) to Xperience by Kentico (XbyK). This guide is a practical next step.

It builds on [the KentiCopilot GitHub documentation](https://github.com/Kentico/xperience-by-kentico-kenticopilot/blob/main/plugins/kentico-kx13-migration/README.md#codebase-migration) and focuses on tips, best practices, and common pitfalls. You will learn what to expect in each migration phase and how to shape the workflow to fit your architecture.

## Set your workspace up for success

- **Let an AI assistant handle the setup.** GitHub Copilot, Claude, or a similar assistant can guide you through the [installation steps](https://github.com/Kentico/xperience-by-kentico-kenticopilot/tree/main/plugins/kentico-kx13-migration#set-up-your-environment) in the KentiCopilot README. If you chose to set up manually and hit an issue (e.g., due to your environment specifics), ask your AI agent to help you recover. It will save you valuable time troubleshooting.
- **Register the Documentation MCP server in one place only.** The [KentiCopilot plugins](https://github.com/Kentico/xperience-by-kentico-kenticopilot/tree/main/plugins) already declare the [Documentation MCP server](https://docs.kentico.com/documentation/developers-and-admins/installation/mcp-server.md), so you don't need to add it yourself. If the same server is also declared in your workspace `mcp.json`, remove or disable that entry. Then open your IDE's or CLI's MCP servers list and confirm that only one entry is running. A single active registration guarantees no duplicate instances or unnecessary token usage, regardless of which AI host you use.
- **Double-check your workspace setup matches our recommendations** in the [KentiCopilot GitHub documentation](https://github.com/Kentico/xperience-by-kentico-kenticopilot/blob/main/plugins/kentico-kx13-migration/README.md#codebase-migration).

> **Tip:** To avoid any human-error-related oversight, ask your AI assistant to _review your project structure and overall setup according to the docs_ for you.

![An example of asking an AI assistant to check your project structure and overall setup of your workspace](https://docs.kentico.com/docsassets/modules/set-up-and-run-the-code-migration/kenticopilot-check-setup.png "An example of asking an AI assistant to check your project structure and overall setup of your workspace")

> **Warning:** Migrate your database to Xperience by Kentico before you start migrating your code. The agent reads the target XbyK database for essential tasks, such as generating content type classes, so the code migration depends on it.
>
> See how [KentiCopilot can help you with content audit and migration](https://docs.kentico.com/modules/upgrade-with-kenticopilot/kenticopilot-content-audit-migration.md), including remodeling scenarios.

## Understand the migration workflow

There are three main parts to code migration:

- **Global code** – project-wide code that isn't tied to a single page, such as localization resources, styles, shared business logic, and project startup configuration.
- **Pages** – the controllers, views, layouts, and content retrieval logic behind each page. Pages that use [Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder.md) also have widgets and sections, which you migrate before the page logic.
- **Shared components** – reusable UI elements embedded directly in views and layouts, such as the header, footer, navigation, and breadcrumbs. These are _not_ Page Builder widgets or sections.

> **Info:** This page is intentionally not a full command walkthrough. Our [GitHub documentation](https://github.com/Kentico/xperience-by-kentico-kenticopilot/blob/main/plugins/kentico-kx13-migration/README.md#codebase-migration) provides the complete command flow and prompt syntax.

At a high level, you need to run the global migration first to seed the target project. Then migrate your pages and shared components in the order that suits your project. For pages that use _Page Builder_, migrate widgets and sections before page logic.

> **Tip:** Before you start the code migration, ask the agent to examine your project and produce an overview:
>
> - **From the codebase**: which page types are Page Builder-enabled, which shared components exist, and any component restrictions (for example, which widgets and sections are allowed in a zone).
> - **From the CI serialization files** (`App_Data/CIRepository`, if Continuous Integration is enabled): which specific pages actually use Page Builder and which widget and section types they render. If CI isn't available, this per-page usage comes from the database instead (the [KentiCopilot content-model audit skill](https://github.com/Kentico/xperience-by-kentico-kenticopilot/blob/main/plugins/kentico-kx13-migration/README.md#content-model-audit) can export it).
>
> This overview helps you decide the order in which to migrate your pages and components.
>
> ![Example output from an AI agent mapping out which page types use the Page Builder feature](https://docs.kentico.com/docsassets/modules/set-up-and-run-the-code-migration/pages-w-pb.png "Example output from an AI agent mapping out which page types use the Page Builder feature")

### What to verify after each phase

We recommend you only move forward once the current phase is stable:

- **After global migration**: the project compiles, startup runs without errors, and content type classes exist for every content type in your solution.

- **After each page migration**: the page renders correctly and the Page Builder tab appears on pages that need it.

  ![Page Builder tab enabled in Xperience by Kentico administration](https://docs.kentico.com/docsassets/modules/set-up-and-run-the-code-migration/pb-enabled.png "Page Builder tab enabled in Xperience by Kentico administration")

  > **Tip:** Consider enabling Page Builder for almost all migrated page content types, even if the KX13 original didn't use it. This keeps the option of using page templates open later. If a page is migrated without a Page Builder template registration, it can be difficult to convert afterward.

- **After component migration**: shared components render correctly across all pages that use them and have been migrated. The agent visually compares each component against the KX13 original using Playwright, and it skips components it has already migrated, so you can re-run `/migrate-shared-component` safely.

### Troubleshooting

The agent attempts to resolve build errors during migration, so most issues are handled for you. If something still does not build or render correctly, ask the agent to identify the root cause and fix it before you continue. If you're unsure what to do next, ask the agent to propose the next best migration step based on your current project state.

If a migrated page's look and feel doesn't match the KX13 original, run `/migrate-page-visual`. This skill uses Playwright to compare the migrated page against the original and realign the styling.