# Migrate from Webflow

> Move a Webflow site's content to CMS Orbit: how CMS collections, items, static pages, assets, Localization and 301 redirects map, a categories collection as a taxonomy from CSV, reading items and pages with the Data API v2, rebuilding static pages as blocks, and importing it all with redirects.

Source: https://docs.bifrostorbit.com/cms/developers/migrate-from-webflow/

Webflow is a website builder: the design, the pages and the hosting live in Webflow, and the CMS collections hold the structured content. CMS Orbit holds content only, and your developers build the website. So a Webflow migration is two jobs: bring the collections across, which maps closely, and rebuild the website's design in your own front end, with static pages becoming entries made of blocks. This guide reads the site with Webflow's Data API, turns it into an import file, and imports it with the script from [Import content with the Management API](https://docs.bifrostorbit.com/cms/developers/import-content/). The examples move the Northwilds journal, with posts, authors and categories, in English with Norwegian and German translations.

For the project around it, from the content inventory to the weeks after launch, see [Plan a migration to CMS Orbit](https://docs.bifrostorbit.com/cms/developers/plan-a-migration/).

The guide is written for the Webflow Data API v2.

## How Webflow maps to CMS Orbit

| Webflow | CMS Orbit | Notes |
| --- | --- | --- |
| Site | Space | |
| CMS collection | Content type | |
| Collection item | Entry | One item id across all locales |
| Collection template page | Your website's page for that content type | Built in your front end, with the content type's address prefix |
| Static page | An entry made of blocks | The API gives its text and images, not its layout. See [Static pages](#4-static-pages) |
| Symbols and components | Components, or shared sections | |
| Assets | Media library | Alt text per language |
| Reference, Multi-reference | Reference, References | |
| A "categories" collection | Taxonomy | Editors can extend it. See [Bring categories across](#2-bring-categories-across) |
| Localization locales | Languages in a region | Each language holds its own copy of the entry, linked as translations |
| Draft and archived items | Drafts and the bin | |
| Staging and published site | Staging and Production environments | |
| 301 redirects | Redirects | |
| Page settings: SEO and Open Graph | The entry's SEO | |
| Forms | Your website's own forms | Not content |
| Ecommerce products | Commerce Orbit | |
| Interactions, styles and custom code | Your front end | |

Field types:

| Webflow | CMS Orbit |
| --- | --- |
| Plain text | `text`, or `textarea` for several lines |
| Rich text | `richtext`, or a list of blocks |
| Image | `asset` |
| Multi-image | `assets` |
| Video link | `text` holding the address, or a video component |
| Link | `link` |
| Email, Phone | `text` |
| Number | `number` |
| Date/Time | `date` or `datetime` |
| Switch | `boolean` |
| Color | `color` |
| Option | `select` |
| File | `asset` |
| Reference | `reference` |
| Multi-reference | `references`, or `taxonomyTerms` for categories |

## Before you start

- A Webflow **site API token** with read access to the site, CMS, pages and assets, from **Site settings › Apps & integrations › API access**, and the site's id, which `GET /v2/sites` lists.
- In CMS Orbit: a space with Staging, a region and every language you need, and a management token. See "Before you start" in [Import content with the Management API](https://docs.bifrostorbit.com/cms/developers/import-content/).
- A `page` content type for static pages, allowing the `text` and `imageBlock` components, besides the journal model from [Schema as code](https://docs.bifrostorbit.com/cms/developers/schema-as-code/).
- Node 24, which runs the TypeScript scripts below as they are. Work in a folder whose `package.json` has `"type": "module"`, such as one made with `npm init -y && npm pkg set type=module`.

## 1. Recreate the model

`GET /v2/sites/{site_id}/collections` lists the collections, and `GET /v2/collections/{collection_id}` each one's fields with their `slug` and `type`. For each collection, write a CMS Orbit content type with the field types in the table above. Write them in a `schema.mjs` and create them with [Schema as code](https://docs.bifrostorbit.com/cms/developers/schema-as-code/).

The script below assumes the journal model from that guide, plus these Webflow collections:

| Webflow | CMS Orbit |
| --- | --- |
| Blog Posts (`blog`) with `name`, `slug`, `summary`, `post-body`, `main-image`, `published-date`, `author` (Reference) and `categories` (Multi-reference) | `journalPost` |
| Authors (`authors`) with `name`, `slug`, `bio` and `picture` | `author` |
| Categories (`categories`) with `name` and `slug` | Terms of the `topics` taxonomy |

An Option field's value is the option's id, such as `a1b2c3d4`. The collection's fields list each option's `id` and `name` under `validations.options`: use them to turn ids into the values of a `select` field.

## 2. Bring categories across

A Webflow site usually tags posts through a Categories collection and a Multi-reference field. It becomes a taxonomy, and each item a term: its slug is the term's value and its name the label in each language. The script in step 3 writes `topics.csv` in CMS Orbit's own format, with a label column per language:

```csv
value,label,label:nb-NO,label:de-DE
ski-touring,Ski touring,Topptur,Skitouren
sea-kayaking,Sea kayaking,Havpadling,Seekajak
```

1. In CMS Orbit, open **Schema › Taxonomies** and create the taxonomy, with the key `topics`.
2. Choose **Import CSV** and pick `topics.csv`. The preview shows each term as new; choose **Import**.

See [Tag content with taxonomies](https://docs.bifrostorbit.com/cms/editors/taxonomies/). The [Management API](https://docs.bifrostorbit.com/cms/developers/management-api/) imports the same file with `POST /taxonomies/topics/import`.

## 3. Read and transform the site

The script reads the site's locales from `GET /v2/sites/{site_id}`, every asset from `GET /v2/sites/{site_id}/assets`, and each collection's items from `GET /v2/collections/{collection_id}/items` once per locale with `cmsLocaleId`. Everything is paged with `offset` and `limit`, at most 100 at a time, until `pagination.total`. The staged items endpoint includes drafts and changes not yet published; use `/items/live` to read only what is published. Webflow allows a limited number of requests a minute, so the script waits when it answers `429`. It reads static pages too, as in step 4, and writes `import.json` and `topics.csv`:

```ts
// webflow.ts
import { writeFile } from 'node:fs/promises'

const API = 'https://api.webflow.com/v2'
const TOKEN = process.env.WEBFLOW_TOKEN
const SITE_ID = process.env.WEBFLOW_SITE_ID
const SITE = 'https://northwilds.com'
const LANGUAGES: Record<string, string> = { en: 'en-GB', nb: 'nb-NO', de: 'de-DE' }

type Locale = { id: string; cmsLocaleId: string; tag: string; subdirectory: string }
type Image = { fileId: string; url: string; alt?: string | null }
type Item = { id: string; isArchived: boolean; isDraft: boolean; fieldData: Record<string, unknown> & { name: string; slug: string } }
type Asset = { id: string; hostedUrl: string; originalFileName: string; altText: string | null }
type Page = {
  id: string
  title: string
  slug: string
  collectionId: string | null
  draft: boolean
  archived: boolean
  publishedPath: string
  seo?: { title?: string; description?: string }
}
type DomNode =
  | { type: 'text'; text: { html: string | null; text: string | null } }
  | { type: 'image'; image: { alt: string | null; assetId: string } }
  | { type: 'component-instance'; propertyOverrides: { text?: { html: string | null; text: string | null } }[] }
  | { type: string }

type Block = { type: string; fields: Record<string, unknown>; children?: Record<string, Block[]> }
type Entry = {
  key: string
  type: string
  name: string
  slug: string
  url?: string
  fields: Record<string, unknown>
  components?: Block[]
  seo?: { title: string | null; description: string | null }
  translations?: Record<string, Partial<Entry>>
}

async function get<T>(path: string, params: Record<string, string> = {}): Promise<T> {
  for (;;) {
    const response = await fetch(`${API}${path}?${new URLSearchParams(params)}`, {
      headers: { Authorization: `Bearer ${TOKEN}`, accept: 'application/json' },
    })
    if (response.status === 429) {
      await new Promise((resolve) => setTimeout(resolve, Number(response.headers.get('retry-after') ?? 60) * 1000))
      continue
    }
    if (!response.ok) throw Object.assign(new Error(`Webflow answered ${response.status} for ${path}`), { status: response.status })
    return (await response.json()) as T
  }
}

async function all<T>(path: string, key: string, params: Record<string, string> = {}): Promise<T[]> {
  const list: T[] = []
  for (let offset = 0; ; offset += 100) {
    const page = await get<Record<string, unknown> & { pagination: { total: number } }>(path, { ...params, offset: String(offset), limit: '100' })
    list.push(...(page[key] as T[]))
    if (offset + 100 >= page.pagination.total) return list
  }
}

const site = await get<{ locales: { primary: Locale; secondary: Locale[] } }>(`/sites/${SITE_ID}`)
const main = site.locales.primary
const others = site.locales.secondary.filter((locale) => LANGUAGES[locale.tag.slice(0, 2)])
const code = (locale: Locale) => LANGUAGES[locale.tag.slice(0, 2)]

const assets = new Map((await all<Asset>(`/sites/${SITE_ID}/assets`, 'assets')).map((file) => [file.id, file]))
const { collections } = await get<{ collections: { id: string; slug: string }[] }>(`/sites/${SITE_ID}/collections`)
const collectionId = (slug: string) => collections.find((collection) => collection.slug === slug)?.id ?? ''

async function items(slug: string) {
  const byLocale: Record<string, Item[]> = {}
  for (const locale of [main, ...others]) {
    const list = await all<Item>(`/collections/${collectionId(slug)}/items`, 'items', { cmsLocaleId: locale.cmsLocaleId })
    byLocale[locale.cmsLocaleId] = list.filter((item) => !item.isArchived)
  }
  return byLocale
}

const posts = await items('blog')
const authors = await items('authors')
const categories = await items('categories')
const categorySlugs = new Map(categories[main.cmsLocaleId].map((item) => [item.id, item.fieldData.slug]))

const newUrl = (slug: string) => `/journal/${slug}`

function localPath(href: string) {
  const path = href.startsWith(SITE) ? href.slice(SITE.length) || '/' : href
  return path.replace(/^((?:\/[a-z]{2})?)\/blog\//, '$1/journal/')
}

function asset(image: Image | null | undefined) {
  if (!image?.url) return null
  const file = assets.get(image.fileId)
  return { $asset: { url: image.url, filename: file?.originalFileName, alt: image.alt ?? file?.altText ?? '' } }
}

const attribute = (html: string, name: string) => html.match(new RegExp(`${name}="([^"]*)"`))?.[1] ?? ''
const plain = (html: string) => html.replace(/<[^>]+>/g, '').trim()

function richText(html: unknown): Block[] {
  if (typeof html !== 'string' || !html) return []
  const local = html.replace(/href="([^"]+)"/g, (_, href: string) => `href="${localPath(href)}"`)
  const blocks: Block[] = []
  for (const part of local.split(/(<figure[^>]*>[\s\S]*?<\/figure>)/)) {
    if (part.startsWith('<figure')) {
      const img = part.match(/<img[^>]*>/)?.[0]
      const caption = part.match(/<figcaption[^>]*>([\s\S]*?)<\/figcaption>/)?.[1]
      if (img) {
        blocks.push({
          type: 'imageBlock',
          fields: { image: { $asset: { url: attribute(img, 'src'), alt: attribute(img, 'alt') } }, caption: caption ? plain(caption) : null },
        })
      } else {
        console.warn(`Left out an embed: ${part.slice(0, 80)}`)
      }
    } else if (part.trim()) {
      blocks.push({ type: 'text', fields: { text: part.trim() } })
    }
  }
  return blocks
}

function post(item: Item) {
  const data = item.fieldData
  return {
    name: data.name,
    slug: data.slug,
    url: newUrl(data.slug),
    fields: {
      excerpt: data.summary ?? null,
      publishedOn: typeof data['published-date'] === 'string' ? data['published-date'].slice(0, 10) : null,
      cover: asset(data['main-image'] as Image | undefined),
      author: data.author ? { $ref: String(data.author) } : null,
      topics: ((data.categories as string[] | undefined) ?? []).map((id) => categorySlugs.get(id)).filter(Boolean),
    },
    components: richText(data['post-body']),
  }
}

function author(item: Item) {
  const bio = richText(item.fieldData.bio).map((block) => block.fields.text).filter(Boolean).join('')
  return { name: item.fieldData.name, slug: item.fieldData.slug, fields: { bio, photo: asset(item.fieldData.picture as Image | undefined) } }
}

function translated(lists: Record<string, Item[]>, item: Item, map: (item: Item) => Omit<Entry, 'key' | 'type'>) {
  const translations: Record<string, Partial<Entry>> = {}
  for (const locale of others) {
    const other = lists[locale.cmsLocaleId].find((candidate) => candidate.id === item.id)
    if (other && JSON.stringify(other.fieldData) !== JSON.stringify(item.fieldData)) translations[code(locale)] = map(other)
  }
  return translations
}

function dom(nodes: DomNode[]): Block[] {
  const blocks: Block[] = []
  let text = ''
  const flush = () => {
    if (text.trim()) blocks.push({ type: 'text', fields: { text } })
    text = ''
  }
  for (const node of nodes) {
    if (node.type === 'text' && 'text' in node) text += node.text.html ?? `<p>${node.text.text ?? ''}</p>`
    else if (node.type === 'component-instance' && 'propertyOverrides' in node) {
      for (const override of node.propertyOverrides) text += override.text?.html ?? (override.text?.text ? `<p>${override.text.text}</p>` : '')
    } else if (node.type === 'image' && 'image' in node) {
      flush()
      const file = assets.get(node.image.assetId)
      if (file) blocks.push({ type: 'imageBlock', fields: { image: { $asset: { url: file.hostedUrl, filename: file.originalFileName, alt: node.image.alt ?? file.altText ?? '' } } } })
    }
  }
  flush()
  return blocks
}

const pages = (await all<Page>(`/sites/${SITE_ID}/pages`, 'pages')).filter((page) => !page.collectionId && !page.draft && !page.archived)
const pageEntries: Entry[] = []
for (const page of pages) {
  const content = async (localeId: string) => dom(await all<DomNode>(`/pages/${page.id}/dom`, 'nodes', { localeId }))
  const translations: Record<string, Partial<Entry>> = {}
  for (const locale of others) translations[code(locale)] = { components: await content(locale.id) }
  pageEntries.push({
    key: `page:${page.id}`,
    type: 'page',
    name: page.title,
    slug: page.slug || 'home',
    url: page.publishedPath || '/',
    fields: {},
    components: await content(main.id),
    seo: { title: page.seo?.title ?? null, description: page.seo?.description ?? null },
    translations,
  })
}

const entries: Entry[] = [
  ...authors[main.cmsLocaleId].map((item) => ({ key: item.id, type: 'author', ...author(item), translations: translated(authors, item, author) })),
  ...posts[main.cmsLocaleId].map((item) => ({ key: item.id, type: 'journalPost', ...post(item), translations: translated(posts, item, post) })),
  ...pageEntries,
]

const cell = (value: string) => (/[",;\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value)
const header = ['value', 'label', ...others.map((locale) => `label:${code(locale)}`)]
const rows = categories[main.cmsLocaleId].map((item) => [
  item.fieldData.slug,
  item.fieldData.name,
  ...others.map((locale) => categories[locale.cmsLocaleId].find((other) => other.id === item.id)?.fieldData.name ?? ''),
])
await writeFile('topics.csv', [header, ...rows].map((row) => row.map(cell).join(',')).join('\n'))

const redirects = [
  ...posts[main.cmsLocaleId].map((item) => ({ from: `/blog/${item.fieldData.slug}`, to: newUrl(item.fieldData.slug) })),
  ...others.flatMap((locale) =>
    posts[locale.cmsLocaleId].map((item) => ({
      from: `/${locale.subdirectory}/blog/${item.fieldData.slug}`,
      to: `/${locale.subdirectory}${newUrl(item.fieldData.slug)}`,
    })),
  ),
]
try {
  const existing = await get<{ redirects: { fromUrl: string; toUrl: string }[] }>(`/sites/${SITE_ID}/redirects`)
  for (const rule of existing.redirects) {
    if (/[()*%]/.test(rule.fromUrl)) console.warn(`Add this pattern by hand: ${rule.fromUrl} to ${rule.toUrl}`)
    else redirects.push({ from: rule.fromUrl, to: localPath(rule.toUrl) })
  }
} catch (error) {
  console.warn(`Could not read the site's 301 redirects (${(error as { status?: number }).status}); export them by hand`)
}

await writeFile('import.json', JSON.stringify({
  environment: 'staging',
  region: 'europe',
  locale: code(main),
  translations: others.map(code),
  entries,
  redirects,
}, null, 2))
console.log(`Wrote ${entries.length} entries and ${redirects.length} redirects to import.json, and ${rows.length} categories to topics.csv`)
```

```bash
export WEBFLOW_TOKEN=<site API token> WEBFLOW_SITE_ID=<site id>
node webflow.ts
```

What it does with the parts that need thought:

- **Rich text** arrives as HTML. Each `<figure>` with an image becomes an `imageBlock` with its alt text and caption, since rich text in CMS Orbit holds no images, and the HTML between becomes `text` blocks. A `<figure>` holding a video or another embed is left out with a warning: map it to a component of your own if your website shows it. Webflow's classes are removed when CMS Orbit saves the text.
- **References:** an item has one id across locales, so a Reference to an author becomes a `$ref` to that id. The Multi-reference to categories becomes the categories' slugs, the values of the terms in `topics.csv`.
- **Images** keep their address on Webflow's asset CDN, and the import downloads them from there. Each image's `alt` in the item, or the asset's alt text in the Assets panel, becomes its alt text in the main language.
- **Locales:** each item has a variant per locale, read with its `cmsLocaleId`. A variant that differs from the main one becomes a translation with its own name, slug and address. `LANGUAGES` maps Webflow's locale tags to CMS Orbit's codes; check the subdirectories match the language addresses on your new website.
- **Drafts and archived items:** archived items are left out. Draft items come across as drafts, like everything else: CMS Orbit publishes only when you ask.
- **Addresses:** a Webflow item lives at `/<collection slug>/<item slug>`, here `/blog/…`. `redirects` sends each one, in every locale's subdirectory, to `/journal/…`.
- **301 redirects:** on an Enterprise workspace, the script reads the site's redirects with `GET /v2/sites/{site_id}/redirects` and adds them. Elsewhere that answers an error, and the script carries on: copy the rules from **Site settings › Publishing › 301 redirects** into a CSV with **Old URL** and **New URL** columns and import it under **SEO › Redirects**. CMS Orbit redirects are exact addresses, so write out each address a wildcard rule covered. See [Create and import redirects](https://docs.bifrostorbit.com/cms/editors/redirects/).

## 4. Static pages

The Data API does not give a static page's layout or styles, only its content. `GET /v2/sites/{site_id}/pages` lists the pages with their title, address (`publishedPath`) and SEO and Open Graph settings, and `GET /v2/pages/{page_id}/dom` gives a page's text, its images with their alt text and asset id, and the text set on component instances, in page order and per locale with `localeId`. The script makes each static page an entry of the `page` type with that text as `text` blocks and its images as `imageBlock` blocks, at the same address, with the same SEO title and description.

Treat these as a starting point, not finished pages. Text that sat in columns, cards or a hero arrives as one run of HTML, in order. Then:

1. **Rebuild each page from components.** Most Webflow sites repeat a handful of sections, such as a hero, a feature grid, a quote and a call to action. Build each once in your front end as a component, add it to CMS Orbit, and recreate each page in the editor from those blocks, moving the imported text into them. Short sites are often quicker rebuilt by hand from the start.
2. **Shared sections** replace Symbols that repeat the same content on many pages, such as a newsletter sign-up.
3. **Scrape the published site only with care,** for a page whose content the API does not return, such as text inside custom code embeds. Read your own site's published HTML, slowly, and keep only the text and image addresses: Webflow's classes and layout wrappers are no use in rich text and are removed when CMS Orbit saves it.

Pages built from a collection template are not static pages: they become your website's page for that content type.

## 5. Import

Check the file with a dry run, then run the import, with `cms-orbit` from [Import content with the Management API](https://docs.bifrostorbit.com/cms/developers/import-content/):

```bash
npx cms-orbit import import.json --dry-run
npx cms-orbit import import.json
```

Check the entries in CMS Orbit on Staging, then run it again with `--publish`, or publish them in CMS Orbit. Promote them to Production with their redirects as described in [Plan a migration](https://docs.bifrostorbit.com/cms/developers/plan-a-migration/).

## 6. Switch the website

Webflow hosted your website, so switching means launching the new one:

1. Build the front end with one of the [quickstarts](https://docs.bifrostorbit.com/cms/developers/quickstarts/), with a component for each block and a page for each content type. See [Render components](https://docs.bifrostorbit.com/cms/developers/render-blocks/).
2. If another app read Webflow's CMS API, replace those calls with the SDK. See [Connect a website](https://docs.bifrostorbit.com/cms/developers/connect-a-website/):

   ```ts
   // Before: Webflow
   const { items } = await fetch(`${API}/collections/${blogId}/items/live?slug=${slug}`, { headers }).then((r) => r.json())

   // After: CMS Orbit
   const result = await cms.resolve({ path: `/journal/${slug}` })
   ```

3. Set up the live preview so editors see the new website beside the editor. See [Set up the live preview](https://docs.bifrostorbit.com/cms/developers/preview/).
4. Deploy the website, and check it on its own address. See [Deploy your website](https://docs.bifrostorbit.com/cms/developers/deploy-your-website/).
5. Promote the content to Production, check that old addresses redirect, then point your domain at the new website and take the Webflow site off it.

## What does not come across

- **Design, layout, styles and interactions.** Your front end holds them now.
- **Forms and their submissions.** Export submissions from Webflow before you close the site; build forms in your front end.
- **Ecommerce.** Move products and orders to Commerce Orbit separately.
- **Custom code embeds and Webflow apps.** Rebuild what you need in your front end.
- **Item history and site backups.** Each entry starts with one draft.
- **Users and roles.** People sign in with Orbit and get roles in CMS Orbit.
