DEV Community: kanawut korsang

Moving off WordPress with an import script you can re-run until launch day

kanawut korsang — Fri, 06 Nov 2026 03:52:19 +0000

A WordPress move usually starts with Tools → Export. You get one XML file, import it, and spend a week fixing what came out wrong. Meanwhile the editors keep publishing on the old site, so by launch day the snapshot is out of date and someone copies the last posts by hand.
I prefer a different shape: an import script that reads the live WordPress site and writes into the new CMS, and that you can run as many times as you like. The first run shows you what breaks. You fix the mapping and run it again. On launch day you run it one last time, and the final posts come across with everything else.
This post walks through such a script. The target is Easy CMS, the embedded CMS for Nuxt and Next.js I wrote about in the first post in this series, but the ideas apply to any CMS with a programmatic API. The full script is in the WordPress recipe; here I'll go through the parts that make it safe to repeat.
[TODO: your story — one line on a WordPress move where a one-shot export went stale, or delete this line]

Read from the REST API, not the database

Every WordPress site serves a REST API at /wp-json/wp/v2/, unless a plugin turned it off. That means no plugin to install, no SSH and no database dump. You can point the script at the production site and it only reads what visitors can already see: published posts and pages.
The script asks for 100 items a page (per_page=100, the API's maximum) and stops at the count WordPress sends in the x-wp-totalpages header. Posts are fetched with &_embed=wp:featuredmedia, so the featured image's URL and alt text come in the same response.

Every document remembers where it came from

This is the whole trick. Each imported collection gets a wpId field, unique, and the script matches on it:

// easy-cms.config.ts (excerpt)
{
  slug: 'posts',
  drafts: true,
  useAsTitle: 'title',
  fields: [
    { name: 'title', type: 'text', required: true },
    { name: 'slug', type: 'slug', from: 'title' },
    { name: 'body', type: 'richText' },
    // …excerpt, publishedAt, cover, categories
    { name: 'wpId', type: 'number', unique: true, admin: { position: 'sidebar' } },
  ],
},

// scripts/import-wordpress.ts (excerpt)
/** Creates or updates the document with this WordPress id. */
async function save(collection: 'categories' | 'posts' | 'pages', wpId: number, data: Record<string, unknown>) {
  const { docs } = await cms.find(collection, { where: { wpId: { equals: wpId } }, limit: 1, draft: true })
  return docs[0]
    ? cms.update(collection, docs[0].id, { ...data, wpId } as never)
    : cms.create(collection, { ...data, wpId } as never)
}

Why the WordPress id and not the slug? Slugs change. An editor renames a post on the old site between two runs, and a slug-based upsert creates a second copy. The id never changes. The unique flag is a safety net: if a bug ever tried to create the same item twice, the database refuses.
cms here is the Local API: createEasyCMS(config) from @easy-cms/core, called from a plain Node script with npx tsx --env-file=.env scripts/import-wordpress.ts https://old-site.com. No HTTP and no API key. The script runs as your own code, with full access.

Images: download once, also across runs

The media collection gets a unique wpUrl field. Easy CMS deliberately doesn't keep the source URL of a downloaded file, so the media table needs no extra column in every project. The script passes it in as data instead:

// scripts/import-wordpress.ts (excerpt)
const media = new Map<string, { id: number | string; url: string } | null>()
async function upload(url: string, alt = '') {
  if (!media.has(url)) {
    const { docs } = await cms.find('media', { where: { wpUrl: { equals: url } }, limit: 1 })
    try {
      media.set(url, (docs[0] ?? (await cms.uploadFromURL(url, { alt, wpUrl: url }))) as never)
    } catch (error) {
      console.warn(`  image kept as a link: ${url} (${(error as Error).message})`)
      media.set(url, null)
    }
  }
  return media.get(url) ?? null
}

The Map stops the same image downloading twice in one run; the wpUrl lookup stops it across runs. A failed download doesn't stop the import: the image keeps its old link, and the warning tells you which one.
cms.uploadFromURL() makes the server fetch a URL, which is a classic SSRF hole. So it refuses localhost, private ranges and link-local addresses such as the cloud metadata IP, checks again after DNS and after each redirect (three at most), and gives up after 15 seconds or past maxFileSize. Called from your own script, it needs no config. One catch: if you test against a WordPress running on your machine, those images are on a private address. Set upload: { fromURL: { allowedHosts: ['localhost'], allowPrivate: true } } while testing, and remove it afterwards: it also opens the admin's From a link field to your network.

HTML in, rich text out

WordPress gives you rendered HTML. Easy CMS stores rich text as Tiptap JSON. @tiptap/html converts one to the other in Node, with no browser:

// scripts/import-wordpress.ts (excerpt)
const extensions = [StarterKit, Image]
async function richText(html: string) {
  const doc = generateJSON(html, extensions) as Node
  const visit = async (node: Node) => {
    if (node.type === 'image' && typeof node.attrs?.src === 'string') {
      const file = await upload(node.attrs.src, String(node.attrs.alt ?? ''))
      if (file) node.attrs.src = file.url
    }
    for (const child of node.content ?? []) await visit(child)
  }
  await visit(doc)
  return doc
}

The extension list decides what survives. Markup with no matching extension is not kept: a page builder's <div>s are unwrapped and keep their text, an <iframe> disappears entirely, and nothing warns you. That is the main thing to check after the first run (see the table below).
Titles need care too. WordPress turns dashes and quotes into entities, so title.rendered is Hello – world. The script runs titles and excerpts through the same parser and keeps only the text, so the title is stored as Hello – world.

Redirects from the old URLs

Every old URL should answer with a 301 to the new one, or you lose links and search rankings. The script adds one redirect per post and page, with @easy-cms/plugin-redirects, for example /2024/05/hello-world/ → /blog/hello-world.
Redirects follow the same rule as documents: look up what the last run stored before creating anything. The lookup only finds it if you ask for the path in the form it was stored in. The plugin normalizes every from before saving it, so the script runs the old path through the same exported normalizePath() first:

// scripts/import-wordpress.ts (excerpt)
import { normalizePath } from '@easy-cms/plugin-redirects'
/** A 301 from the old address, when it differs from the new one. */
async function redirect(oldLink: string, to: string) {
  // The path as the plugin stores it: no trailing slash, and Thai text, `%e0%b8%aa…` and
  // `%E0%B8%AA…` all as `%E0%B8%AA…`, so the next run finds it.
  const from = normalizePath(new URL(oldLink).pathname)
  if (!from || from === normalizePath(to)) return
  const { totalDocs } = await cms.find('redirects', { where: { from: { equals: from } }, limit: 0 })
  if (!totalDocs) await cms.create('redirects', { from, to, type: '301' })
}

Skip that step and the check never matches: WordPress links end in a slash the plugin drops, so the second run tries to create the same redirect and fails on the unique from column. Non-ASCII slugs, such as the Thai ones WordPress builds from Thai titles, are stored percent-encoded (/%E0%B8%82…), and since 1.4.2 they match whether a request writes the escapes in lowercase, as WordPress links do, or in uppercase, as browsers do.
Then make the site follow the redirects. In Nuxt it's a server middleware:

// server/middleware/redirects.ts
import { resolveRedirect } from '@easy-cms/plugin-redirects'
export default defineEventHandler(async (event) => {
  const url = getRequestURL(event)
  if (/^\/(_nuxt|api|admin)(\/|$)/.test(url.pathname)) return
  const redirect = await resolveRedirect(await useEasyCMS(), url)
  if (redirect) return sendRedirect(event, redirect.location, redirect.status)
})

In Next.js 16 the same call goes in proxy.ts, which runs on Node.js. Redirects are read once and kept in memory, and the visitor's query string is kept.

Old category, tag and date archive URLs aren't redirected. Add the ones that get traffic by hand in Settings → Redirects.

When slugs change

Slugs change in two more ways, and both lose links without anyone noticing.
An editor renames a post in WordPress between two runs. The next run creates a redirect from the new WordPress address, but the one the first run made still points to the post's old address on the new site, which no longer exists. So the script compares the slug with what the last run stored, and when it changed, it moves every redirect that pointed to the old address over to the new one.
A post renamed long before the move is the other half. WordPress keeps each old slug of a published post in _wp_old_slug and redirects it, so old links work today. The REST API doesn't return fields that start with _, so the script can't see them. If you can run WP-CLI on the old site, one query exports them, and the script adds a 301 for each:

wp db query "SELECT post_id, meta_value FROM $(wp db prefix)postmeta WHERE meta_key = '_wp_old_slug'" --skip-column-names > old-slugs.tsv
npx tsx --env-file=.env scripts/import-wordpress.ts https://old-site.com --old-slugs old-slugs.tsv

That step needs shell access to the old site, unlike the rest of the script. WordPress keeps old slugs for posts, not for pages. Thanks to the reader who pointed out the _wp_old_slug case in the comments.

What comes across, and what doesn't

Comes across	Doesn't
Titles, slugs, excerpts, dates	Tags and authors (add them the way categories are done)
Paragraphs, headings, lists, quotes, code, links, bold, italic	Embeds (YouTube, tweets) and other `<iframe>`s: dropped
Images in posts, featured images	Page builder layouts: the text arrives, the columns don't
Categories	Custom fields (ACF), menus, comments
Shortcodes, as the HTML WordPress renders for them	Unpublished content, unless you sign in with an application password

Shortcodes need a second look. The REST API returns content after WordPress has run them, so a working [gallery] arrives as HTML. But if the plugin that owns a shortcode is gone, WordPress leaves the text alone, and you get a paragraph that literally says [gallery id="1"]. Before launch, run richTextToPlainText() from @easy-cms/richtext over the imported bodies and look for a leftover [.
Custom post types work the same way if they're exposed in the REST API (show_in_rest): add a collection and their REST name to the loop.

Launch day

Run it locally with --limit 10 and read the posts in /admin: headings, lists, images, the cover, the categories.
Fix the mapping and run it again, as often as you need. Documents and images are updated, not copied, and existing redirects are kept, except that a renamed post's redirects follow it.
Create a migration for the new collections (npx easy-cms migrate:create wordpress). For production, run easy-cms migrate first, then the script with the production settings and NODE_ENV=production, so the schema isn't pushed into that database. On serverless hosts, make sure uploads go to S3, R2 or Vercel Blob, not to a local folder.
On staging, ask the new site for every address in the old sitemap (/wp-sitemap.xml, or /sitemap_index.xml with Yoast). The recipe's check-redirects.ts does it in one command, following redirects. Any 404 is a missing redirect, or one that ends at a page that doesn't exist.
Back up, run it one last time, switch DNS. Two things follow from the design, and you should agree with them before you start. A re-run overwrites imported documents with what WordPress has, so editors keep writing in WordPress until the switch and don't edit imported posts in the new admin until then. And the script only creates and updates: a post deleted in WordPress stays in Easy CMS.

When to stay on WordPress

If the site is mostly WooCommerce, memberships, or dozens of ACF field groups that editors depend on, this script moves only the easy part. Moving the rest is a rebuild, not an import. Headless WordPress, or simply staying, may be the better call. A script like this fits blogs, company sites and documentation, where the content is posts, pages, categories and images, and the new site is a Nuxt or Next.js app.
The pattern works without Easy CMS, too. Give every imported record its source id with a unique constraint, upsert on it, make every side effect check before it acts, and compare URLs in one normalized form. Then the import is a command you can run every day until launch, not a one-off event.

Easy CMS is MIT-licensed: github.com/maritonx/easy-cms · docs. If you try it, tell me what got in your way in the feedback issue.

Build a Nuxt blog end to end: drafts, live preview, SEO and deploy

kanawut korsang — Thu, 05 Nov 2026 05:12:45 +0000

npm run dev and an admin at /admin is the easy part of a CMS. The questions that take the time come after it. Who can see a draft? What does the editor see before pressing Publish? What does Google see? And what happens to the database when you deploy a config change?
This post answers those questions with a small Nuxt blog. It has posts, categories and site settings, pages that show only published content, drafts with live preview for editors, SEO fields with a sitemap, and a deploy with migrations. The code comes from the Nuxt example in the Easy CMS repository, trimmed down. Most of the ideas apply to any database-backed CMS you put behind a Nuxt site.
If you haven't seen Easy CMS before, the first post in this series explains what it is. The short version: it's a headless CMS that runs inside your Nuxt or Next.js app.

Setup

You need Node.js 22.19 or newer:

npx nuxi@latest init my-blog
cd my-blog
npx create-easy-cms --db sqlite --yes
npm install @easy-cms/richtext @easy-cms/plugin-seo

create-easy-cms adds the Nuxt module, writes easy-cms.config.ts, and puts a random EASY_CMS_SECRET in .env. SQLite keeps everything in cms.db until you deploy.

The content model

A blog needs three things: categories, posts, and one set of site settings. In Easy CMS, settings like these go in a global, which is a single document instead of a list.

// easy-cms.config.ts
import { defineConfig } from '@easy-cms/core'
import { sqlite } from '@easy-cms/db-sqlite'
export default defineConfig({
  secret: process.env.EASY_CMS_SECRET ?? '',
  db: sqlite({ url: process.env.DATABASE_URL ?? 'file:./cms.db' }),
  collections: [
    {
      slug: 'categories',
      admin: { editIn: 'drawer' }, // small: edit in a panel over the list
      useAsTitle: 'name',
      access: { read: () => true },
      fields: [
        { name: 'name', type: 'text', required: true },
        { name: 'slug', type: 'slug', from: 'name' },
      ],
    },
    {
      slug: 'posts',
      drafts: true, // draft / published
      versions: true, // history, and drafts that don't touch the live post
      schedule: true, // publish or unpublish at a set time
      preview: ({ doc }) => (doc.slug ? `/posts/${doc.slug}` : null),
      useAsTitle: 'title',
      access: {
        // Visitors see published posts; logged-in editors see drafts too.
        read: ({ user }) => (user ? true : { status: { equals: 'published' } }),
      },
      fields: [
        { name: 'title', type: 'text', required: true, maxLength: 120 },
        { name: 'slug', type: 'slug', from: 'title' },
        { name: 'excerpt', type: 'textarea', maxLength: 300 },
        { name: 'cover', type: 'upload' },
        { name: 'body', type: 'richText' },
        { name: 'category', type: 'relationship', to: 'categories', admin: { position: 'sidebar' } },
        { name: 'publishedAt', type: 'date', admin: { position: 'sidebar' } },
      ],
    },
  ],
  globals: [
    {
      slug: 'site',
      access: { read: () => true },
      fields: [
        { name: 'siteName', type: 'text', defaultValue: 'My Blog' },
        { name: 'tagline', type: 'text' },
      ],
    },
  ],
})

Two parts of this matter more than they look.

The access lines are required for public content. If you define no rule, only logged-in users are allowed. Categories and the site global are public on purpose.
The posts read rule returns a query, not a boolean. For visitors it adds status = published to every read, including the REST API at /api/cms/posts. So you can't forget the filter on one endpoint. In development the database follows the config, so new fields become columns when the server starts. Open /admin, create the first admin, and write a post. ## Pages that show only what visitors may see Nuxt server routes get useEasyCMS() auto-imported. The list route is simple. find returns only published documents unless you ask for drafts:

// server/api/posts/index.get.ts
export default defineEventHandler(async () => {
  const cms = await useEasyCMS()
  const { docs } = await cms.find('posts', { sort: '-publishedAt', limit: 20 })
  // Send the list page only what it shows, not every post's body.
  return docs.map((post) => ({
    title: post.title,
    slug: post.slug,
    excerpt: post.excerpt,
    category: typeof post.category === 'object' ? post.category?.name : null,
  }))
})

The single post route is where the bugs usually are. Editors should see their drafts on the real page and visitors shouldn't, and both use the same URL:

// server/api/posts/[slug].get.ts
export default defineEventHandler(async (event) => {
  const cms = await useEasyCMS()
  const user = await useEasyCMSUser(event) // the logged-in user, or null
  const { docs } = await cms.find('posts', {
    where: { slug: { equals: getRouterParam(event, 'slug') } },
    limit: 1,
    user,
    overrideAccess: false, // let the collection's read rule decide
    draft: user !== null, // editors get the pending draft
  })
  if (!docs[0]) throw createError({ statusCode: 404 })
  return docs[0]
})

These are the Local API options that matter here, with their defaults:

Option	Default	Why it matters here
`overrideAccess`	`true`	The Local API trusts server code and skips access rules.
`user`	`null`	Who the rules are checked for.
`draft`	`false`	Include drafts: with versions, a published post's pending draft.
`depth`	`1`	Populates `category`, so you get its name instead of an id.

The trap is the first row. If you write draft: true and leave overrideAccess at its default, every visitor can read drafts by guessing a slug. Passing user with overrideAccess: false lets the same rule that protects the REST API protect your page. CMSs with an in-process API often have the same default, so check it in whichever one you use.
The site name works the same way. A route returns cms.findGlobal('site'), and app.vue fetches it for the header and useHead.

Drafts that don't take the live post down

With drafts: true, new posts start as drafts. required isn't enforced on drafts, so an editor can save half a post, and Publish checks everything.
versions: true is easy to skip, and I'd turn it on for any blog. Without versions, a document has one copy, so saving a published post as a draft unpublishes it. With versions, the draft is stored next to the live post. The site keeps showing the published version, and the admin marks the post as having Unpublished changes. Every save goes into a History panel (50 versions per document by default), and you can restore any of them.

schedule: true adds a Schedule button. A Nuxt server that keeps running checks for due jobs every minute by itself. On serverless hosts nothing keeps running, so a cron has to call /api/cms/jobs/run. I'll come back to that in the deploy section.

Live preview

The preview function in the config tells the admin where a post is shown. The page needs one line:

<!-- app/pages/posts/[slug].vue -->
<script setup lang="ts">
import { renderRichText } from '@easy-cms/richtext'
const route = useRoute()
const { data: post } = await useFetch(`/api/posts/${route.params.slug}`, {
  headers: useRequestHeaders(['cookie']), // so editors see their drafts
})
useLivePreview(post) // auto-imported; does nothing outside the admin
const html = computed(() => renderRichText(post.value?.body))
</script>
<template>
  <article v-if="post">
    <p v-if="post.status === 'draft'"><strong>Draft preview</strong></p>
    <h1>{{ post.title }}</h1>
    <div v-html="html" />
  </article>
</template>

When the editor presses Preview, the admin opens your real page in a frame next to the form. On every change it sends the form to POST /api/cms/posts/:id/preview. The server returns the document as a normal read would, with relationships populated, and saves nothing. Then the admin posts that document to the frame with postMessage, and useLivePreview puts it into the ref, so the page re-renders.

The design rule this forces on you is useful anywhere: render from the document, not from the database. The page gets the rich text as JSON, so renderRichText runs in the browser too. It escapes text and drops unsafe URLs, which is why v-html is safe here. Only users who may update a post can preview it.

SEO fields and a sitemap

The SEO plugin adds a meta group (title, description, share image, and "Hide from search engines") to the collections and globals you choose. Here it's just posts:

// easy-cms.config.ts (add to the config above)
import { seoPlugin } from '@easy-cms/plugin-seo'
  admin: { siteURL: process.env.SITE_URL }, // the public address, for the sitemap
  plugins: [
    seoPlugin({
      collections: ['posts'],
      generateTitle: ({ doc }) => `${doc.title} | My Blog`,
      generateDescription: ({ doc }) => doc.excerpt,
      generateImage: ({ doc }) => doc.cover,
      generateURL: ({ doc }) => (doc.slug ? `/posts/${doc.slug}` : null),
    }),
  ],

The plugin is set up before the config it belongs to, so doc isn't typed from the collection. A generator can return a field as it reads it: text for the title, description and address, a media id or media document for the image. Any other value suggests nothing.
Editors get length meters (50–60 characters for titles and 100–150 for descriptions by default, counting a Thai letter with its marks as one), a search result preview, and Generate buttons. The buttons run your generators on the server with the unsaved form.

On the page, seoMeta reads those fields and falls back to the post's own title and excerpt:

// app/pages/posts/[slug].vue, after useFetch
import { seoMeta } from '@easy-cms/plugin-seo'
const seo = seoMeta(post.value ?? {}, {
  siteURL: useRequestURL().origin,
  url: (p) => `/posts/${p.slug}`,
  type: 'article',
})
useSeoMeta(seo.nuxt) // title, description, Open Graph, robots
useHead(seo.head) // canonical link, BlogPosting JSON-LD

useRequestURL() is fine when every page is rendered per request. If a CDN caches your pages, pass your public address instead, for the same reason as the sitemap below: the Host header comes from the client.
The sitemap is a server route:

// server/routes/sitemap.xml.ts
import { sitemapXml } from '@easy-cms/plugin-seo'
export default defineEventHandler(async (event) => {
  setHeader(event, 'content-type', 'application/xml; charset=utf-8')
  return sitemapXml(await useEasyCMS(), { page: getQuery(event).page as string | undefined })
})

It reads posts as a visitor, without a login, so drafts stay out. So does anything your read rule hides, and any post marked "Hide from search engines". Over 50,000 addresses it becomes a sitemap index. Its addresses must be absolute, which is what admin.siteURL is for: put SITE_URL=http://localhost:3000 in .env while you develop, and the public address in production. Without it, the sitemap answers 500 as soon as a post is published, and the error tells you to set admin.siteURL. Don't take the address from the request instead. A client can send any Host header, and a sitemap is often cached. The Nuxt example did that before 1.4.2. robotsTxt from the same package keeps crawlers out of /admin/ and /api/cms/ but lets them load uploaded images.
One design point worth copying: generateURL is the only place the post's address is defined. The admin's search preview, the sitemap and the hreflang links all use it, so they can't disagree with each other.

Migrations: where development and production differ

The SEO plugin adds columns to ecms_posts. In development that just happens. In production, nothing changes the schema on its own. Easy CMS refuses to start when migrations are pending, or when the config changed without one: the API answers 500 and the log says what to run.

npx easy-cms migrate:create init   # after your first model, and after every change
git add easy-cms/migrations        # review the SQL, then commit
npx easy-cms migrate               # where you deploy, before the new version starts
npx easy-cms migrate:status        # what's applied and what's pending

The Nuxt example has 22 migrations, from 20260925091723_init to 20261009020143_audit_scope. Each one is a .sql file with a .json snapshot of the schema next to it. Most are a handful of statements, and some are one line:

-- easy-cms/migrations/20261004041909_category_color.sql
-- Easy CMS migration 20261004041909_category_color (sqlite)
-- Generated from the config; review before deploying.
ALTER TABLE `ecms_categories` ADD `color` text;

The history also shows which changes need a migration. Adding a field does, and so does turning on a feature: versions created ecms_document_versions, and schedule created ecms_scheduled_jobs. Upgrading Easy CMS can need one too. The SEO plugin's "Hide from search engines" checkbox arrived as a new meta_noindex column.
Three things to know before your first deploy:

Renames lose data in development. Development push drops the old column and adds a new one. When the data matters, run migrate:create in a terminal. It asks whether a field that disappeared was renamed.
A database created by development push can't take migrations. Run them against a fresh database. Don't copy your laptop's cms.db to the server.
Each migration runs in one transaction. A failing one is rolled back and isn't recorded. ## Deploying the Nuxt build The cheapest setup that works is one Linux server with SQLite and uploads on its disk. A server that keeps running also runs scheduled jobs by itself. The VPS guide uses a systemd unit that migrates before every start:

# /etc/systemd/system/easy-cms.service (excerpt)
[Service]
User=cms
WorkingDirectory=/srv/site
Environment=NODE_ENV=production
EnvironmentFile=/srv/site/.env
ExecStartPre=/usr/bin/npx easy-cms migrate
ExecStart=/usr/bin/node .output/server/index.mjs
Restart=always

Each line in that unit is there because of a mistake that's easy to make:

Nuxt's production server doesn't read .env. Without EnvironmentFile, the API answers 500 and the log says secret: is required.
Start from the project root. file:./cms.db, the migrations and uploads/ resolve from the working directory.
Build on the server's OS and architecture. The SQLite driver ships native files. Set EASY_CMS_SETUP_CODE until the first admin exists. Otherwise whoever opens /admin first on a fresh site can make themselves admin. Behind Caddy or nginx, set easyCms: { trustProxy: true } in nuxt.config.ts so login rate limits see each visitor's IP. Serverless works too, but it needs more pieces:

	One server (VPS, Docker)	Vercel / Netlify
Database	SQLite file on the disk, or Postgres	Hosted Postgres (Neon, Netlify Database), or Turso on Vercel
Uploads	`uploads/` on the disk	Vercel Blob, Netlify Blobs, or S3
Scheduled posts	The server runs them every minute	A cron calling `/api/cms/jobs/run` with `CRON_SECRET`
Migrations	`ExecStartPre`, or before `node` in a container	Before the build: `npx easy-cms migrate && npm run build`

On Vercel's Hobby plan, cron jobs run at most once a day, so a post scheduled for 9:00 can go out hours late unless something else calls the endpoint. Edge runtimes aren't supported at all.
[TODO: your story — which host you'd pick for a small Nuxt blog and why, 1 line]

What I'd tell you before you start

Editors can't change the content model. Fields are code, so adding one means a developer, a migration and a deploy. That's the point of a code-first CMS, but it's a real cost for a team that wants to add fields itself.
Plan the database for your host. SQLite on a disk is simple until you move to serverless, and then you need Postgres or Turso. easy-cms copy can move content between databases, but it's easier to pick right the first time.
Turn on versions early. Adding them later is one more migration, and without them, a draft unpublishes the live post. The tutorial has the same steps for Next.js. The example also shows nested pages, forms built in the admin, redirects, and a Thai and English version of every post.

Easy CMS is MIT-licensed: github.com/maritonx/easy-cms · docs. If you try it, tell me what got in your way in the feedback issue.

Make a Nuxt or Next.js site readable by AI: llms.txt, robots.txt, Markdown

kanawut korsang — Mon, 26 Oct 2026 04:13:59 +0000

Ask an AI assistant about a page on your site and one of three things happens. It answers from what it learned in training, it answers from a search index it built earlier, or it fetches your page right now. In all three, a crawler read your HTML at some point. What it was allowed to read, and how easily, is the part you can shape.
I built four pieces for that into the SEO plugin of Easy CMS, my embedded CMS for Nuxt and Next.js (the first post in this series introduces it). The ideas work in any server-rendered site:

robots.txt rules for AI crawlers, by what they do.
/llms.txt, a short Markdown index of the site, and /llms-full.txt, the whole site in one file.
A Markdown URL for each page, such as /posts/hello.md.
IndexNow pings when a page changes for visitors. First, render on the server. AI crawlers generally don't run JavaScript, so a page that loads its content in the browser looks empty to them.

robots.txt: three kinds of AI crawler

"AI crawler" covers three jobs:

Group	What it does	If you block it
`training`	Collects text to train models.	Your text stays out of future training sets.
`search`	Indexes pages for AI search and for answers that cite and link them.	Your pages stop showing up as cited sources.
`user`	Opens a page because a person asked an assistant to read it.	Assistants can't fetch your page on request. Some vendors say these may not always follow robots.txt.

Each company publishes its own user-agent names, and they change, so don't copy a list from a blog post. Easy CMS keeps them in one exported constant, AI_CRAWLERS, grouped as above and updated in each release. The AI search guide shows the current list.
A common choice: stay out of training, stay visible in AI answers.

// app/robots.txt/route.ts (Next.js)
import { robotsTxt } from '@easy-cms/plugin-seo'
import config from '@/easy-cms.config'
export function GET() {
  // AI training crawlers stay out; AI search and assistants may still read and cite posts.
  const text = robotsTxt({ config, ai: { training: false } })
  return new Response(text, { headers: { 'content-type': 'text/plain; charset=utf-8' } })
}

The output, shortened:

User-agent: *
Allow: /api/cms/media/file/
Disallow: /admin/
Disallow: /api/cms/
User-agent: <one line for each crawler in the training group>
…
Disallow: /
Sitemap: https://example.com/sitemap.xml

Two choices need explaining.
Everything is allowed by default. If an upgrade started blocking a group, sites would quietly drop out of AI answers. Blocking is the site owner's business decision, so it's opt-in.
Each group repeats the base rules. A crawler follows only the most specific group that names it, without merging in User-agent: *. Add a group for one bot to disallow /search, and that bot may now crawl your admin and API. robotsTxt() adds the admin and API rules to every group it writes, including the ones you add with rules: [{ userAgent: 'SomeBot', disallow: ['/'] }]. If you write robots.txt by hand, copy your base rules into each group.

llms.txt: a table of contents, not a dump

llms.txt is a proposed standard: a Markdown file at the root that says what the site is and where its main pages are. Here's what Easy CMS generates:

# My Blog
> A blog about building websites in Thailand.
## Posts
- [Hello](https://example.com/posts/hello.md): What this blog is about.
## Pages
- [My Blog](https://example.com/)

You configure it in the plugin and serve it from a route:

// easy-cms.config.ts (excerpt)
seoPlugin({
  collections: ['posts'],
  generateURL: ({ doc }) => `/posts/${doc.slug}`,
  llms: {
    description: 'A blog about building websites in Thailand.',
    limit: 100, // newest pages per collection (the default)
    markdownURL: ({ doc, collection }) =>
      collection === 'posts' && doc.slug ? `/posts/${doc.slug}.md` : null,
  },
})

// server/routes/llms.txt.ts (Nuxt)
import { llmsTxt } from '@easy-cms/plugin-seo'
export default defineEventHandler(async (event) => {
  setHeader(event, 'content-type', 'text/markdown; charset=utf-8')
  return llmsTxt(await useEasyCMS())
})

Links are made absolute from a { siteURL } you pass, or else from admin.siteURL in the config, or serverURL when admin.siteURL is empty.
The choices behind it:

Same pages as the sitemap. Both share one function that reads documents without a login and drops anything marked "Hide from search engines", so the two files can't disagree.
100 newest per collection. llms.txt is the contents page of a book. A list of every URL is the sitemap's job.
One locale. llms.txt has nothing like hreflang, so every language would just repeat each page. It uses the default locale, or llms.locale.
A separate markdownURL. generateURL stays the address of the HTML page, because the sitemap and the search preview depend on it. /llms-full.txt (llmsFullTxt(cms)) is for tools that want the whole site in one request: every page's Markdown, newest first. It stops at about 5 MB (maxBytes) and ends with a line pointing to /llms.txt and /sitemap.xml for the rest. ## A Markdown URL for each page HTML wraps the text in navigation, footers and scripts. Markdown is just the text. docMarkdown() writes one document as Markdown: title, description, URL, published and updated dates, then the body. The body is rich text and textarea fields at the top level, plus any text inside blocks and arrays. Top-level text fields are skipped: they're usually a slug or a name, not content. If that guess is wrong for a collection, pass your own function in the plugin's markdown option. In Next.js, a dynamic segment can't carry a .md suffix, so a rewrite maps the URL onto a route:

// next.config.ts
rewrites: async () => [{ source: '/posts/:slug.md', destination: '/md/posts/:slug' }],

// app/md/posts/[slug]/route.ts
import { getEasyCMS } from '@easy-cms/next'
import { docMarkdown } from '@easy-cms/plugin-seo'
import config from '@/easy-cms.config'
export const dynamic = 'force-dynamic'
export async function GET(_request: Request, { params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const cms = await getEasyCMS(config)
  // Read as a visitor: published posts only.
  const { docs } = await cms.find('posts', {
    where: { slug: { equals: decodeURIComponent(slug) } },
    limit: 1,
    overrideAccess: false,
    user: null,
  })
  const post = docs[0]
  if (!post || post.meta.noindex) return new Response('Not found', { status: 404 })
  // The address on the site from the config (admin.siteURL), not from the request's Host.
  const url = `${cms.config.admin.siteURL.replace(/\/+$/, '')}/posts/${post.slug}`
  return new Response(docMarkdown(cms, { collection: 'posts', doc: post, url }), {
    headers: { 'content-type': 'text/markdown; charset=utf-8' },
  })
}

In Nuxt, a server middleware matches /^\/posts\/([^/]+)\.md$/ and does the same. Three details matter: read with overrideAccess: false, user: null, so only what a visitor may see comes out. Respect noindex: a page you hid from search shouldn't reappear as Markdown. And take the address from the config, not the request: a client can send any Host header, and a cached response would pass that address on to every reader.
Why not Accept: text/markdown on the normal URL? One URL with two formats looks cleaner, but many caches key on the URL alone. Unless every layer between you and the reader honors Vary: Accept, the first Markdown response gets cached and served to the next browser, or the reverse. A separate .md URL can't be mixed up.

IndexNow: tell search engines when a page changes

Crawlers come back on their own schedule. IndexNow lets you tell Bing, Yandex and the other engines that take part about a changed URL right away. Bing's index also feeds ChatGPT search and Copilot, which is why I put it in this plugin.

seoPlugin({
  // …
  indexNow: { key: process.env.INDEXNOW_KEY }, // 8–128 letters, digits or dashes, e.g. a UUID
})

Each part of the behavior has a reason:

Only changes visitors can see. Publish, edit while published, unpublish, delete. A draft saved over a published post doesn't ping, because the live page hasn't changed. This was harder than it sounds: when a draft is waiting, the previousDoc that afterChange hooks get is that draft. So the plugin reads the published state in beforeChange and compares after the save. That costs one extra read per edit, and only when IndexNow is on.
Batched. Changes are gathered for 5 seconds (delay), then sent as one request per host, up to 10,000 URLs each. Publishing 40 posts in one go means one request, not 40.
No retries. A failed send is logged and dropped. Search engines still crawl as usual, so a lost ping costs little.
Public https URLs only. localhost, IP addresses, hostnames without a dot, and .test, .local, .example, .invalid and .internal domains are skipped. Dev servers and test runs stay quiet with no config. A staging site on a real public domain will send, so leave INDEXNOW_KEY unset there. IndexNow checks ownership with a key file at /<key>.txt, and accepts only URLs under that file's location, so it must sit at the root. The examples answer it with indexNowKeyFile(cms, pathname): a catch-all app/[file]/route.ts in Next.js, a middleware in Nuxt. A plain file in public/ works too. One trade-off I accepted: the 5-second queue lives in memory. On serverless, if the function stops before it flushes, those URLs are lost. Set a shorter delay there.

Doing this without Easy CMS

Piece	What to do	The trap
robots.txt	One group per crawler category; the names come from each vendor's docs.	A named group ignores `*`, so repeat your base rules in it.
llms.txt	Title, one-line summary, newest pages per section, one locale.	Listing every URL and every language.
Markdown pages	A separate `.md` URL, read as an anonymous visitor.	Content negotiation behind a cache; leaking drafts or noindex pages.
IndexNow	Ping on visitor-visible changes, batched, public https only.	Pinging on every draft save, or from staging.

What I don't know yet

llms.txt is a proposal, not a standard every assistant reads. I can't tell you which ones use it today, or whether any of this changes where you rank. What I can say: each file costs one route, and none exposes anything a visitor couldn't already read.
[TODO: your story — one line on what you saw (e.g. which crawlers fetched /llms.txt or .md pages) after turning this on for a real site, or delete this line]

If you want the reference, the AI search guide has the Nuxt and Next.js versions of every route, and `examples/next-blog` and `examples/nuxt-blog` in the repository run them all.

Easy CMS is MIT-licensed: github.com/maritonx/easy-cms · docs. If you try it, tell me what got in your way in the feedback issue.

Building a Payload-style CMS that lives inside your Nuxt app

kanawut korsang — Wed, 21 Oct 2026 05:48:02 +0000

Nuxt has a great Git-based CMS. What it doesn't have is a mature CMS that lives inside your app and keeps content in a database, the way Payload does for Next.js. Payload runs inside a Next.js app. With Nuxt, it still runs next to your app.
I build websites for clients, some in Nuxt and some in Next.js, and I kept wanting that missing piece. So I built it: Easy CMS, an open-source (MIT) headless CMS that you install into a Nuxt or Next.js app with npm. Next.js developers are welcome too: both frameworks get the same features.

The problem

My clients build their sites in Vue or React, and they want a back office their editors can use, in Thai and in English. For a developer, that back office should be just another npm package: versioned with the app, reviewed in pull requests and deployed with it.
Here's what a Nuxt developer could pick from (as of October 2026):

Nuxt Content + Nuxt Studio. It's free, MIT and self-hosted, and it's excellent when your content is Markdown. But it's Git-based: an edit becomes a commit. It doesn't give you records in a database, roles, or data that users create.
Payload. It's great, and you can call its Local API from Nuxt. But its admin is React and needs a Next.js (or, in the v4 beta, TanStack Start) host. That means two apps, two deploys, and an admin you can't extend with Vue.
Directus or Strapi. Both are solid, but each is another server to deploy, update and keep in sync.
Sanity or Contentful. Both work well, but your content lives on their cloud. What I wanted was what Payload gives Next.js developers: content defined in code, an admin included, and one app to deploy. I wanted it for Nuxt too.

What I built

Easy CMS runs inside your app's server. You describe your content in easy-cms.config.ts, and you get an admin at /admin, a typed Local API for your pages and a REST API at /api/cms.

Try it in two minutes

Inside an existing Nuxt 4 or Next.js 15+ app (Node.js 22.12 or newer, 22.19 with Nuxt):

npm create easy-cms@latest
npm run dev   # open http://localhost:3000/admin

The command detects Nuxt or Next.js and installs the packages. It writes easy-cms.config.ts with a sample posts collection, puts a random secret in .env, and wires up the framework: a module for Nuxt, route handlers for Next.js. When you open /admin, it asks you to create the first admin.
The config is plain TypeScript:

// easy-cms.config.ts
import { defineConfig } from '@easy-cms/core'
import { sqlite } from '@easy-cms/db-sqlite'
export default defineConfig({
  secret: process.env.EASY_CMS_SECRET!,
  db: sqlite({ url: 'file:./cms.db' }),
  collections: [
    {
      slug: 'posts',
      drafts: true,
      fields: [
        { name: 'title', type: 'text', required: true },
        { name: 'slug', type: 'slug', from: 'title' },
        { name: 'body', type: 'richText' },
      ],
    },
  ],
})

Reading content in Nuxt is a server route:

// server/api/posts.get.ts
export default defineEventHandler(async () => {
  const cms = await useEasyCMS()
  return cms.find('posts', { sort: '-createdAt', limit: 10 })
})

find returns only published documents by default. post.title is typed as string because the config says it's a required text field. In development the database schema follows the config: save the file, and the admin shows the new fields.

In Next.js, you call getEasyCMS(config) in a Server Component. With no framework at all, npm create easy-cms@latest my-cms gives you a standalone server on port 4000 that any frontend can call.
The admin covers what editors usually ask for: drafts and scheduled publishing, version history with restore, live preview, a media library with folders, roles set in the admin, single sign-on, an audit log, backups and a ⌘K command palette.

How it works

┌────────────────── your Nuxt / Next.js app ──────────────────┐
│  pages ──► Local API (typed)      browsers ──► /api/cms      │
│  editors ──► /admin                                          │
│                  @easy-cms/nuxt | @easy-cms/next             │
│                        @easy-cms/core                        │
│          SQLite / Postgres (ecms_ tables) · uploads          │
└──────────────────────────────────────────────────────────────┘

The core is framework-free. @easy-cms/core is plain TypeScript built on the Web-standard Request and Response. Config, validation, access control, hooks, drafts and both APIs all live there.
Each adapter is thin. The Nuxt module and the Next.js route handlers mostly mount one handler. That's why both frameworks get the same features.
The Local API skips HTTP. Your pages call cms.find() directly, and you deploy one app.
Your data stays in your database. Easy CMS uses SQLite (a file, or Turso) or Postgres, through Drizzle. It writes to real tables and columns with an ecms_ prefix, so you can still query them with SQL.
The admin comes prebuilt. It's a Vue app that reads your config from the API and draws the forms, so you never build it. This has a cost: every feature has to work through two frameworks and a standalone server. So adapters stay as thin as possible, and end-to-end tests cover all three.

Where it fits

Here's how it compares, as of October 2026. Each of these tools is good at something:

	Runs inside a Nuxt app	Content stored in	Admin UI	Access control	License
Nuxt Content + Studio	✅	Git (files)	Vue	Login, no roles	MIT
Payload	Local API, or a separate app	Database	React	In code	MIT
Directus	Separate server	Database	Vue	Roles in the admin	Source-available
Strapi	Separate server	Database	React	Roles in the admin	MIT (Community Edition)
Easy CMS	✅ (Next.js too)	Database	Vue	Roles in the admin + rules in code	MIT

If your content is Markdown that lives in Git, use Nuxt Studio. If you're on Next.js and want the biggest ecosystem, Payload is the safe choice. Easy CMS is for content that lives in a database, with roles and an admin, inside a Nuxt or Next.js app. Other young projects are exploring this space too, like nuxt-cms.

How it was built: with AI, and with receipts

Easy CMS 1.0 came out on October 17, 22 days after the first commit. That's fast, and you should be suspicious of it. Here's the honest picture.
I build it alone, in my spare time. About half of the more than 400 commits were co-written with Claude Code, and the trailers are in the git history for anyone to check. What keeps that safe is the process around the code:

55 architecture decision records. Every decision that matters has its reasons written down, in Thai, my first language.
800+ tests. There are unit and integration tests, Playwright end-to-end tests, smoke tests of create-easy-cms with npm, pnpm, Yarn and Bun, and upgrade tests. The upgrade tests migrate databases created by older releases on every CI run.
A self-review against OWASP ASVS Level 1. It's my own review, not an external audit. That review found the worst bug so far. In the multi-tenant plugin, one helper decided two things: whether a user could read every tenant, and whether they had access to every tenant. The code looked reasonable. But once sites could have members, a customer who signed up on a shop passed that check. They could then edit other users, including the admin's password. The review flagged it as critical. The fix split the helper in two, added a test that fails on the old code, and shipped in 0.47.3 the same day. Less dramatically, a rename of config options before 1.0 touched 139 files and missed three fields in the starter template. CI caught it when the template failed to build. AI makes it cheap to write code that looks right. Tests, written decisions and reviews are how you find the code that only looks right.

When it's not a fit

Editors can't change the content model. It's code, so a developer has to.
No edge runtimes. It needs Node.js 22.12 or newer (22.19 with Nuxt). MySQL isn't supported either.
No big marketplace. There aren't many ready-made integrations yet.
Some plugins are experimental. The shop, GraphQL and MCP plugins may still change in a minor release. Everything else follows the 1.0 stability promise: breaking changes only in a major release, with an upgrade guide.

Try it, and tell me where it got in your way

Run npm create easy-cms@latest in a Nuxt or Next.js app, or click a Deploy button in the README to get a blog with its admin on Vercel or Netlify. Then tell me what got in your way in the 1.0 feedback issue. A rough sentence is fine.

Repository: github.com/maritonx/easy-cms
Docs (English and Thai): easy-cms-website.vercel.app/docs

DEV Community: kanawut korsang

Moving off WordPress with an import script you can re-run until launch day

Read from the REST API, not the database

Every document remembers where it came from

Images: download once, also across runs

HTML in, rich text out

Redirects from the old URLs

When slugs change

What comes across, and what doesn't

Launch day

When to stay on WordPress

Build a Nuxt blog end to end: drafts, live preview, SEO and deploy

Setup

The content model

Drafts that don't take the live post down

Live preview

SEO fields and a sitemap

Migrations: where development and production differ

What I'd tell you before you start

Make a Nuxt or Next.js site readable by AI: llms.txt, robots.txt, Markdown

robots.txt: three kinds of AI crawler

llms.txt: a table of contents, not a dump

IndexNow: tell search engines when a page changes

Doing this without Easy CMS

What I don't know yet

If you want the reference, the AI search guide has the Nuxt and Next.js versions of every route, and examples/next-blog and examples/nuxt-blog in the repository run them all.

Building a Payload-style CMS that lives inside your Nuxt app

The problem

What I built

Try it in two minutes

How it works

Where it fits

How it was built: with AI, and with receipts

When it's not a fit

Try it, and tell me where it got in your way

If you want the reference, the AI search guide has the Nuxt and Next.js versions of every route, and `examples/next-blog` and `examples/nuxt-blog` in the repository run them all.