@botlr/next 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @botlr/next
 
+## 0.3.0
+
+### Minor Changes
+
+- e3ff8e7: `createLocalePage` now throws when a page cannot be resolved, so `next build` fails instead of saving an error page. In development the error box is still rendered. The new `resolveErrors` option (`"throw"` or `"render"`) overrides the default; `ResolvedPage`'s error result carries the original error as `cause`.
+
+### Patch Changes
+
+- e3ff8e7: Retry failed reads. GET requests that fail with a network error or a 408, 429 or 5xx status are retried twice with exponential backoff and `Retry-After` support before `BotlrError` is thrown. Configure or disable with the new `retry` client option, also accepted by `getBotlrForRoute` and `createBotlrFromEnv`. Writes are never retried.
+- Updated dependencies [e3ff8e7]
+  - @botlr/sdk@0.3.0
+  - @botlr/react@0.1.2
+
+## 0.2.0
+
+### Minor Changes
+
+- Page helpers extracted from the satellite apps.
+
+  `@botlr/sdk`: `PageResponse` gains optional `full_slug`, `breadcrumbs` and `alternate_translations` (new `AlternateTranslation` type, also used by `ResolveResponse`). New asset helpers `getAssetUrl`, `createAssetUrl`, `getAssetId`, `getAssetFilename` and `isAssetData` take the media server URL explicitly instead of reading `NEXT_PUBLIC_MEDIA_URL`.
+
+  `@botlr/next`: `resolvePage` and `createPageResolver`, `buildPageMetadata`, `renderCmsPage` with `themeSettingsToCss`, `serveStaticTextFile` and `defaultRobotsContent`, `createLocalePage` and `createLocaleAliasPage`, `rateLimit` and `getClientIp`, plus `scopeFromEnv` and `environmentFromEnv`. Every helper takes its client and component registry as arguments. `html-react-parser` is a new dependency.
+
+### Patch Changes
+
+- Updated dependencies
+  - @botlr/sdk@0.2.0
+  - @botlr/react@0.1.1
+
 ## 0.1.0
 
 - First release. `getBotlrForRoute` moves here from the publisher's

package/README.md

@@ -1,22 +1,12 @@
 # @botlr/next
 
-Thin Next.js helpers on top of `@botlr/sdk` and `@botlr/react`. Everything
-from both packages is re-exported, so a Next.js app can import from
-`@botlr/next` alone.
+Next.js helpers on top of `@botlr/sdk` and `@botlr/react`. Everything from
+both packages is re-exported, so a server file can import from `@botlr/next`
+alone. The package imports `next/headers` and `next/navigation`, so client
+components should import runtime values from `@botlr/sdk` or `@botlr/react`
+instead; type imports from `@botlr/next` are fine anywhere.
 
-```ts
-// app/[[...slug]]/page.tsx
-import { getBotlrForRoute, SectionRenderer } from "@botlr/next";
-
-export default async function Page({ params, searchParams }) {
-  const botlr = await getBotlrForRoute({
-    appId: process.env.BOTLR_APP_ID!,
-    preview: (await searchParams).preview === "true",
-  });
-  const resolved = await botlr.resolveUrl((await params).slug?.join("/") ?? "");
-  // ...render resolved.data.layout with SectionRenderer
-}
-```
+## Clients
 
 - `getBotlrForRoute(params)` builds a client for the current request. The
   locale comes from `Accept-Language` unless given; `baseUrl`, `apiKey` and
@@ -25,8 +15,76 @@ export default async function Page({ params, searchParams }) {
   browser through a `NEXT_PUBLIC_` name.
 - `getCachedBotlr` is the same, memoised per request with React `cache`.
 - `createBotlrFromEnv(overrides)` needs no request context (scripts,
-  `generateStaticParams`).
-- `localeFromAcceptLanguage(header, fallback)` and `configFromEnv(overrides)`
-  are the building blocks.
+  `generateStaticParams`, the page helpers below).
+- `configFromEnv`, `scopeFromEnv({ locale })` (from `BOTLR_ORG_SLUG`,
+  `BOTLR_PROJECT_SLUG`, `BOTLR_APP_INSTANCE_SLUG`, `BOTLR_APP_ID`),
+  `environmentFromEnv()` (`BOTLR_ENVIRONMENT`, `ENVIRONMENT`, `NODE_ENV`) and
+  `localeFromAcceptLanguage` are the building blocks.
+
+## A static locale route in one call
+
+```ts
+// lib/botlr.ts
+import { createBotlrFromEnv } from "@botlr/next";
+export const botlr = createBotlrFromEnv();
+
+// app/(root)/[[...slug]]/page.tsx
+import { createLocalePage } from "@botlr/next";
+import { botlr } from "@/lib/botlr";
+import { publisherSectionRegistry } from "@/components/sections/publisher-section-registry";
+
+// Segment config must stay as literals here so Next can read it statically.
+export const revalidate = false;
+export const dynamicParams = false;
+
+const page = createLocalePage({
+  locale: "da",
+  folder: "",
+  client: botlr,
+  componentRegistry: publisherSectionRegistry,
+  siteUrl: process.env.NEXT_PUBLIC_APP_URL,
+});
+
+export const generateStaticParams = page.generateStaticParams;
+export const generateMetadata = page.generateMetadata;
+export default page.Page;
+```
+
+`createLocalePage` lists slugs with `getPageSlugList`, resolves each request
+once for metadata and page through `createPageResolver`, calls `notFound()`
+for missing and unpublished pages, follows CMS redirects with
+`permanentRedirect` (or `redirect` with `redirect: "temporary"`) prefixed by
+`folder`, and renders with `renderCmsPage`. `createLocaleAliasPage("/sv")`
+makes a folder that only redirects to another one.
+
+When resolving a page throws, even after the client's retries, the page
+throws too: `next build` fails instead of saving an error page, and Vercel
+keeps the previous deploy live. In development an error box is rendered in
+its place. Pass `resolveErrors: "render"` to always show the box (with
+`renderError` to customise it) or `resolveErrors: "throw"` to always throw.
+
+## The pieces
+
+- `resolvePage(client, slug, locale, options)` folds `/api/resolve` into
+  `{ kind: "page" | "redirect" | "404" | "error" }` and prepends non-page
+  content (articles by default; see `contentSections`) to the `main` region as
+  an inline section. `createPageResolver(client, options)` binds the client
+  and memoises per request.
+- `buildPageMetadata(pageData, { siteUrl, folder })` turns `seo_meta` into
+  Next `Metadata`: title, description, keywords, Open Graph, Twitter, robots,
+  canonical and hreflang alternates. Without `siteUrl` only an explicit
+  `seo_meta.canonical` is emitted.
+- `renderCmsPage({ pageData, scope, componentRegistry, client })` picks the
+  page template, then the theme's, then a built-in one; merges template and
+  page layouts; applies visibility rules for `environment`; fetches shared
+  sections through `client` or `fetchSharedSection`; and mounts a
+  `SectionRenderer` at every `{{{REGION}}}` marker. `themeSettingsToCss`
+  emits the theme's custom properties.
+- `serveStaticTextFile(client, slug, defaultContent)` serves a CMS page's
+  text sections as `text/plain`, for `robots.txt`, `humans.txt` and
+  `llms.txt` routes. `defaultRobotsContent()` allows everything in production
+  and disallows elsewhere.
+- `rateLimit(key, { limit, window })` and `getClientIp(request)` for form and
+  forum route handlers. In-memory, per server instance.
 
-`next` and `react` are peer dependencies.
+`next` and `react` are peer dependencies; `html-react-parser` is a dependency.