@notionx/create-notionx-app 1.0.0 → 2.0.0

package/dist/templates/lib/pages/source.ts.tmpl

@@ -1,14 +1,19 @@
 import {
-  getGenericNotionContentBySlug,
   type GenericContentDetail,
   type NotionBlock,
 } from "@notionx/core/notion";
+import {
+  getGenericNotionContentBySlugForLocale,
+  getGenericNotionContentByIdForLocale,
+} from "@notionx/core";
 import {
   createSitePagesApi,
   type SitePage as BaseSitePage,
   type SitePageBlockRef,
 } from "@notionx/core/pages";
 import { blocksSource, contentSources } from "@/lib/content/models";
+import { getRequestLocale } from "@/lib/site/request-env";
+import { i18n } from "@/lib/i18n";
 import { pageFields, pagesDataSourceEnv } from "./model";
 
 const pagesModel = {
@@ -35,167 +40,102 @@ const fallbackBlocks = (text: string): NotionBlock[] => [
   },
 ];
 
-type BlockPropertyValue = string | string[] | number | boolean;
-
-type BlockCta = {
-  label: string;
-  href: string;
-};
-
-type FeatureGridItem = {
-  title: string;
-  description: string;
-  icon: string;
-  href?: string;
-};
-
-export type StructuredHeroBlock = {
-  type: "hero";
-  slug: string;
-  title: string;
-  description: string;
-  eyebrow: string;
-  headline: string;
-  subheadline: string;
-  primaryCta: BlockCta | null;
-  secondaryCta: BlockCta | null;
-  alignment: "left" | "center";
-  theme: "default" | "muted" | "inverse";
-  coverImage: string | null;
-  editUrl: string | null;
-};
-
-export type StructuredFeatureGridBlock = {
-  type: "feature-grid";
-  slug: string;
-  title: string;
-  description: string;
-  headline: string;
-  body: string;
-  columns: 2 | 3 | 4;
-  items: FeatureGridItem[];
-  coverImage: string | null;
-  editUrl: string | null;
-};
-
-export type StructuredStoryBlock = {
-  type: "story";
-  slug: string;
-  title: string;
-  description: string;
-  headline: string;
-  body: string;
-  quote: string;
-  quoteAttribution: string;
-  mediaUrl: string | null;
-  layout: "text-left" | "media-left" | "media-right";
-  coverImage: string | null;
-  editUrl: string | null;
-};
-
-export type StructuredLatestPostsBlock = {
-  type: "latest-posts";
-  slug: string;
-  title: string;
-  description: string;
-  headline: string;
-  body: string;
-  count: number;
-  primaryCta: BlockCta | null;
-  coverImage: string | null;
-  editUrl: string | null;
-};
-
-export type LegacyStructuredPageBlock = {
-  type: "legacy";
+export type StructuredPageBlock = {
   slug: string;
-  title: string;
-  description: string;
   variant: string;
+  order: number;
   coverImage: string | null;
   editUrl: string | null;
   blocks: NotionBlock[];
 };
 
-export type StructuredPageBlock =
-  | StructuredHeroBlock
-  | StructuredFeatureGridBlock
-  | StructuredStoryBlock
-  | StructuredLatestPostsBlock
-  | LegacyStructuredPageBlock;
-
 export type SitePage = Omit<BaseSitePage, "structuredBlocks"> & {
   structuredBlocks: StructuredPageBlock[];
 };
 
-const fallbackStructuredBlocks: Record<
-  string,
-  Exclude<StructuredPageBlock, LegacyStructuredPageBlock>
-> = {
+const fallbackStructuredBlocks: Record<string, StructuredPageBlock> = {
   "home-hero": {
-    type: "hero",
     slug: "home-hero",
-    title: "Homepage Hero",
-    description:
-      "Editable hero module seeded into the reusable blocks source for the homepage.",
-    eyebrow: "Notion + Cloudflare",
-    headline: "Start with a homepage you can keep editing",
-    subheadline:
-      "Keep the layout stable in code while the hero copy, positioning, and primary call to action evolve in Notion.",
-    primaryCta: { label: "Explore the blog", href: "{{contentSourceListPath}}" },
-    secondaryCta: { label: "Read the story", href: "/about" },
-    alignment: "center",
-    theme: "muted",
+    variant: "hero",
+    order: 10,
     coverImage: null,
     editUrl: null,
-  },
-  "home-feature-grid": {
-    type: "feature-grid",
-    slug: "home-feature-grid",
-    title: "Homepage Feature Grid",
-    description:
-      "Reusable mid-page section for capabilities, benefits, or service pillars.",
-    headline: "Show the system working together",
-    body:
-      "Use this grid to explain how editing, infrastructure, and publishing fit together without overwhelming the homepage.",
-    columns: 3,
-    items: [
+    blocks: [
       {
-        title: "Editorial workflows",
-        description:
-          "Use Notion as the editor for pages, posts, and reusable sections.",
-        icon: "pen-square",
-        href: "/about",
-      },
-      {
-        title: "Cloudflare runtime",
-        description:
-          "Ship on Workers with storage and caching primitives ready to grow.",
-        icon: "cloud",
+        id: "fallback-hero-heading",
+        type: "heading_1",
+        heading_1: {
+          rich_text: [
+            {
+              type: "text",
+              text: { content: "Start with a homepage you can keep editing" },
+              plain_text: "Start with a homepage you can keep editing",
+            },
+          ],
+        },
       },
       {
-        title: "{{contentSourceListTitle}} updates",
-        description:
-          "Publish new entries and surface them through the generated routes automatically.",
-        icon: "newspaper",
-        href: "{{contentSourceListPath}}",
+        id: "fallback-hero-sub",
+        type: "paragraph",
+        paragraph: {
+          rich_text: [
+            {
+              type: "text",
+              text: {
+                content:
+                  "Keep the layout stable in code while the hero copy, positioning, and primary call to action evolve in Notion.",
+              },
+              plain_text:
+                "Keep the layout stable in code while the hero copy, positioning, and primary call to action evolve in Notion.",
+            },
+          ],
+        },
       },
     ],
+  },
+  "home-feature-grid": {
+    slug: "home-feature-grid",
+    variant: "feature-grid",
+    order: 20,
     coverImage: null,
     editUrl: null,
+    blocks: [
+      {
+        id: "fallback-feature-heading",
+        type: "heading_2",
+        heading_2: {
+          rich_text: [
+            {
+              type: "text",
+              text: { content: "Show the system working together" },
+              plain_text: "Show the system working together",
+            },
+          ],
+        },
+      },
+    ],
   },
   "home-latest-posts": {
-    type: "latest-posts",
     slug: "home-latest-posts",
-    title: "Homepage Latest Posts",
-    description: "Reusable homepage section for surfacing the latest published posts.",
-    headline: "Read the latest from the blog",
-    body:
-      "Use this section to prove the content model is working with a grid of recent published posts right on the homepage.",
-    count: 6,
-    primaryCta: { label: "View all posts", href: "{{contentSourceListPath}}" },
+    variant: "latest-posts",
+    order: 30,
     coverImage: null,
     editUrl: null,
+    blocks: [
+      {
+        id: "fallback-latest-heading",
+        type: "heading_2",
+        heading_2: {
+          rich_text: [
+            {
+              type: "text",
+              text: { content: "Read the latest from the blog" },
+              plain_text: "Read the latest from the blog",
+            },
+          ],
+        },
+      },
+    ],
   },
 };
 
@@ -226,9 +166,9 @@ const fallbackPages: BaseSitePage[] = [
     coverImage: null,
     editUrl: null,
     structuredBlocks: [
-      { slug: "home-hero", variant: "hero", order: 10 },
-      { slug: "home-feature-grid", variant: "feature-grid", order: 20 },
-      { slug: "home-latest-posts", order: 30 },
+      { slug: "home-hero" },
+      { slug: "home-feature-grid" },
+      { slug: "home-latest-posts" },
     ],
     blocks: fallbackBlocks("Configure Notion Pages to edit this homepage from Notion."),
   },
@@ -320,241 +260,103 @@ const pagesApi = createSitePagesApi({
 });
 
 function fallbackPageBlock(ref: SitePageBlockRef): StructuredPageBlock | null {
+  if (!ref.slug) return null;
   const fallback = fallbackStructuredBlocks[ref.slug];
   if (!fallback) return null;
   return fallback;
 }
 
-function fallbackToLegacyNotionBlocks(
+function mapGenericBlockToStructuredBlock(
   detail: GenericContentDetail,
-  ref: SitePageBlockRef
-): LegacyStructuredPageBlock | null {
-  if (!detail.blocks.length) return null;
+  ref: SitePageBlockRef,
+  index: number
+): StructuredPageBlock {
+  const typeValue = detail.properties.type;
+  const variant =
+    (typeof typeValue === "string" ? typeValue.trim() : "") ||
+    ref.variant ||
+    "legacy";
+  const orderValue = detail.properties.order;
+  const order =
+    typeof orderValue === "number" && Number.isFinite(orderValue)
+      ? orderValue
+      : index;
   return {
-    type: "legacy",
     slug: detail.slug,
-    title: detail.title,
-    description: detail.description,
-    variant: ref.variant ?? "story",
+    variant,
+    order,
     coverImage: detail.coverImage,
     editUrl: detail.editUrl,
     blocks: detail.blocks,
   };
 }
 
-function readString(value: BlockPropertyValue | undefined) {
-  if (Array.isArray(value)) return String(value[0] ?? "").trim();
-  if (typeof value === "string") return value.trim();
-  return "";
-}
-
-function readNumber(value: BlockPropertyValue | undefined) {
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
-function normalizeAlignment(value: string): StructuredHeroBlock["alignment"] {
-  return value === "left" ? "left" : "center";
-}
-
-function normalizeTheme(value: string): StructuredHeroBlock["theme"] {
-  if (value === "default" || value === "inverse") return value;
-  return "muted";
-}
-
-function normalizeColumns(value: number | null): StructuredFeatureGridBlock["columns"] {
-  if (value === 2 || value === 4) return value;
-  return 3;
-}
-
-function normalizeLayout(value: string): StructuredStoryBlock["layout"] {
-  if (value === "text-left" || value === "media-left") return value;
-  return "media-right";
-}
-
-function normalizeCount(value: number | null) {
-  if (typeof value === "number" && value > 0) return Math.min(Math.floor(value), 12);
-  return 6;
-}
-
-function readCta(
-  labelValue: BlockPropertyValue | undefined,
-  hrefValue: BlockPropertyValue | undefined
-): BlockCta | null {
-  const label = readString(labelValue);
-  const href = readString(hrefValue);
-  return label && href ? { label, href } : null;
-}
-
-function parseFeatureGridItems(
-  value: BlockPropertyValue | undefined
-): FeatureGridItem[] {
-  const raw = readString(value);
-  if (!raw) return [];
-
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    if (!Array.isArray(parsed)) return [];
-    return parsed
-      .map((item): FeatureGridItem | null => {
-        if (!item || typeof item !== "object") return null;
-        const typed = item as {
-          title?: unknown;
-          description?: unknown;
-          icon?: unknown;
-          href?: unknown;
-        };
-        const title = typeof typed.title === "string" ? typed.title.trim() : "";
-        const description =
-          typeof typed.description === "string" ? typed.description.trim() : "";
-        if (!title || !description) return null;
-        return {
-          title,
-          description,
-          icon: typeof typed.icon === "string" ? typed.icon.trim() : "sparkles",
-          href: typeof typed.href === "string" ? typed.href.trim() : undefined,
-        };
-      })
-      .filter((item): item is FeatureGridItem => Boolean(item));
-  } catch {
-    return [];
-  }
-}
-
-function resolveBlockType(detail: GenericContentDetail, ref: SitePageBlockRef) {
-  const fromRecord = readString(detail.properties.type);
-  return fromRecord || ref.variant || "";
-}
-
 async function resolveStructuredBlock(
-  ref: SitePageBlockRef
+  ref: SitePageBlockRef,
+  locale: string,
+  index: number
 ): Promise<StructuredPageBlock | null> {
-  const detail = await getGenericNotionContentBySlug(blocksSource, ref.slug);
-  if (!detail) return fallbackPageBlock(ref);
-
-  return mapGenericBlockToStructuredBlock(detail, ref);
-}
-
-function mapGenericBlockToStructuredBlock(
-  detail: GenericContentDetail,
-  ref: SitePageBlockRef
-): StructuredPageBlock | null {
-  const type = resolveBlockType(detail, ref);
-
-  if (type === "hero") {
-    const headline = readString(detail.properties.headline);
-    if (!headline) return fallbackToLegacyNotionBlocks(detail, ref);
-    return {
-      type: "hero",
-      slug: detail.slug,
-      title: detail.title,
-      description: detail.description,
-      eyebrow: readString(detail.properties.eyebrow),
-      headline,
-      subheadline: readString(detail.properties.subheadline),
-      primaryCta: readCta(
-        detail.properties.primaryCtaLabel,
-        detail.properties.primaryCtaHref
-      ),
-      secondaryCta: readCta(
-        detail.properties.secondaryCtaLabel,
-        detail.properties.secondaryCtaHref
-      ),
-      alignment: normalizeAlignment(readString(detail.properties.alignment)),
-      theme: normalizeTheme(readString(detail.properties.theme)),
-      coverImage: detail.coverImage,
-      editUrl: detail.editUrl,
-    };
-  }
-
-  if (type === "feature-grid") {
-    const headline = readString(detail.properties.headline);
-    const items = parseFeatureGridItems(detail.properties.items);
-    if (!headline || !items.length) return fallbackToLegacyNotionBlocks(detail, ref);
-    return {
-      type: "feature-grid",
-      slug: detail.slug,
-      title: detail.title,
-      description: detail.description,
-      headline,
-      body: readString(detail.properties.body),
-      columns: normalizeColumns(readNumber(detail.properties.columns)),
-      items,
-      coverImage: detail.coverImage,
-      editUrl: detail.editUrl,
-    };
-  }
-
-  if (type === "story") {
-    const headline = readString(detail.properties.headline);
-    const body = readString(detail.properties.body);
-    if (!headline || !body) return fallbackToLegacyNotionBlocks(detail, ref);
-    return {
-      type: "story",
-      slug: detail.slug,
-      title: detail.title,
-      description: detail.description,
-      headline,
-      body,
-      quote: readString(detail.properties.quote),
-      quoteAttribution: readString(detail.properties.quoteAttribution),
-      mediaUrl: readString(detail.properties.mediaUrl) || null,
-      layout: normalizeLayout(readString(detail.properties.layout)),
-      coverImage: detail.coverImage,
-      editUrl: detail.editUrl,
-    };
+  // Try by pageId first (from Notion relation — preferred path).
+  if (ref.pageId) {
+    const detail = await getGenericNotionContentByIdForLocale(
+      blocksSource,
+      ref.pageId,
+      locale
+    );
+    if (detail) return mapGenericBlockToStructuredBlock(detail, ref, index);
   }
 
-  if (type === "latest-posts") {
-    const headline = readString(detail.properties.headline);
-    if (!headline) return fallbackToLegacyNotionBlocks(detail, ref);
-    return {
-      type: "latest-posts",
-      slug: detail.slug,
-      title: detail.title,
-      description: detail.description,
-      headline,
-      body: readString(detail.properties.body),
-      count: normalizeCount(readNumber(detail.properties.count)),
-      primaryCta: readCta(
-        detail.properties.primaryCtaLabel,
-        detail.properties.primaryCtaHref
-      ),
-      coverImage: detail.coverImage,
-      editUrl: detail.editUrl,
-    };
+  // Try by slug (fallback or legacy rich_text JSON).
+  if (ref.slug) {
+    const detail = await getGenericNotionContentBySlugForLocale(
+      blocksSource,
+      ref.slug,
+      locale
+    );
+    if (detail) return mapGenericBlockToStructuredBlock(detail, ref, index);
+    return fallbackPageBlock(ref);
   }
 
-  return fallbackToLegacyNotionBlocks(detail, ref);
+  return null;
 }
 
-export async function getPageBlocks(page: BaseSitePage | null) {
+export async function getPageBlocks(page: BaseSitePage | null, locale?: string) {
   if (!page) return [];
+  const resolvedLocale = locale ?? getRequestLocale(i18n.defaultLocale);
   const resolved = await Promise.all(
-    (page.structuredBlocks ?? []).map((ref) => resolveStructuredBlock(ref))
+    (page.structuredBlocks ?? []).map((ref, index) =>
+      resolveStructuredBlock(ref, resolvedLocale, index)
+    )
   );
   return resolved.filter((block): block is StructuredPageBlock => Boolean(block));
 }
 
-async function withStructuredBlocks(page: BaseSitePage | null): Promise<SitePage | null> {
+async function withStructuredBlocks(
+  page: BaseSitePage | null,
+  locale?: string
+): Promise<SitePage | null> {
   if (!page) return null;
   return {
     ...page,
-    structuredBlocks: await getPageBlocks(page),
+    structuredBlocks: await getPageBlocks(page, locale),
   };
 }
 
-export async function listSitePages() {
-  const pages = await pagesApi.listSitePages();
-  const resolved = await Promise.all(pages.map((page) => withStructuredBlocks(page)));
+export async function listSitePages(locale?: string) {
+  const resolvedLocale = locale ?? getRequestLocale(i18n.defaultLocale);
+  const pages = await pagesApi.listSitePages(resolvedLocale);
+  const resolved = await Promise.all(pages.map((page) => withStructuredBlocks(page, resolvedLocale)));
   return resolved.filter((page): page is SitePage => Boolean(page));
 }
 
-export async function getSitePageByKey(key: string) {
-  return withStructuredBlocks(await pagesApi.getSitePageByKey(key));
+export async function getSitePageByKey(key: string, locale?: string) {
+  const resolvedLocale = locale ?? getRequestLocale(i18n.defaultLocale);
+  return withStructuredBlocks(await pagesApi.getSitePageByKey(key, resolvedLocale), resolvedLocale);
 }
 
-export async function getSitePageBySlug(slug: string) {
-  return withStructuredBlocks(await pagesApi.getSitePageBySlug(slug));
+export async function getSitePageBySlug(slug: string, locale?: string) {
+  const resolvedLocale = locale ?? getRequestLocale(i18n.defaultLocale);
+  return withStructuredBlocks(await pagesApi.getSitePageBySlug(slug, resolvedLocale), resolvedLocale);
 }
 export const getSitePageForContentSource = pagesApi.getSitePageForContentSource;
 export const getSiteNavigation = pagesApi.getSiteNavigation;

package/dist/templates/lib/pages/translations.ts.tmpl

@@ -2,9 +2,15 @@
 // localized page is missing in the target locale, do not pretend the
 // page exists — let the caller render a localized not-found.
 
-import { pickTranslation } from "@notionx/core";
+import {
+  pickTranslation,
+  mapNotionPageToLocalizedContentTranslation,
+  listGenericNotionContentForLocale,
+} from "@notionx/core";
 import { i18n } from "@/lib/i18n";
 import { pagesContract } from "@/lib/locale-contract";
+import { pageTranslationsSource } from "@/lib/content/models";
+import type { NotionPageLike } from "@notionx/core";
 
 export type PageTranslation = {
   pageId: string;
@@ -32,3 +38,19 @@ export function getDefaultLocalePage(
 ): PageTranslation | null {
   return pickTranslation(rows, i18n.defaultLocale, pagesContract, i18n.defaultLocale);
 }
+
+export async function listPageTranslations(locale: string): Promise<PageTranslation[]> {
+  if (!pageTranslationsSource) return [];
+  const pages = await listGenericNotionContentForLocale(pageTranslationsSource, locale);
+  return pages
+    .map((p) => mapNotionPageToLocalizedContentTranslation<PageTranslation>(p as unknown as NotionPageLike, {
+      fields: {
+        title: "Title",
+        source: "Source",
+        locale: "Locale",
+        slug: "Slug",
+        published: "Published",
+      },
+    }))
+    .filter((row): row is PageTranslation => row !== null);
+}

package/dist/templates/lib/site/request-env.ts.tmpl

@@ -46,6 +46,12 @@ import { AsyncLocalStorage } from "node:async_hooks";
  */
 export interface RequestEnv {
   CONTENT_CACHE?: KVNamespace;
+  /**
+   * Locale resolved by the middleware from the `/{locale}` path
+   * prefix. Server components and data loaders read this via
+   * `getRequestLocale()` to pick the right translation rows.
+   */
+  NOTIONX_LOCALE?: string;
   // Extend as new runtime consumers need to read env outside the
   // worker entry (e.g. cron-triggered helpers).
 }
@@ -69,3 +75,13 @@ export function runWithRequestEnv<T>(env: RequestEnv, fn: () => T): T {
 export function getRequestEnv(): RequestEnv | undefined {
   return _envStore.getStore();
 }
+
+/**
+ * Read the locale for the current request, set by the locale prefix
+ * middleware. Falls back to the default locale when called outside a
+ * request scope (build scripts, tests) or when the middleware did
+ * not run (e.g. single-locale projects).
+ */
+export function getRequestLocale(defaultLocale = "en"): string {
+  return getRequestEnv()?.NOTIONX_LOCALE ?? defaultLocale;
+}