Using Notion as a CMS Backend for Rork Apps — Auth, Block Rendering, Rate Limits, and the 1-Hour Image URL Problem

// server/src/routes/articles.ts
import { Hono } from "hono";
import { cache } from "hono/cache";
import { Client } from "@notionhq/client";
 
type Bindings = {
  NOTION_TOKEN: string;
  NOTION_DATABASE_ID: string;
};
 
const app = new Hono<{ Bindings: Bindings }>();
 
app.get(
  "/articles",
  cache({
    cacheName: "notion-articles",
    cacheControl: "public, max-age=300", // 5-minute edge cache
  }),
  async (c) => {
    const notion = new Client({ auth: c.env.NOTION_TOKEN });
 
    try {
      const res = await notion.databases.query({
        database_id: c.env.NOTION_DATABASE_ID,
        filter: {
          and: [
            { property: "Status", select: { equals: "Published" } },
            { property: "Locale", select: { equals: "en" } },
          ],
        },
        sorts: [{ property: "PublishedAt", direction: "descending" }],
        page_size: 50,
      });
 
      const articles = res.results.map((page: any) => ({
        id: page.id,
        slug: page.properties.Slug.rich_text[0]?.plain_text ?? "",
        title: page.properties.Title.title[0]?.plain_text ?? "Untitled",
        excerpt: page.properties.Excerpt.rich_text[0]?.plain_text ?? "",
        publishedAt: page.properties.PublishedAt.date?.start ?? null,
        cover: page.cover?.type === "external"
          ? page.cover.external.url
          : page.cover?.file?.url ?? null,
      }));
 
      return c.json({ articles });
    } catch (err: any) {
      // Notion often returns transient 5xx — short retries tend to resolve them
      console.error("notion-query-failed", err.code, err.message);
      return c.json({ error: "notion_unavailable" }, 503);
    }
  }
);
 
export default app;

// app/components/NotionRenderer.tsx
import { View, Text, Image, StyleSheet } from "react-native";
 
type NotionBlock =
  | { id: string; type: "paragraph"; paragraph: { rich_text: RichText[] } }
  | { id: string; type: "heading_2"; heading_2: { rich_text: RichText[] } }
  | { id: string; type: "heading_3"; heading_3: { rich_text: RichText[] } }
  | { id: string; type: "bulleted_list_item"; bulleted_list_item: { rich_text: RichText[] } }
  | { id: string; type: "code"; code: { rich_text: RichText[]; language: string } }
  | { id: string; type: "image"; image: { type: "file" | "external"; file?: { url: string }; external?: { url: string } } }
  | { id: string; type: string; [key: string]: unknown }; // fallback for unknown types
 
type RichText = { plain_text: string; annotations: { bold: boolean; italic: boolean; code: boolean } };
 
export function NotionRenderer({ blocks }: { blocks: NotionBlock[] }) {
  return (
    <View>
      {blocks.map((block) => (
        <BlockView key={block.id} block={block} />
      ))}
    </View>
  );
}
 
function BlockView({ block }: { block: NotionBlock }) {
  switch (block.type) {
    case "paragraph":
      return <Paragraph text={block.paragraph.rich_text} />;
    case "heading_2":
      return <Heading level={2} text={block.heading_2.rich_text} />;
    case "heading_3":
      return <Heading level={3} text={block.heading_3.rich_text} />;
    case "bulleted_list_item":
      return <BulletItem text={block.bulleted_list_item.rich_text} />;
    case "code":
      return <CodeBlock text={block.code.rich_text} language={block.code.language} />;
    case "image": {
      const url = block.image.type === "file"
        ? block.image.file?.url
        : block.image.external?.url;
      if (!url) return null;
      return <NotionImage url={url} />;
    }
    default:
      // Never swallow silently — surface in dev, fall back cleanly in prod
      if (__DEV__) {
        return (
          <View style={styles.unknown}>
            <Text style={styles.unknownText}>Unsupported block: {block.type}</Text>
          </View>
        );
      }
      return null;
  }
}
 
function renderRichText(rich: RichText[]) {
  return rich.map((r, i) => {
    const style = [
      r.annotations.bold && styles.bold,
      r.annotations.italic && styles.italic,
      r.annotations.code && styles.inlineCode,
    ].filter(Boolean);
    return (
      <Text key={i} style={style}>
        {r.plain_text}
      </Text>
    );
  });
}
 
function Paragraph({ text }: { text: RichText[] }) {
  return <Text style={styles.paragraph}>{renderRichText(text)}</Text>;
}
 
function Heading({ level, text }: { level: 2 | 3; text: RichText[] }) {
  const style = level === 2 ? styles.h2 : styles.h3;
  return <Text style={style}>{renderRichText(text)}</Text>;
}
 
function BulletItem({ text }: { text: RichText[] }) {
  return (
    <View style={styles.bulletRow}>
      <Text style={styles.bulletDot}>•</Text>
      <Text style={styles.bulletText}>{renderRichText(text)}</Text>
    </View>
  );
}
 
function CodeBlock({ text, language }: { text: RichText[]; language: string }) {
  const source = text.map((r) => r.plain_text).join("");
  return (
    <View style={styles.codeWrap}>
      <Text style={styles.codeLang}>{language}</Text>
      <Text style={styles.codeBody}>{source}</Text>
    </View>
  );
}
 
function NotionImage({ url }: { url: string }) {
  // url is routed through the image proxy defined later
  return <Image source={{ uri: url }} style={styles.image} resizeMode="cover" />;
}
 
const styles = StyleSheet.create({
  paragraph: { fontSize: 16, lineHeight: 26, marginVertical: 8, color: "#111" },
  h2: { fontSize: 22, fontWeight: "700", marginTop: 24, marginBottom: 12 },
  h3: { fontSize: 18, fontWeight: "700", marginTop: 16, marginBottom: 8 },
  bold: { fontWeight: "700" },
  italic: { fontStyle: "italic" },
  inlineCode: { fontFamily: "Menlo", backgroundColor: "#f2f2f2" },
  bulletRow: { flexDirection: "row", marginVertical: 4 },
  bulletDot: { marginRight: 8, lineHeight: 26 },
  bulletText: { flex: 1, fontSize: 16, lineHeight: 26 },
  codeWrap: { backgroundColor: "#f6f8fa", padding: 12, borderRadius: 8, marginVertical: 12 },
  codeLang: { fontSize: 11, color: "#888", marginBottom: 6 },
  codeBody: { fontFamily: "Menlo", fontSize: 13, lineHeight: 20 },
  image: { width: "100%", aspectRatio: 16 / 9, borderRadius: 8, marginVertical: 12 },
  unknown: { padding: 8, backgroundColor: "#fff4e5", borderRadius: 4, marginVertical: 4 },
  unknownText: { color: "#b16a00", fontSize: 12 },
});

// server/src/routes/image-proxy.ts
import { Hono } from "hono";
import { Client } from "@notionhq/client";
 
type Bindings = { NOTION_TOKEN: string };
 
const app = new Hono<{ Bindings: Bindings }>();
 
// Clients call /image-proxy?pageId=xxx&blockId=yyy
app.get("/image-proxy", async (c) => {
  const pageId = c.req.query("pageId");
  const blockId = c.req.query("blockId");
 
  if (!pageId || !blockId) {
    return c.json({ error: "missing_params" }, 400);
  }
 
  const notion = new Client({ auth: c.env.NOTION_TOKEN });
 
  try {
    // Re-fetching the block gives us a URL that is valid right now
    const block: any = await notion.blocks.retrieve({ block_id: blockId });
 
    if (block.type !== "image") {
      return c.json({ error: "not_an_image" }, 400);
    }
 
    const url = block.image.type === "file"
      ? block.image.file.url
      : block.image.external.url;
 
    if (!url) {
      return c.json({ error: "no_url" }, 404);
    }
 
    // Fetch the image bytes and proxy them — clients never see the Notion URL
    const imageRes = await fetch(url);
    if (!imageRes.ok) {
      return c.json({ error: "notion_image_fetch_failed" }, 502);
    }
 
    const body = await imageRes.arrayBuffer();
    return new Response(body, {
      status: 200,
      headers: {
        "Content-Type": imageRes.headers.get("Content-Type") ?? "image/jpeg",
        // Ten-minute edge cache suppresses repeat Notion calls for the same image
        "Cache-Control": "public, max-age=600, s-maxage=600",
        "ETag": imageRes.headers.get("ETag") ?? "",
      },
    });
  } catch (err: any) {
    console.error("image-proxy-failed", err.code, err.message);
    return c.json({ error: "proxy_failed" }, 500);
  }
});
 
export default app;

// server/src/lib/notion-with-retry.ts
export async function queryWithRetry<T>(
  fn: () => Promise<T>,
  options: { maxRetries?: number; baseDelayMs?: number } = {}
): Promise<T> {
  const maxRetries = options.maxRetries ?? 3;
  const baseDelay = options.baseDelayMs ?? 500;
 
  let lastError: unknown;
 
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      lastError = err;
 
      // Retry only 429 and 5xx — 4xx usually means "you did the wrong thing"
      const code = err?.status ?? err?.code;
      const isRetryable =
        code === 429 ||
        code === "rate_limited" ||
        (typeof code === "number" && code >= 500 && code < 600);
 
      if (!isRetryable || attempt === maxRetries) {
        throw err;
      }
 
      // Honor Retry-After when present, otherwise exponential backoff with jitter
      const retryAfter = Number(err?.headers?.["retry-after"]);
      const delay = Number.isFinite(retryAfter) && retryAfter > 0
        ? retryAfter * 1000
        : baseDelay * Math.pow(2, attempt) + Math.random() * 200;
 
      console.warn(`notion-retry attempt=${attempt + 1} delay=${delay}ms code=${code}`);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
 
  throw lastError;
}

// app/hooks/useArticles.ts
import { useQuery, useInfiniteQuery } from "@tanstack/react-query";
 
const API_BASE = process.env.EXPO_PUBLIC_API_BASE!;
 
type ArticleSummary = {
  id: string;
  slug: string;
  title: string;
  excerpt: string;
  publishedAt: string | null;
  cover: string | null;
};
 
async function fetchArticles(cursor?: string): Promise<{ articles: ArticleSummary[]; nextCursor?: string }> {
  const url = new URL("/articles", API_BASE);
  if (cursor) url.searchParams.set("cursor", cursor);
 
  const res = await fetch(url.toString());
  if (!res.ok) {
    throw new Error(`articles_fetch_failed: ${res.status}`);
  }
  return res.json();
}
 
export function useArticleList() {
  return useInfiniteQuery({
    queryKey: ["articles"],
    queryFn: ({ pageParam }) => fetchArticles(pageParam as string | undefined),
    initialPageParam: undefined as string | undefined,
    getNextPageParam: (last) => last.nextCursor,
    // Match the server edge cache: data is fresh for 5 minutes
    staleTime: 1000 * 60 * 5,
    // Keep previous data while refetching on focus — no flash of empty list
    refetchOnWindowFocus: false,
  });
}
 
export function useArticle(slug: string) {
  return useQuery({
    queryKey: ["article", slug],
    queryFn: async () => {
      const res = await fetch(`${API_BASE}/articles/${slug}`);
      if (!res.ok) throw new Error(`article_fetch_failed: ${res.status}`);
      return res.json();
    },
    staleTime: 1000 * 60 * 5,
    // The server handles retries for us; retry once on the client for transient network blips
    retry: 1,
  });
}

// app/providers.tsx
import { QueryClient, QueryClientProvider, focusManager } from "@tanstack/react-query";
import { AppState, type AppStateStatus } from "react-native";
import { useEffect } from "react";
 
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // Avoid refetch storms when the user briefly backgrounds the app
      refetchOnReconnect: "always",
      gcTime: 1000 * 60 * 30,
      networkMode: "offlineFirst",
    },
  },
});
 
export function AppProviders({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    const sub = AppState.addEventListener("change", (state: AppStateStatus) => {
      focusManager.setFocused(state === "active");
    });
    return () => sub.remove();
  }, []);
 
  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}

// server/src/lib/fetch-blocks.ts
import { Client } from "@notionhq/client";
 
type BlockNode = { id: string; type: string; has_children: boolean; children?: BlockNode[] } & Record<string, unknown>;
 
export async function fetchBlockTree(notion: Client, blockId: string, depth = 0): Promise<BlockNode[]> {
  // Guard against pathologically deep pages — the Notion API allows deep nesting
  if (depth > 6) {
    console.warn("fetchBlockTree: max depth reached", { blockId });
    return [];
  }
 
  const results: BlockNode[] = [];
  let cursor: string | undefined = undefined;
 
  do {
    const res = await notion.blocks.children.list({
      block_id: blockId,
      start_cursor: cursor,
      page_size: 100,
    });
 
    for (const raw of res.results as any[]) {
      const node: BlockNode = { ...raw };
      if (raw.has_children) {
        node.children = await fetchBlockTree(notion, raw.id, depth + 1);
      }
      results.push(node);
    }
 
    cursor = res.next_cursor ?? undefined;
  } while (cursor);
 
  return results;
}

// server/src/lib/article-filter.ts
export function buildPublishedFilter(locale: "ja" | "en", now = new Date()) {
  return {
    and: [
      { property: "Status", select: { equals: "Published" } },
      { property: "Locale", select: { equals: locale } },
      {
        property: "PublishedAt",
        date: { on_or_before: now.toISOString() },
      },
    ],
  };
}