Migration paths

Who this is for. A lead planning a change of shape or engine on a site that is already live, or a team at kickoff weighing what changing course later would cost. After this page you can tell an incremental change from a rewrite, and size each in what has to change rather than in days.

The three paths at a glance

None of the three touches content. Layouts, layout areas, revisions, records, custom entities, jobs, members, forms and commerce behave the same in every shape (What the choice does not change). What differs is how much of the code is written again.

Server-side to hybrid: incremental and safe

Hybrid is server-side with additions. The mechanism is three pieces: a fragment template that switches caching off, a dispatcher that serves fragments by name, and a script that fetches them after the cached page has painted (Dynamic fragments). Adding the first fragment changes nothing about a cached page that is already correct, so you convert one page at a time and release each step on its own.

The order to work in

1. Move the three elements that always need a fragment: sign-in state, the cart count and personalised blocks (The three things that always need a fragment).
2. Build the one client module that carries the CSRF token, once, for every script that writes to the platform (One client module, carrying the CSRF token).
3. Where a feature should be switchable, gate its bundle with a site-data switch, so that it loads only when it is on (A personalisation bundle that loads only when it is on).

How big it is

Count the per-visitor elements on the site: each becomes its own fragment, with its own decision about what its cache varies by. Add one client module, built once, and one site-data switch for each feature that should be switchable. That count is the estimate. The cached pages around the fragments stay as they are.

Hybrid to headless: a rewrite, not a refactor

A hybrid site looks halfway to headless, because parts of it already talk to the API. It is not. The platform still composes every page of a hybrid site: routing, template resolution, the page cache, revisions and live preview, SEO output, the sitemap, error pages, forms and member sign-in are all built in (What the platform does that you do not write). A headless build gives up every one of them, and the front end rebuilds what it needs: a router for every record type with a URL, rewrites and redirects, 404 and error pages, SEO tags, the sitemap, caching and invalidation, and preview (What a headless build gives up).

Why the islands do not carry over

The hybrid site's client module is built for a page the platform rendered and a visitor's signed-in session on it. It sends the CSRF token only when someone is signed in, only with POST, PUT, PATCH and DELETE, and sends no Authorization header (One client module, carrying the CSRF token). A headless front end authenticates as an external application instead, with OAuth (the preferred credential) or an API key (the older option), as Authenticating an external application describes, and it composes the whole page itself. So the shell, the routing and the islands are rebuilt together, not adapted in place.

How big it is

Take every row of the worksheet on What a headless build must rebuild and multiply it by every kind of record the site has with a URL: pages, blog posts, book pages, product descriptions and custom entity records, each with its own route. That is the estimate. It is not a conversion of the existing templates: it is a second application, and it is planned, staffed and tested as one.

Switching template engine: every template, no data

The template engine is one setting for the whole site, Globals.template.engine: Smarty by default, Twig for a Twig site. It is set in the site's .settings.json, not in the admin, so changing it is a deployment, not a content operation.

Content does not depend on the engine. Layout areas, revisions and records are read the same way by either, so a switch changes no data. What it changes is every template: the platform renders every template of a site with the one engine that setting names, so the whole set moves at once, not one template or one folder at a time.

It is not only the templates folder

Three kinds of template code stored in records are rendered by the same engine, and move in the same migration:

• Jobs: the template code written into a job's actions.
• Discount rules: a template condition, whose code decides whether the discount applies.
• Shipping: a template shipping method, whose code works out the rate.

All three use the site's engine, so none of them can stay on the old one while the templates move. The same holds on a headless site: What the choice does not change notes that the platform still renders some templates there, such as those inside jobs.

How big it is

Every .html file under templates/, translated line by line: Smarty's modifiers and PHP function calls each have a Twig equivalent to find, and Twig's filters and tests each have a Smarty equivalent. Then every job action, discount condition and template shipping method written in the old engine's syntax. Guide 2, on the template languages, maps one engine onto the other. Nothing about content, revisions or records changes.