Migrate from microCMS

While checking how your existing site displays, move things in this order: schema, content, then your app's connection target. The current import isn't a feature that automatically duplicates your whole microCMS service.

1. Move the schema

Prepare the schema JSON exported from microCMS, then load it in genko.me from the API creation screen (/w/your-workspace/new-api), or from Import on the target API's Schema screen (/w/your-workspace/apis/blog/schema). Check the field IDs, required settings, and multiple selections in the result, then save.

The microCMS types that convert automatically are text, textArea, richEditor, media, number, boolean, date, and select. Custom fields and any other type cause an error. Redesign things like reference fields in the new workspace. Choices, multiple selection, and the initial values of strings, numbers, and booleans carry over. For unsupported settings, read the warnings and set any constraints you need again.

If you can, keep endpoint names and field IDs the same as in the source, so you change less in your app. blog and blogs are different endpoints. Don't guess from display names. Use the actual values shown in the dashboard.

2. Move the content

In the target API's content list (/w/your-workspace/apis/blog), choose Import from the arrow icon next to "Import or export content". For CSV, use the column names from "Download import CSV template". For JSON, an array or a format with an entries or contents array is accepted. The file must be 10 MB or less, with up to 1,000 entries at a time. See Import and export for details.

"Status after import" defaults to Draft. To publish, change it to Published. This isn't a procedure that restores the source's publish status or scheduled dates as they were.

Entry IDs for List APIs are newly issued. If your site uses the ID in entry URLs, keep a table that maps old IDs to new IDs, and set up redirects from the old URLs to the new ones. Match reference fields to the new IDs as well. An Object API imports only one item, and if content already exists, it keeps that ID and replaces the content.

You need to migrate the image and file themselves separately. Download the files from the source, upload them to genko.me, and set them on the entries. Compare image alt text too. Don't judge that the image migration is done just by looking at the URLs you imported.

3. Connect from your app

In the Next.js App Router, generate the schema and client with the CLI as in the Quickstart. If you're already connected to genko.me, sync with pull.

You can replace a list with List and an entry page with View. Adjust how the components render to match your existing HTML and CSS. For custom UI such as a carousel, you can also pass data fetched with the SDK, like client.works.list(). See List and View and Fetch content for details.

Switch the places that use your existing client, and check the following.

If some entries still refer to old image URLs during the migration, keep the old image domain allowed too.

4. Switch webhooks and production

Your microCMS signature verification code won't work as it is. Change it to match genko.me's X-Genko-Signature and event format. See Webhook signature verification and update notifications.

Set GENKO_API_KEY on your hosting provider too, along with the webhook secret if you use webhooks. Local environment variables aren't forwarded automatically. If your setup statically generates entries during a Docker build, the API key must be available at build time too. Don't write the key directly in a Dockerfile or in Git.

5. Confirm the switch

Compare the number of published entries, body text, choices, links, and images with the source, then open the list and an entry page in production. Also check that publishing, updating, and unpublishing show up on your site. Shut down the old service only after you've confirmed nothing still accesses the old URLs or refers to old images.