Migrating from the configurator

What happens to a shop built in the block configurator and how to move to a site as code.

Until now a shop’s site was assembled from blocks in a visual editor. In ItemShop 3.0 the site is built as a project with code, and the block configurator is being retired.

Do I have to do anything now?

No. Shops built in the configurator keep working unchanged — same address, same products, same checkout — until you publish your first code site to production. Until then hosting answers 421 (“not this site”) for your shop and traffic is served by the existing storefront. Products, payments, servers, orders and discounts are not part of the migration because they don’t change at all — the code site fetches them from the Storefront API.

What carries over

You migrate onto a template (Bento by default, and Storefront for non-Minecraft shops). The look from the configurator moves into src/site.config.ts:

From the configurator	To the site (site.config.ts)
Brand colour, accent	colors.brand (+ brandHover), colors.accent — check contrast
Light/dark theme, toggle	theme.default, theme.toggle
Logo (image or text), name	logo.image / logo.text, name
Menu links	nav[] (the special terms and privacy point to the shop’s legal documents)
Footer links, social media	footer.links (external: true for Discord etc.)
Hero: title, text, button, image	hero.* (**bold** works in text)
Visibility of recent purchases, top supporters, goal	recentPurchases.show, topSpenders.show, goal.show
Server address in the header	serverAddress
Discord link	placeholders in the template replaced by your Discord (or hidden)
Languages	languages (empty = all enabled in the panel)
Email and discount codes at checkout	checkout.requireEmail, checkout.discountCodes
Content translations	Localized values in the config; product translations stay on the products

What has no 1:1 counterpart:

• the configurator’s theme.variant is a layout, not a colour — it corresponds to the template choice and hero background,
• navbar style and stickiness (navStyle, navSticky) — handled by the header CSS in the template,
• custom blocks (text, image, HTML) — recreate them as components or hero text; HTML without inline scripts,
• terms and consent texts — legal documents are served by the platform and not copied into the site.

The public-data privacy switches (recent buyers, top supporters, monthly goal, online players) keep working server-side, independently of the site.

How the migration goes

You start it in the panel: the “Move to the new shop” banner (dashboard and block editor) opens a wizard with three steps.

1. Choose a template

   The wizard lists the templates (Bento by default, marked as recommended) and a Show what we’ll move button: the list of settings that will be carried over, a list of things “to move manually” and the generated src/site.config.ts. Nothing is saved yet. Create the new shop creates the project from the template, adds a “Migration from the block editor” revision and builds a preview.

2. Check the preview

   Buyers still see the old shop. Open the preview in a new tab — it is exactly the site they will see after publishing. You can pick another template and create the site again. Ask the AI editor or your own agent (skill itemshop-migrate-legacy) to add anything that isn’t on the carried-over list.

3. Publish the new shop

   Publish the new shop switches the shop address and your domain to the new site. The owner or team approves the publication in the panel — from the CLI, MCP or the AI agent it goes through the publishing rules and without approval ends with 403 WORKSPACE_PRODUCTION_REQUIRES_APPROVAL.

Before you publish, check the whole purchase flow in the preview (nick, consents, payment choice). After publishing, players land on the new site.

Going back to the old shop

The old shop settings (configurator) are never changed during migration, so going back only switches a mode: the site returns to the “old shop” mode while the project and its revisions stay. After that, hosting answers 421 for your shop and traffic is served by the existing storefront.

For integrations

The wizard uses the /shops/{shopId}/site/migrate endpoints:

Method	Path	Scope	Action
GET	/site/migrate	site:read	State: legacy, migrating or published, with the build and preview.
GET	/site/migrate/preview?templateId=	site:read	The generated site.config.ts plus applied and skipped lists (no changes).
POST	/site/migrate	site:write	Creates the site from the template, the migration revision and a build with a preview.
POST	/site/migrate/publish	site:write	Publishes to production (publishing rules).
POST	/site/migrate/rollback	site:write	Goes back to the old shop.

For bulk runs (operators of a self-hosted install) there is the npm run migrate:legacy script with --dry-run.

What goes away

• the block configurator and its site settings panel,
• the configurator’s checkout appearance settings (checkout layout is now defined by the site code),
• the old AI assistant for blocks — replaced by the AI editor.

Site as code

How the new model works.

Templates

Bento and the other templates.