Squarespace to Storyblok Migration: Mapping WXR to Components

The short answer

There is no Squarespace to Storyblok importer, and there is no format the two share. Squarespace hands you a WordPress-oriented XML file. Storyblok expects a set of components you designed before the import started, then one HTTP POST per story against a rate-limited Management API. Everything between those two ends is a translation script you write, and on this particular pair the script has one genuinely easy part and three genuinely awkward ones.

The easy part is the post body. The awkward parts are that Storyblok will not invent a schema for you, that the export's category and tag structure cannot be trusted without inspection, and that write throughput, not conversion, sets your calendar.

Budget $5,000 to $25,000 for a 50 to 100 page site. On this pair the number moves with how many page types the export drops, how many distinct components the content actually needs, and how many stories have to be written twice because they carry relations.

What Squarespace hands you, briefly

Settings, then Advanced, then Import / Export produces one XML file. It carries layout pages, a single blog page with its posts, text blocks, image blocks, the text from embed and Instagram blocks, and gallery pages. It drops store pages, portfolios, index, album and calendar pages, every blog page after the first, page-specific headers, footers and sidebars, drafts, style settings and custom CSS. Squarespace states you cannot export from one Squarespace site and import it into another, which is the clearest available signal about what the file is for.

That is deliberately the whole treatment here. The export's limits are the subject of the Squarespace to code migration guide, and if you have not yet scoped what the file leaves behind, read that first and come back with a page inventory. If you are still deciding whether Storyblok is the right destination at all, the headless CMS migration guide covers that comparison. This page assumes both questions are settled and asks a narrower one: how does the content that survives the export become Storyblok content?

Inside the WXR file

Open the export in a text editor and the shape is immediately familiar to anyone who has handled a WordPress migration, because it is the WordPress eXtended RSS format. Four structures matter:

• <item> elements. Every unit of content is one of these. Pages, blog posts and attachments all share the same element name, so you cannot tell them apart by tag, only by what they contain.

• content:encoded. This holds the post or page body as a single HTML string. It is the whole body rather than an excerpt, which is the biggest advantage this export has over the flat CSV that other site builders produce.

• wp:postmeta. Key and value pairs hanging off an item. Whatever Squarespace chose to preserve that does not fit a standard field lands here, and the key names are the exporter's own.

• wp:attachment_url. Attachments are not a separate section of the file. They arrive interleaved with your posts as ordinary <item> elements that happen to carry this element.

And one structure that matters more than its size suggests: <category> elements, which do double duty for both categories and tags, distinguished only by a domain attribute. More on that below, because it is the part of this migration most likely to be got wrong quietly.

Storyblok has no schema-on-write

This is the constraint that reorders the whole project. Storyblok's hierarchy is Space, then nestable Folders, then Stories, then Blocks. There are two schema layers: components are block schemas, and content types are story schemas, with Storyblok's docs describing content types as a subset of components. A block is an instance of a component. bloks is the field type that nests blocks inside other blocks.

A story is created with POST /spaces/:id/stories against https://mapi.storyblok.com/v1, and the body needs name, slug, and a content object containing at least {"component": "..."}. That component name must already exist in the space, created through /spaces/:id/components. If it does not exist, the story is not created against a guessed schema. There is no schema-on-write anywhere in the product.

So the modelling decision happens before a single line of import code is useful, and on this pair the decision has a specific shape. The WXR export already gives you a body, so you are not inferring structure from nothing. What you are deciding is how much of that body should stay as one rich text field and how much should become composable blocks.

Import the file literally and you get a post content type with a richtext field holding the entire converted body. That technically works, and it produces a Storyblok space that does not behave like Storyblok: the editor gets one long text field and cannot compose anything. The opposite mistake is worse, which is inventing a deep tree of nestable components on day one that nothing in the source actually maps to.

The defensible middle is to read the bodies first. Find the constructs that recur across many posts, the gallery, the pull quote, the embed wrapper, the call to action, and make those nestable components. Leave everything else as rich text. That inventory is real work, and it is the reason this job is a migration rather than a script.

A minimum viable model for a typical Squarespace blog and marketing site looks like this:

• A page content type (is_root: true) with title, SEO fields, and a bloks field for body sections.

• A post content type (is_root: true) with title, a richtext body, a datetime published date, an asset featured image, and relation fields for author and taxonomy.

• An author content type and a taxonomy content type, both as real stories, so relations have somewhere to point.

• Nestable components (is_nestable: true) for each recurring construct you found in the bodies.

Use asset for images and multiasset for galleries. The older image and file field types are deprecated and should not go into a new space.

Post bodies are the easy part of this pair

Storyblok's rich text is JSON based on TipTap, so a root node of type: "doc" with formatting carried in a marks array on text nodes. Converting HTML into it is officially solved: @storyblok/richtext v5 ships htmlToStoryblokRichtext, along with markdownToStoryblokRichtext, and renderRichText for going the other way.

That converter handles img. It is worth being explicit about, because silent image loss during HTML to rich text conversion is a real failure mode on other CMS ingestion paths, and it is not one you have to budget for here. Feed content:encoded to htmlToStoryblokRichtext and images survive the conversion as nodes. You still have to re-host the files, which is the asset section below, but you do not have to reconstruct the body around them afterwards.

Where it stays lossy is at the edges. Squarespace's block wrappers, inline styles and embedded widgets sit outside the supported element list, and the converter has no node to put them in. Pre-process the HTML before conversion and decide per construct: strip it, flatten it, or map it to a blok node. Storyblok's rich text schema includes a blok node type, so a component can be embedded inline in a body, which is exactly where the recurring constructs you inventoried should end up.

Categories and tags: a known unknown, treated as one

In the WXR format, <category> elements carry a domain attribute that separates the two vocabularies. The obvious mapping is to branch on domain, writing categories into one field and tags into another.

Do not write that code before looking at your file. Squarespace's exact WXR dialect is not documented by Squarespace, and it is not documented by Storyblok either. No vendor publishes a specification for what Squarespace's exporter emits. Several things are therefore unknown before you open a specific export: whether domain is populated on every element, whether it is populated consistently, whether tags appear in the file at all, and whether the display name and the slug-style nicename agree with each other.

Saying so is more useful than a confident mapping table would be. The fix is cheap: audit the file first. Extract every <category> element, group by domain attribute and by value, and print the counts. It takes about ten minutes and it converts a guess into a fact about the export in front of you. The code block below does exactly that.

Then choose based on what you found rather than on what the format allows:

• If domain is populated consistently and both vocabularies are present, map them to two separate relation fields pointing at taxonomy stories.

• If domain is absent or uniform, the distinction is not in the file. Recover it from the live site's URL structure if categories drive routing, or collapse both into a single options field if they do not.

• If the distinction drives URLs you owe redirects on, reconcile it by hand from your crawl. Hand reconciliation of a few dozen terms is cheaper and safer than a heuristic applied wrongly to every post.

The failure this avoids is specific and quiet: a branch on domain that sorts everything into one bucket, producing a site where every tag became a category, which nobody notices until an editor goes looking for a tag page that does not exist.

Attachments are items, not posts

Because wp:attachment_url entries arrive as ordinary <item> elements, the most common early bug in a WXR import is a loop that iterates items and posts every one of them as a story. You end up with a space full of stories whose titles are image filenames.

Filter attachments out of the story pass and into an asset ledger before anything else runs. Then reconcile that ledger against the image URLs actually referenced inside content:encoded, because the two sets do not always agree: bodies can reference Squarespace CDN URLs that never appear as attachment items. Download from both sets while the Squarespace subscription is still live, because those CDN URLs stop being dependable once the site is gone.

Uploading each asset to Storyblok is three steps, not one:

1. A signed request to POST /spaces/:id/assets, which returns a post_url and a fields object.

2. A multipart POST to that post_url, forwarding every key in `fields` verbatim, with the file appended last. Field order in the multipart body is a common silent failure, and the symptom does not obviously point at ordering.

3. An optional finish step to mark the upload complete.

The throughput consequence is easy to miss. The multipart POST goes to object storage and does not consume your Storyblok API quota, but the signed request does. An asset-heavy site therefore burns the rate limit roughly twice as fast as a count of stories would suggest.

Relations, UUIDs, and why the import runs twice

Storyblok relations are UUID strings, and a story's UUID does not exist until the story has been created. That single fact forces the import order.

You cannot create a post that references its author and its category in the same request that creates those targets. So relational content needs two phases: create the stories with their relation fields empty, record every returned UUID in a ledger, then issue PUT requests to backfill the relations once every UUID is known. For content that carries relations, that doubles the request count against a limit that was already the tight part of the job.

A practical ordering minimises the second pass. Create taxonomy stories and author stories first, since they generally reference nothing, record their UUIDs, and only then create posts. Posts can then be written with most relations already resolved, and the backfill pass shrinks to post-to-post references and anything circular.

One more relation detail is worth knowing while you design listing pages rather than after. resolve_relations takes a component.field format, and Storyblok documents a hard ceiling of 50 stories resolved in a single request. A listing page that expects to resolve relations across more than 50 stories will not come back fully resolved. That is a modelling constraint to design around, not a bug to debug at delivery time.

Throughput is the schedule

There is no bulk story endpoint. One POST per story. The rate limits are 3 requests per second on Starter and 6 on Growth and above, and those requests include your asset signed requests and your backfill PUTs, not only story creation.

Put together, throughput rather than conversion quality determines how long the import takes. Work it out before you promise a date: add your story count, your relational stories a second time for the backfill pass, and your asset count for the signed requests, then divide by your plan's rate and add margin for backoff. Do that arithmetic against your own inventory rather than trusting a general estimate.

Three things the import script must have, all of which are otherwise learned the hard way:

• A token bucket. Not a fixed sleep between calls. Bursts around asset uploads will trip the limit even when the average rate looks safe.

• 429 handling with backoff and retry. A 429 treated as a failure rather than a retry loses content silently in the middle of a long run.

• Resumability. Persist a source-ID to story-ID ledger to disk after every successful write. An import that dies partway through must resume rather than restart, and without the ledger a re-run creates duplicates instead of continuing.

Internal links break quietly, not loudly

Bodies in content:encoded contain absolute links to the Squarespace site. Convert them and they remain perfectly valid URLs, so nothing errors, no test fails, and the new Storyblok-backed site quietly links its readers back to the old one. If the old site is later taken down, those links become 404s that no build step ever warned you about.

Rewrite links to Storyblok slugs before conversion, using the same old-path to new-slug map you are already building for redirects. Then assert it: fail the build if any occurrence of the old domain survives in converted content. Storyblok's multilink field stores {id, url, linktype, fieldtype, cached_url} with a linktype of either story or url, and internal links should be story links rather than URL links, so they keep resolving if a slug changes later.

Seats, before the handoff and not after

Storyblok's free tier is one seat. Not one editor plus an agency account, one seat in total. Growth is $99 a month for five seats. For a site you are handing to a client with an editorial team, the free tier is a development convenience rather than the plan you deliver on, and that belongs in the quote at the start rather than being discovered at handoff.

For comparison on the bill you are leaving behind, Squarespace starts from $19 a month on annual billing. Squarespace A/B tests its pricing, so check the current figure on their pricing page rather than trusting any number in an article, including this one.

Where AI agents fit, precisely

Squarespace has no official MCP server. That is a real difference from Webflow, Wix and WordPress, which all ship first-party ones. Third-party MCP servers built on Squarespace's public APIs do exist, so the accurate statement is that agent access to Squarespace exists but is not vendor-supplied. It is also worth noting that developer.squareup.com belongs to Square, a different company, and is not a Squarespace developer resource.

The practical consequence for this migration is small, because the source side of the work is a file on disk rather than a live API. You point an agent at the XML and the conversion script, which is an ordinary coding task in a repo, with a build and a diff to verify against. Agent access matters more afterwards: once the front end lives in a Git repo you own, changes to it are reviewable, testable and revertable in a way that editing inside a builder is not.

When not to do this

A five page Squarespace brochure with no blog does not need a component model, a two-phase import, or a $99 a month seat plan. The modelling work that makes Storyblok worthwhile only pays off when there is enough structured, repeating content to model.

The cases where this pair does make sense: a content archive that has outgrown a single blog page, an editorial team that needs a proper authoring interface rather than a page builder, a front end you want in your own repository, or content that has to serve more than one surface. If none of those describe your site, staying put is a defensible answer and a cheaper one.

Cost and running bill

Migration is $5,000 to $25,000 for a 50 to 100 page site. Running costs afterwards are two separate bills that people frequently merge into one and are then surprised by.

The front end is $0 to $20 a month on Cloudflare Pages, which carries no commercial-use restriction, or roughly $20 to $50 a month on Vercel. Vercel Hobby is non-commercial only and its terms explicitly cover a paid employee or consultant writing the code, so it is not an option for client work. Storyblok is a separate subscription on top of whichever host you choose, and that is where the seat question above lands.