ReferenceUpgrading

Upgrading

Update the package and deploy. Your content model lives in your code and every build pushes it to your space: there is no migration to run.

View as Markdown

When the schema moves

Nothing to run. A space's content lives in Smoodly's service, and your content model lives in your code: every build pushes it to the space (a Next site's prebuild runs smoodly push, an Astro build does it itself), and so does the dev server. Update smoodly, build and deploy; restart the dev server after an upgrade. npx smoodly --version prints the version you have.

The migrate and rebuild commands are gone, and so is the build's schema check. Up to 0.0.51 a site's content lived in a Postgres schema it migrated itself; that history is in git, in this page as of v0.0.51.

The sections below name each version's changes to your code. Going up several versions at once, work through each section between your version and the new one, oldest first. A version without a section needs no change in your code.

Upgrading to 0.0.36

0.0.36 changes what a read returns and closes public reads.

| Before | After | |---|---| | item.entry.fields.title, item.entry.id | item.fields.title, item.id | | entry page view ({ entry, path, locale, locales }) | ({ entry }), with entry.path, entry.locale, entry.locales | | a reference in a section or an entry, f.ref or f.refList: a.slug, a.name plus your own path helper | a.fields.name, a.path | | getGlobal(...) spread into the view, every global (the Lorem starter's header in PageFrame.tsx, and the contact prop the layout passes to FooterView) | { fields, settings, styles }: <HeaderView {...header.fields} settings={header.settings} styles={header.styles} />, and contact?.fields | | a reference's path used as a string | string \| null: a reference to an entry without an address has none | | entry.fields as ArticleFields, the Lorem starter's hand-written field types, a reference's a.fields included | as unknown as ArticleFields where a component takes the hand-written type; elsewhere drop the cast, fields is typed from the collection | | getPage(...).record, .tree, .tree.meta | a page item with seo | | page registration meta: { seo: true } | seo: true | | createSmoodlyAdmin({ …, content }) | createSmoodlyAdmin({ …, presence }) | | reading content with the publishable key | not possible; a route in your app over q | | publicContent() in smoodly/server.ts, with publicContentConfig and ContentConfig | presence(), returning presenceConfig(smoodlyEnv()), typed Promise<PresenceConfig> (both from smoodly) | | a global in the layout: <Footer {...footer} /> | <Footer {...footer.fields} settings={footer.settings} styles={footer.styles} /> | | dropping missing references: .filter(Boolean) | .filter((p) => p !== null), which TypeScript narrows |

Also new: where filters the version shown and works on localized fields, references resolve as deep as their field says everywhere, and a collection can turn on seo. The Next.js guide shows the route that replaces a browser read.

Upgrading to 0.0.38

0.0.38 has no schema change. It replaces the starter's stores() with two functions in smoodly/server.ts, and the site needs one variable less.

| Before | After | |---|---| | stores() in a seed or a script | content(), the content API | | stores() and adminAuth() in smoodly/ops.ts | adminDeps(), which carries auth; delete the adminAuth export from smoodly/server.ts | | the starter's own scripts/seed.ts | it ran once, at install: delete it, the seed line in package.json, and in AGENTS.md the npm run seed line and the "Seed through the stores" rule | | hand-built tree nodes cast to PageTree | node(Section, fields) | | the site requires all three variables | the site requires SMOODLY_URL and SMOODLY_SECRET_KEY; the admin also SMOODLY_PUBLISHABLE_KEY |

In smoodly/server.ts, replace the exported stores() with these two (the stores built inside bound() stay), and add createSmoodlyContent and type SmoodlyContent to the import from smoodly/admin:

smoodly/server.ts
export function adminDeps() {
  smoodlyEnv("admin"); // the admin signs in with the publishable key: a missing one is named here, not on a live page
  const { pages, entries, assets, members, auth, site } = bound();
  // …
  return { pages, entries, assets, members, auth, href, projector: site.projector };
}
// …
export function content(): SmoodlyContent {
  const { pages, entries, assets, members, site } = bound();
  return createSmoodlyContent({ config, pages, entries, assets, members, href, projector: site.projector });
}

export { node } from "smoodly";

smoodly/ops.ts then took everything from adminDeps(); the file is gone since the admin became one route (below).

A fixed page or a collection's list page that has no record yet is now served from code, so a page type added after install no longer waits for an editor to open Pages. Cached reads are keyed by the package version and your content model, so an upgrade never serves a page cached in the old shape.

Upgrading to 0.0.40

0.0.40 has no schema change and nothing breaks. Every page and entry now gets a canonical link, and a page its Open Graph URL, both built from metadataBase. One change is worth making in your root layout:

| Before | After | |---|---| | metadataBase: new URL(process.env.SITE_URL \|\| "http://localhost:3000"), or no metadataBase in a site installed before 0.0.35 | metadataBase: siteUrl() in the root layout's metadata, with import { siteUrl } from "smoodly" |

siteUrl() names SITE_URL when it lacks https://, where the old line failed every page with a bare "Invalid URL", and warns once in production when it is unset. Also new: content().pages.list(), and an unreachable SMOODLY_URL is named in the error.

Upgrading to 0.0.44

0.0.44 has no schema change and nothing breaks. One change in smoodly/server.ts lets next build run without the keys, for a CI or a host that builds without secrets: the read helpers wait for a request before they read the environment. (0.0.44 shipped the gate as connection() from next/server; the excerpts below show today's buildGate() from smoodly/next, which 0.0.50 renamed it to.)

smoodly/server.ts
export const q = (): Queries =>
  new Proxy({} as Queries, {
    get: (_, name) => async (...args: unknown[]) => {
      await buildGate();
      return (bound().q as unknown as Record<string | symbol, (...a: unknown[]) => unknown>)[name](...args);
    },
  });

Do the same for the four render helpers, renderSmoodlyPath, smoodlyMetadata, renderSmoodlyPage and smoodlyPageMetadata, the gate first:

smoodly/server.ts
export const renderSmoodlyPath: Renderer["renderSmoodlyPath"] = async (...args) => { await buildGate(); return bound().renderer.renderSmoodlyPath(...args); };

Upgrading to 0.0.46

0.0.46's delivery tables and their rebuild belonged to the Postgres schema, and nothing of them is left to do.

Astro ships: npx create-smoodly-app --framework astro makes a new Astro site. Nothing changes for a Next.js site beyond the steps below. 0.0.46 also changes how a site registers its content model: the config registers schemas, and a new file lists the components. The config then loads without React, so the CLI, a script and an agent can read it.

Components now import from smoodly/react, and schemas from smoodly. The root entry loads no React, so an Astro project installs none; react is an optional peer dependency of the package.

  1. Move each schema into a file beside its component: export const heroSchema = … goes from Hero.tsx to Hero.schema.ts, and Hero.tsx imports it. Do the same for elements and page types. A schema file imports no component.
  2. List schemas where components were listed: smoodly/sections.ts, smoodly/elements.ts and pages in smoodly/config.ts. Entry pages leave the config.
  3. Pass schemas to z.locked(), z.sections(), z.freeform(), smoodly.toolset(), smoodly.global({ section }) and node().
  4. Create smoodly/views.ts with every component, the entry pages included, and move RichText there from the config's custom:
smoodly/views.ts
export const views = () =>
  defineViews(config, {
    sections: [Hero, PageHero, ImageText, Points, FavouriteArticles, People, Quote, Header, Footer],
    elements: [Callout, Cta],
    pages: [HomePage, ArticlesPage, StandardPage, ArticlePage, NewsPage, NewsPostPage],
    RichText,
  });
  1. In smoodly/richtext.tsx, import the element components directly, since smoodly/elements.ts now lists schemas: createRichText({ elements: [Callout, Cta], … }). An element with a view but missing here is named on the first render.
  2. In smoodly/server.ts, build the stores and the site from the config and hand the renderer the views:
smoodly/server.ts
  const { pages, entries, assets, members, published } = createSupabaseStores(db, config);
  // …
  const site = createSmoodlySite(siteOptions(config, () => ({ pages, entries, assets, published })));
  // …
  const renderer = createPageRenderer({ site, ...views(), href });

In the same file, adminDeps() and content() hand the operations the site's projector. A publish then writes the finished document of every page and entry it changes, and a live page reads it in one lookup:

smoodly/server.ts
  const { pages, entries, assets, members, auth, site } = bound();
  // The projector: a publish writes the finished documents a live page reads.
  return { pages, entries, assets, members, auth, href, projector: site.projector };
// …
  const { pages, entries, assets, members, site } = bound();
  return createSmoodlyContent({ config, pages, entries, assets, members, href, projector: site.projector });
  1. In every component file and in smoodly/views.ts, change from "smoodly" to from "smoodly/react". Schema files, the config, smoodly/server.ts and scripts keep "smoodly". A pairing line left on the root fails to compile: smoodly.section is no longer there.

A component left where a schema belongs is named: smoodly: pass the schema, not the component — "hero" is registered by its schema (heroSchema), and its component goes to defineViews. A schema with no component is named on the first render.

Names now need to be unique per kind only: a section and a collection may share one. Sections and elements share a namespace, as do collections and globals.

The admin now ships prebuilt in the package, and one route file serves it:

  1. Create app/(smoodly)/admin/[[...segments]]/route.ts:
app/(smoodly)/admin/[[...segments]]/route.ts
import { createAdminRoute } from "smoodly/next";
import { config } from "@/smoodly/config";
import { adminDeps, presence } from "@/smoodly/server";

export const { GET, POST } = createAdminRoute(() => ({ config, ...adminDeps(), presence }));
  1. Delete app/(smoodly)/admin/[[...segments]]/page.tsx, app/(smoodly)/admin/layout.tsx, smoodly/admin.tsx and smoodly/ops.ts.
  2. Nothing else imports from smoodly/admin/next: that entry is gone. smoodly/admin is unchanged.

Your app no longer compiles the admin, so a build is faster and an admin fix needs only the package update. The admin's font is served by your own site; it no longer asks Google Fonts for it.

Upgrading to 0.0.48

A site in live mode changes nothing. Static mode is new and opt-in for Astro: set output: "static" in astro.config and follow Deploying › Static.

Next, Export and import.

Upgrading to 0.0.50

0.0.50 has no schema change. Live pages on Next.js are now served from Next's route cache: next build still needs no keys, each address renders on its first visit and stays cached until a publish expires it. Three edits in files the installer wrote for you:

  • The two route files become one. Delete app/(site)/page.tsx and app/(site)/[...path]/page.tsx (under app/[locale] on a multilingual site) and create app/(site)/[[...path]]/page.tsx from Next.js. The generateStaticParams export is what turns the cache on.
  • In smoodly/server.ts, replace every await connection() with await buildGate(), imported from smoodly/next, and drop the next/server import. The gate still keeps next build off the database; at run time it no longer forces a render per request.
  • A page, a section or a layout under the CMS route that reads cookies, headers or search params must move to a route file of its own, or it answers a 500 in production.

Do the first two together: with the new route file, a connection() left anywhere in smoodly/server.ts answers 500 on every public page in production, and next dev will not show it.

A renamed page's old address still answers a permanent redirect, now without the request's query string: the cached answer cannot read it.

Upgrading to 0.0.52

There is no upgrade to 0.0.52 from an installed 0.0.51 site: up to 0.0.51 a site ran its own Postgres and Supabase, and nothing imports that database into a space. Make the site again with npx create-smoodly-app@latest into a new folder, on a project made in the dashboard, move your components, sections and config across, and enter or seed the content in the new space. The sections below say what changed in a site's code between the two versions, for that move.

0.0.52 moves a site's content into Smoodly's service, a space per site, and every build pushes the site's content model to its space. The admin's operations move to Smoodly's API, a service of its own, and the admin route on your site keeps the page and its files and gains two routes the API uses: one that expires the tags a publish names, signed with the API's own key, and one that turns on draft mode for the editor's browser. The operations endpoint under /admin/_smoodly/op is gone.

  • Your env names the space by its id, sp_…, and its two keys, sk_… and pk_…, from the project at smoodly.io (Keys). SMOODLY_API_URL, the address of Smoodly's API, is https://api.smoodly.io unless you set it.
  • On Next.js, add "prebuild": "smoodly push" to package.json's scripts: each build gives the space the content model and the site's address (SITE_URL). An Astro build pushes by itself.
  • In smoodly/server.ts, adminDeps() no longer hands over the stores and the sign-in check; it returns the API's address, the space (the API keeps a space's admin routes under it) and the delivery mode. The API signs its calls to your site with its own key, which the admin route fetches from the API and checks:
smoodly/server.ts
export function adminDeps() {
  const env = smoodlyEnv("admin"); // the admin talks to SMOODLY_API_URL, which also tells it where editors sign in
  return { apiUrl: env.apiUrl, spaceId: env.spaceId, delivery: "live" as const };
}

Drop supabaseAdminAuth and AdminAuth from the smoodly/admin import, and the auth the old bound() built (supabaseAdminAuth, AdminAuth, AuthConfig, gateAdminOp, createAdminOps, runAdminOp, ensureFixedNodes, ensureGlobalItems and localContentTransport are gone from it; SignInConfig names what GET /v1/auth answers).

The admin asks the API where editors sign in (GET /v1/auth), so the site no longer holds the Auth project's values: delete publicAuth() from smoodly/server.ts, and signIn: publicAuth() from the route file:

app/(smoodly)/admin/[[...segments]]/route.ts
export const { GET, POST } = createAdminRoute(() => ({ config, ...adminDeps(), presence }));

SMOODLY_PUBLISHABLE_KEY, when set, is now the space's publishable key (pk_…).

Media files move into Smoodly's service as well: a file of up to 100 MB (25 MB unless media.maxSize says more; an image 20 MB at most) uploads from the admin, with its progress shown, or through content().media. An export holding files over 4 MB now imports. withDownload is gone from the smoodly import: an SVG is served as an attachment by the API itself.

Images are served from Smoodly's media host, media.smoodly.io, cut to the framed area at the width the layout needs, in AVIF or WebP, with no image optimizer on your side (Images and crops):

  • Delete SMOODLY_URL from your env files and your host's settings: a site names no media host.
  • On Next.js, delete images: smoodlyImages() and its import from next.config.ts: smoodly/image/config, smoodlyImages, isPrivateHost, nextLoader, imageUrl and ImageLoader are gone. SmoodlyImage no longer uses next/image: drop its loader and unoptimized props.
  • On Astro, the integration no longer sets image.remotePatterns, and <Image> no longer goes through /_image; it takes no unoptimized.
  • f.image({ crops: { desktop: "16:9", mobile: "4:5" } }) names crops for art direction, and the new media prop on Image and SmoodlyImage says where each applies: media={{ mobile: "(max-width: 767px)" }}.
  • An image's quality and its widest width can be set for the site (media: { quality, maxWidth } in defineConfig), a field (f.image({ quality, maxWidth })) or a placement (the quality and maxWidth props); nothing to change if you set none (Quality and width).

Editors sign in at smoodly.io: /admin has no sign-in form of its own. It sends the editor to smoodly.io and back, and holds a session for this site's space alone, which Sign out ends without signing them out of smoodly.io. Nothing to set on your site, and the admin no longer depends on Supabase: drop @supabase/supabase-js from your package.json unless your own code uses it.

Your site's reads move to the API too: the site opens no database.

  • The live site and the admin need SMOODLY_SPACE_ID and SMOODLY_SECRET_KEY.
  • In smoodly/server.ts, bound() builds the reads from the API instead of the stores, and content() posts to the API:
smoodly/server.ts
  const site = createSmoodlyApi({ ...apiEnv(), config });
smoodly/server.ts
  return createSmoodlyContent({ config, href, transport: apiTransport(apiEnv()) });

Drop createSmoodlyClient, createSupabaseStores, createSmoodlySite and siteOptions from the smoodly import, and the client() export with them.

Editing presence moves to the API as well: the admin opens one connection per tab to Smoodly's API, and your Supabase project's Realtime is no longer used. presenceConfig(env) answers at once with the API's address and the space, so presence() in smoodly/server.ts is typed PresenceConfig, not a promise:

smoodly/server.ts
export function presence(): PresenceConfig {

A seed now writes through the API, so the API must answer while it runs. On Astro there is nothing to change: the integration reads over the API by itself.

A publish now answers at once and reaches the site a moment later: the API builds the pages it changed and every page that depends on them, clears its edge copies, then calls your site's revalidate route. The admin shows Publishing… in its rail until that lands. A script that publishes through content() gets the same answer; GET /v1/spaces/{space}/status with the secret key says how many deliveries are still pending.

Upgrading to 0.0.53

Nothing in your code changes: npm install smoodly@0.0.53 (and create-smoodly-app@0.0.53 for new sites) and deploy. 0.0.53 is the clean after the hosted service: every file says today's shape, and a few things a site never reached since 0.0.52 are gone from the package's public surface, since members are managed at smoodly.io: memberErrors, InviteInput and InviteResult from smoodly, MembersListResult.consoleUrl and the invite, setRole and remove members operations from smoodly/admin, and the MemberStore write methods. The admin reads the dashboard's address from the service.

For a new site: the installer's seed succeeds on its first run against a fresh space (its reads are draft reads, never an edge copy), and every template's .gitignore lists .vercel/, so a local build with the Vercel adapter is never committed as prebuilt output. An existing site adds .vercel/ to its .gitignore by hand.

Upgrading to 0.0.54

Nothing in your code changes. The editor gains the structure view (the switch at the top right turns the canvas into a card per section, dragged to reorder), undo and redo (Cmd+Z, Shift+Cmd+Z, the two arrows at the top right) and copying a section to another page (a card's ⋯ menu in the structure view). Update smoodly, build and deploy.

Upgrading to 0.0.55

Nothing in your code changes. In the editor, the structure view shows one Add section per zone, at its end, and the Page Outline's rows carry the same ⋯ menu as the structure cards (Copy, Paste before, Paste after, Remove) in place of the ×. Update smoodly, build and deploy.

Upgrading to 0.0.56

Nothing in your code changes, and one thing in your environment: the package, the installer and every new site now name Node 22.12 or newer (Astro 7's floor). What a site meets after the update:

  • Publish checks references on entries and globals too: an entry or a global cannot go live in a language while one of its reference fields points at an entry that is unpublished there, and a page whose child is still published in that language cannot be unpublished. The message names what to publish or unpublish first.
  • On the live site a list ordered by updatedAt follows the publish time, and an entry's updatedAt is its last publish; in draft mode both follow the last save. Editing an old post no longer moves it to the top of a public list until it is published again.
  • A link field takes only what the site renders (https://, http://, mailto:, tel:, a path, # or ?), marked as the editor types and refused at publish. The custom CSS box refuses image-set(), image() and src() beside url().
  • A new section's required select or radio stores its first option, as the form shows it.
  • On Astro, the editor's preview cookie ends twelve hours after it was set; opening the admin sets a new one.
  • In Astro, an element view inside richtext gets styles as it does in React, and a view's aspect narrower than the image's cut scales sizes by the frame, so the browser picks a candidate for what it shows.
  • The installer takes every prompt's default when it runs without a terminal, expands a leading ~/, takes a folder holding only .git, and makes the initial commit before it pushes the schema and seeds the content.

Update smoodly, build and deploy.

Upgrading to 0.0.59

Nothing in your code changes, and every order stays as it is. locales in the config takes a new optional order: "shared" (the default) keeps one order of pages and of manually ordered entries for every language, "perLocale" gives each language its own; see Locales and routing. A collection takes admin: { showInNav: true } to sit in the admin's main navigation instead of the Collections menu; see Defining a collection. A collection's list in the admin shows 20 entries a page (100 or 500 on the editor's choice) and filters by title, and getEntries / getLiveCollection take offset beside limit; see Queries. In the admin, a page's ⋯ menu has Duplicate…, and fields have a visible edge in the dark theme. An export made before this version does not import into a space on it: export again after upgrading.

Upgrading to 0.0.61

Nothing in your code changes. Two things are new:

  • A site can read a preview space, a copy of production a project adds once it is live (Deploying). Its id and keys carry preview (sp_preview_…), which older versions refuse as not a Smoodly key: update before you point a site at one.
  • The push names the space it reached. The build log's line is now Pushed schema version 4 to the production space sp_… (it was Pushed schema version 4 to sp_…), and the dev server prints the same once. Change any script that reads that line.

Update smoodly, build and deploy.

Upgrading to 0.0.64

Nothing in your code changes. Richtext has tables: add "table" to a toolset's nodes and editors can insert a plain grid with a header row and an optional header column (Richtext › Tables). RichText renders it as <table> with <thead>, <th scope> and <td>; style th, not thead th. A site on an older version shows a table's cells as paragraphs, so update before editors start using tables.

Update smoodly, build and deploy.

Edit this page on GitHubLast updated 13 Nov 2026