Deploying
Put your Smoodly site on the internet: give it the production space's values and let its build push the schema; then, once it is live, add a preview space to develop against.
What a deploy needs
A Smoodly site on Astro is a server-rendered Astro site. The starter's @astrojs/node adapter deploys to any host that runs astro build and starts dist/server/entry.mjs. Pages are cached in that process's memory and expire when an editor publishes.
On Vercel, swap the adapter for Vercel's, and the cache for its CDN:
import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel";
import { cacheVercel } from "@astrojs/vercel/cache";
import smoodly from "smoodly/astro";
export default defineConfig({
output: "server",
adapter: vercel(),
// Pages are cached on Vercel's CDN and expired by tag when an editor publishes.
cache: { provider: cacheVercel() },
site: process.env.SITE_URL,
integrations: [smoodly({ config: "src/smoodly/config.ts" })],
});Install it with npm install @astrojs/vercel. The steps below name Vercel's settings; other hosts have the same ones under other names.
Run the function near your visitors. A page that is not in the CDN yet makes one call to Smoodly's API, answered from the edge when cached and otherwise by your space, which lives near where you made the project: Stockholm for a project made from Europe. On Vercel, vercel.json sets the function's region with { "regions": ["arn1"] } (Stockholm; the region list names the rest). Vercel's Speed Insights (@vercel/speed-insights, mounted as its Astro or Next component in your layout) records real visitors' Web Vitals; it is your site's script, not Smoodly's, and optional.
Static
Set Astro's output to static and every published page is built as a file: visitors need no function, and the site stays up if Smoodly's API is down.
import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel";
import smoodly from "smoodly/astro";
export default defineConfig({
output: "static",
adapter: vercel(),
site: process.env.SITE_URL,
integrations: [smoodly({ config: "src/smoodly/config.ts" })],
});Publishing does not change the live site. Editors press Deploy in the admin's top bar, next to their avatar, when they are done, and the host builds. Give the site the host's deploy hook as SMOODLY_DEPLOY_HOOK where astro build runs (on Vercel: Settings › Git › Deploy Hooks): the build hands it to Smoodly's API with the site's address; without it the tile shows what is waiting and Deploy stays disabled. SITE_URL must be the site's own address, and the build refuses static output without it: the tile reads the build's marker, /_smoodly/build.json, from there. It says Building… until the new build answers, N changes while publishes wait (an unpublish or a delete counts as one too), and The build has not landed after ten minutes with no new build, in which case look at the host's log. A host that strips query strings from a cached file can hold the old marker for its max-age.
The admin, its revalidate and preview routes and the preview address still run on demand, so the deployment is files plus one function; a host with no function at all cannot run the admin. A static page has no lists by query string and no draft at its real address: drafts are edited through the preview address, as in live mode. A moved page's old address becomes one of the host's redirects at build, so it is answered without a function too. The cache provider in astro.config is unused in static output and may stay.
A Smoodly site on Next.js deploys like any other Next.js app: to Vercel, or to any host that runs next build and next start. Pages are served from the host's cache (on Vercel, the CDN: x-vercel-cache: HIT) and expire when an editor publishes; the function runs for the first visit of an address and for the editor's preview. The steps below name Vercel's settings; other hosts have the same ones under other names.
Environment variables
Set these in your host's project settings. Production gets the production space's values. Your host's Preview environment gets the preview space's once the project has one (A preview space), and the production space's until then. A missing or wrong key answers every page with a 500 and names the variable in the server log, your host's function logs:
SMOODLY_SPACE_IDThe space your content lives in, `sp_…`. A key from another space is refused by name.SMOODLY_SECRET_KEYThe space's secret key (`sk_…`). Server-only: never expose it to the browser. A wrong key fails every page with one of these: the publishable key `holds the publishable key`; a string that is no Smoodly key `is not a Smoodly secret key`; a key the space does not hold `is not one of the space's live keys`. Every read sends the key again, so a corrected key works on the next request.SMOODLY_PUBLISHABLE_KEYThe space's publishable key (`pk_…`): it reads published content only, so a browser may hold it.SITE_URLThe site's own address with its scheme, like `https://www.example.com`. The build pushes it to the space: the admin's operations are accepted from it, and a publish calls it back. Your root layout builds `metadataBase` from it, so the canonical link, hreflang links (on a multilingual site) and social image URLs are absolute. Unset, it falls back to `http://localhost:3000` and the server warns once per process (a build prints it from each of its workers); a value without `http://` or `https://` stops every page with an error that names it. It is read when the server starts, so restart or redeploy after changing it.SMOODLY_PREVIEW_SECRETNext.js only; an Astro site has no such route and ignores the variable, since its drafts live at the preview address inside the admin. Optional. Lets a link turn draft mode on outside the admin: `/api/preview?secret=…&path=/` sets the draft cookie and redirects to `path`; a wrong or missing secret gets a 401. `/api/preview?disable` turns it off and needs no secret. Leave the variable unset and only the admin can turn draft mode on.On Astro the same variables are read at build and at run time. SITE_URL becomes site, fixed into the build, so set it where astro build runs (in the host's settings, or in .env for a build on your machine); without it, the absolute links in the page head are built from each request's own address, and the build warns.
Keys says what each key can reach, and how to rotate one.
Seeing what a page costs
Set SMOODLY_DEBUG_READS=1 on the server and every page answers with two headers: x-smoodly-reads, the number of calls to Smoodly's API the response made (a page is one: the lookup brings the layout globals along, so the layout's reads cost nothing; a list on the page is one more, and so is a global without layout: true that a view reads), and Server-Timing, each call by its key with when it started and how long it took, then the render. curl -sD - -o /dev/null https://your-site/?v=1 shows them on a cache miss. Leave the variable unset for visitors.
The push at build
Your content model lives in your code, and each build pushes it to the space with the site's address. A Next site's prebuild script runs smoodly push; an Astro build does it itself. The build log shows Pushed schema version 1 to the production space sp_…, or Schema unchanged (version 1) in the production space sp_… when nothing changed (the preview space sp_preview_… for a preview space), so the log says which space the build reached. The dev server says the same line once when it starts. A push that fails is logged and never fails the build. There is no migration to run and no document to rebuild: a package upgrade or a content-model change reaches the space with the next deploy.
In live mode every page renders on request, so the framework's build reads no content: a build without the keys still succeeds and only skips the push. A static Astro build reads every published page, so it needs the keys.
If your site takes the package from a packed tarball in the repository rather than from npm, replacing the file is not enough: a host that restores node_modules from its build cache (Vercel does) sees the same path and version and keeps the old package. Deploy once without the cache (vercel --prod --force), or give the tarball a new name.
The starter's content
The installer already filled the space with the starter's content. On a new site that is the production space, so the content you build on is where the live site reads it and a first deploy has nothing to copy. If the installer's seed failed, or you chose to run it later, run it yourself; it fills the space your env file names:
npm run seedA space without a schema refuses the seed with no_schema: start the dev server or build first, which pushes the schema.
A preview space
A preview space is a full copy of production to develop against: its pages, entries, history, redirects and media. A project has none until you add one, and many sites never need one before they go live.
Add it once the site is live. A dev server and every build push the site's schema to the space they read. Before launch that is what you want. After it, a schema change you try on your machine, or in a preview deployment, would change what the live site serves if they still read production.
- Open the project at smoodly.io, go to Spaces & keys and choose Add a preview space. Its two keys are shown once; its id stays on the page.
- Put the three values in your env file, and in your host's Preview environment.
- Wait for the copy; the page shows its progress. While it runs the preview space refuses edits, uploads and schema pushes, its admin says a copy is in progress, and a site reading it may show missing pages.
- When the copy is ready, restart the dev server and redeploy the preview environment. Their push was refused if they started during the copy, and a site signs in to its admin only from an address its push gave the space.
If a copy fails, the page says why, and the preview space stays locked: its admin and a push say the copy failed. Choose Try again there to continue where it stopped, or Refresh from production to start over.
A preview space's values say what they are: its id is sp_preview_… and both keys carry it. The build log names the space a push reached, so you can see which one a build used.
Refresh from production, on the same page, replaces everything in the preview space with a new copy: preview's own content changes are lost, and its keys and its schema stay the same. After a refresh, restart or redeploy the site that reads preview: it may hold pages it cached before. Nothing travels the other way. Content is edited in production; preview is where code and schema changes are tried against a copy of it.
Sign-in on the real address
Editors sign in at /admin on the deployed site as they do locally: the admin sends them to smoodly.io and back. The deploy's push gives the space the site's address, and smoodly.io sends an editor back only to an admin address the space recorded that way (a preview deploy's and localhost included), so there is nothing to set.
Preview and drafts
Editors see drafts at the preview address, /_smoodly/preview/<path>, inside the admin only: a signed cookie opens it, and nothing there is cached. A live address never shows a draft, and there is no pill.
The editor turns on draft mode (Next's way of rendering unpublished content for one browser). While it is on, a small pill at the bottom of each page says Preview · unpublished changes. Exit preview turns draft mode off through /api/preview, which every starter includes. Visitors never get the pill or any of its code.