smoodly 0.0.59 → 0.0.61

package/docs/reference/upgrading.md

@@ -0,0 +1,312 @@
+# 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.
+
+## 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](../frameworks/nextjs.md#content-in-the-browser) 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](../getting-started/content-from-code.md) |
+| `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`:
+
+File: `smoodly/server.ts`
+
+```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.)
+
+File: `smoodly/server.ts`
+
+```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:
+
+File: `smoodly/server.ts`
+
+```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`:
+
+File: `smoodly/views.ts`
+
+```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,
+  });
+```
+
+5. 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.
+6. In `smoodly/server.ts`, build the stores and the site from the config and hand the renderer the views:
+
+File: `smoodly/server.ts`
+
+```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:
+
+File: `smoodly/server.ts`
+
+```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 });
+```
+
+7. 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`:
+
+File: `app/(smoodly)/admin/[[...segments]]/route.ts`
+
+```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 }));
+```
+
+2. Delete `app/(smoodly)/admin/[[...segments]]/page.tsx`, `app/(smoodly)/admin/layout.tsx`, `smoodly/admin.tsx` and `smoodly/ops.ts`.
+3. 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](../getting-started/deploying.md#static).
+
+Next, [Export and import](../getting-started/export-and-import.md).
+
+## 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](../frameworks/nextjs.md#the-route-file). 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](https://app.smoodly.io), 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](../getting-started/keys.md)). `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:
+
+File: `smoodly/server.ts`
+
+```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:
+
+File: `app/(smoodly)/admin/[[...segments]]/route.ts`
+
+```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](../media/images-and-crops.md)):
+
+- 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](../media/images-and-crops.md#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:
+
+File: `smoodly/server.ts`
+
+```ts
+  const site = createSmoodlyApi({ ...apiEnv(), config });
+```
+
+File: `smoodly/server.ts`
+
+```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:
+
+File: `smoodly/server.ts`
+
+```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](../languages/locales.md#one-order-or-one-per-language). A collection takes `admin: { showInNav: true }` to sit in the admin's main navigation instead of the *Collections* menu; see [Defining a collection](../collections/defining.md#entries-in-the-admin). 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](../collections/queries.md#paging-a-list). 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](../getting-started/deploying.md#a-preview-space)). 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoodly",
-  "version": "0.0.59",
+  "version": "0.0.61",
   "description": "Open-source, code-first CMS for Astro and Next.js: define a component once, it becomes a typed, editable building block.",
   "license": "MIT",
   "engines": {
@@ -62,11 +62,12 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "docs"
   ],
   "scripts": {
     "build:admin": "tsx scripts/build-admin.ts",
-    "build": "node scripts/write-version.mjs && rm -rf dist && tsc -p tsconfig.build.json && node scripts/copy-astro.mjs && npm run build:admin",
+    "build": "node scripts/write-version.mjs && rm -rf dist && tsc -p tsconfig.build.json && node scripts/copy-astro.mjs && npm run build:admin && node scripts/build-docs.mjs",
     "prepublishOnly": "npm run build",
     "pretest": "node scripts/write-version.mjs && npm run -s build:admin",
     "test": "vitest run",