@getvitops/emdash 0.3.4 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @getvitops/emdash
 
+## 0.3.5
+
+### Patch Changes
+
+- Updated dependencies
+  - @getvitops/utils@5.0.0
+
 ## 0.3.4
 
 ### Patch Changes

package/README.md

@@ -38,6 +38,56 @@ export default defineConfig({
 
 Tested against `emdash@0.31.x`.
 
+## Rendering mode
+
+An EmDash site **must** run `output: 'server'` with an adapter — the admin at `/_emdash/admin`,
+the media and API routes, preview tokens and scheduled publishing all need a server, and
+`vitopsHosting()` supplies the adapter. That makes prerendering **per-route and opt-in**, the
+opposite of a plain Astro site (which should stay `output: 'static'` and opt _out_ with
+`export const prerender = false` — see [`@getvitops/astro`](../astro/README.md#rendering-mode)).
+
+So on an EmDash site:
+
+- **Put `export const prerender = true` on every page that doesn't need per-request data** — the
+  home page, legal pages, anything whose content is known at build time. A route with no
+  `prerender` export is rendered again for every visitor on every request.
+- **Give dynamic routes a `getStaticPaths()`** so database-backed pages build to static HTML too.
+  Query the collection at build time and return one entry per path:
+
+  ```astro
+  ---
+  // src/pages/[...slug].astro
+  import { getEmDashCollection, getEmDashEntry } from 'emdash';
+  import { PortableText } from 'emdash/ui';
+  import Layout from '../layouts/Layout.astro';
+
+  export const prerender = true;
+
+  export async function getStaticPaths() {
+    const { entries } = await getEmDashCollection('pages', { status: 'published' });
+    return entries.map((entry) => ({ params: { slug: entry.slug } }));
+  }
+
+  const { slug } = Astro.params;
+  const { entry: page } = await getEmDashEntry('pages', slug);
+  ---
+
+  <Layout title={page.data.title}>
+    <PortableText value={page.data.content} />
+  </Layout>
+  ```
+
+The trade-off is deliberate and worth stating: **a prerendered page reflects the database as of the
+last build**, so publishing from the admin only appears after a redeploy. Leave a route
+server-rendered when that is unacceptable — the preview route (draft content is served at request
+time via a signed token), a page that must go live within seconds, or anything personalised. That
+is the narrow case, not the default.
+
+One exception to the exception: if you are building a **distributable EmDash theme** rather than a
+site, EmDash's own guidance is that content pages must stay server-rendered, since a theme's users
+edit content through the admin and expect it live. The rule above is for a site you build and
+deploy yourself.
+
 ## Hosting seam: `vitopsHosting()`
 
 One call resolves the Astro adapter + EmDash database/storage for a hosting

package/dist/index.mjs

@@ -358,7 +358,7 @@ async function vitopsHosting(options = {}) {
 
 //#endregion
 //#region package.json
-var version = "0.3.4";
+var version = "0.3.5";
 
 //#endregion
 //#region src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/emdash",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "EmDash CMS native plugin for the Vitops design system — Portable Text block types editors can insert from the admin, rendered with the design-system web components and CSS framework.",
   "license": "MIT",
   "files": [
@@ -22,7 +22,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@getvitops/utils": "4.1.0"
+    "@getvitops/utils": "5.0.0"
   },
   "devDependencies": {
     "@astrojs/cloudflare": "^14.0.0",
@@ -30,7 +30,7 @@
     "astro": "^7.1.2",
     "emdash": "^0.31.0",
     "vitest": "^4.1.9",
-    "@getvitops/astro": "4.1.0"
+    "@getvitops/astro": "5.0.0"
   },
   "peerDependencies": {
     "@astrojs/cloudflare": ">=14",