---

name: bellog-notion description: Provides Notion CMS integration patterns and best practices for Bellog. Triggers when working with Notion data or implementing Notion-based features.

Bellog Notion CMS Integration

This skill defines how to work with Notion as a CMS in the Bellog blog project.

Architecture Overview

Bellog uses Notion as a headless CMS:

• Content is managed in a Notion database
• Data is fetched via Notion API
• Content is rendered using react-notion-x
• Caching with Next.js for performance

Key Files

• /src/lib/notion.ts - Notion API client & queries
• /src/lib/posts.ts - Cached data fetching
• /src/lib/tags.ts - Tag aggregation
• /src/types/index.d.ts - Type definitions
• /src/app/api/revalidate/route.ts - Cache invalidation

Notion Database Schema

Properties Structure

Copyinterface NotionPostProperties {
  // Required properties
  title: {
    type: "title";
    title: Array<RichTextItemResponse>;
  };

  date: {
    type: "date";
    date: { start: string } | null;
  };

  description: {
    type: "rich_text";
    rich_text: Array<RichTextItemResponse>;
  };

  slug: {
    type: "rich_text";
    rich_text: Array<RichTextItemResponse>;
  };

  tags: {
    type: "multi_select";
    multi_select: Array<{
      name: string;
      color: string;
    }>;
  };

  status: {
    type: "select";
    select: {
      name: "published" | "draft" | "archived";
    } | null;
  };
}

Field Details

• title (Title property) - Post title
• date (Date property) - Publication date
• description (Rich Text) - Brief summary/excerpt
• slug (Rich Text) - URL-friendly identifier
• tags (Multi-select) - Post categories/topics
• status (Select) - Publication status

Utility Functions

From /src/lib/notion.ts

1. Get All Published Posts

Copyimport { getAllPostsFromNotion } from '@/lib/notion';

// Fetches all posts with status = "published"
const posts = await getAllPostsFromNotion();

Returns:

CopyArray<{
  id: string;
  title: string;
  slug: string;
  date: string;
  description: string;
  tags: string[];
  status: string;
}>

Query Details:

• Filters: status = "published"
• Sorts: date descending
• Includes: All post properties

2. Get Post by Slug

Copyimport { getPostBySlugFromNotion } from '@/lib/notion';

const post = await getPostBySlugFromNotion('my-post-slug');

Returns: Single post object or null if not found

3. Get Post Content (RecordMap)

Copyimport { getPostRecordMap } from '@/lib/notion';

// Get full page content for rendering
const recordMap = await getPostRecordMap(pageId);

Returns: ExtendedRecordMap for react-notion-x

Use: When rendering full post content with NotionRenderer

Data Extraction Patterns

Extract Plain Text from Rich Text

Copyfunction extractPlainText(
  richText: Array<RichTextItemResponse>
): string {
  return richText.map(item => item.plain_text).join('');
}

// Usage
const description = post.properties.description.rich_text
  .map(item => item.plain_text)
  .join('');

Extract Title

Copyconst title = post.properties.title.title
  .map(item => item.plain_text)
  .join('');

Extract Tags

Copyconst tags = post.properties.tags.multi_select
  .map(tag => tag.name);

Extract Date

Copyconst date = post.properties.date.date?.start || '';

Caching Strategy

Pattern from /src/lib/posts.ts

Two-level caching:

1. React cache() - Request deduplication
2. Next.js unstable_cache() - Persistent caching

Copyimport { cache } from "react";
import { unstable_cache } from "next/cache";
import { getAllPostsFromNotion } from './notion';

export const getAllPosts = cache(
  unstable_cache(
    async () => {
      const posts = await getAllPostsFromNotion();

      // Sort by date descending
      return posts.sort((a, b) =>
        new Date(b.date).getTime() - new Date(a.date).getTime()
      );
    },
    ["all-posts"], // Cache key
    {
      revalidate: 3600, // 1 hour
      tags: ["posts", "notion"] // For invalidation
    }
  )
);

Why Two Levels?

• React cache(): Prevents duplicate fetches in single render
• unstable_cache(): Persists data across requests with TTL

Cache Keys

Copy["all-posts"]           // All posts list
["post-{slug}"]         // Individual post
["post-recordmap-{id}"] // Post content

Cache Tags

Copy["posts", "notion"]     // Tag for bulk invalidation

On-Demand Revalidation

API Route

File: /src/app/api/revalidate/route.ts

Copyimport { revalidateTag } from 'next/cache';

export async function POST(request: Request) {
  // Verify secret
  const secret = request.nextUrl.searchParams.get('secret');

  if (secret !== process.env.REVALIDATION_SECRET) {
    return Response.json(
      { message: 'Invalid secret' },
      { status: 401 }
    );
  }

  // Invalidate cache
  revalidateTag('notion');

  return Response.json({
    revalidated: true,
    now: Date.now()
  });
}

Usage

Trigger from Notion webhook:

Copycurl -X POST "https://bellog.com/api/revalidate?secret=YOUR_SECRET"

Manual trigger:

Copycurl -X POST "http://localhost:3000/api/revalidate?secret=dev_secret"

What Gets Revalidated

All cached data with tag "notion":

• Post list
• Individual posts
• Tag counts

Rendering Notion Content

With react-notion-x

Copyimport { NotionRenderer } from 'react-notion-x';
import { getPostRecordMap } from '@/lib/notion';

export default async function PostContent({ postId }: Props) {
  // Fetch content
  const recordMap = await getPostRecordMap(postId);

  return (
    <NotionRenderer
      recordMap={recordMap}
      fullPage={false}
      darkMode={false} // Handle with useTheme in client
      components={{
        // Custom component overrides
        Code: CustomCodeBlock,
        Collection: CustomCollection,
        Equation: CustomEquation
      }}
    />
  );
}

Custom Components

Override default rendering:

Copyimport { Code } from 'react-notion-x/build/third-party/code';

// Custom code block with line numbers
function CustomCodeBlock({ block }) {
  return (
    <div className="custom-code-wrapper">
      <Code block={block} />
    </div>
  );
}

Environment Variables

Required in .env.local

Copy# Official Notion API
NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxx
NOTION_DATABASE_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# notion-client (for react-notion-x)
NOTION_TOKEN_V2=v02%3Auser_token_or_cookie...
NOTION_ACTIVE_USER=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Cache revalidation
REVALIDATION_SECRET=your_random_secret_string

Getting Values

NOTION_API_KEY:

1. Go to https://www.notion.so/my-integrations
2. Create new integration
3. Copy "Internal Integration Token"

NOTION_DATABASE_ID:

1. Open database in Notion
2. Copy ID from URL: notion.so/workspace/[THIS_PART]?v=...

NOTION_TOKEN_V2:

1. Open Notion in browser
2. DevTools → Application → Cookies
3. Copy token_v2 value

NOTION_ACTIVE_USER:

1. Same location as token_v2
2. Copy notion_user_id value

Type Safety

Post Type

Copy// /src/types/index.d.ts

export interface Post {
  id: string;
  title: string;
  slug: string;
  date: string;
  description: string;
  tags: string[];
  status: PostStatus;
}

export type PostStatus = 'published' | 'draft' | 'archived';

Accessing Properties

Copy// ✅ Type-safe access
import type { QueryDatabaseResponse } from '@notionhq/client/build/src/api-endpoints';

const page = response.results[0] as PageObjectResponse;

if (page.properties.title.type === 'title') {
  const title = page.properties.title.title
    .map(t => t.plain_text)
    .join('');
}

Error Handling

API Call Errors

Copytry {
  const posts = await getAllPostsFromNotion();
  return posts;
} catch (error) {
  console.error('Failed to fetch posts:', error);

  // Return fallback
  return [];

  // Or rethrow for error boundary
  throw new Error('Failed to load posts');
}

Missing Properties

Copy// Check property exists and has value
const date = post.properties.date?.date?.start || new Date().toISOString();

// Provide defaults
const description = post.properties.description?.rich_text?.[0]?.plain_text || '';

Notion API Rate Limits

Limits:

• 3 requests per second
• Averaged over 1-minute window

Mitigation:

• Caching with unstable_cache
• Revalidate on-demand instead of frequent polling
• Use TTL (1 hour) to reduce API calls

Adding New Properties

Steps

1. Add to Notion Database

   • Open database in Notion
   • Add new property with desired type

2. Update TypeScript Types

   Copy// /src/types/index.d.ts
   export interface Post {
     // ... existing fields
     author?: string; // New field
   }
   

3. Extract in Notion Client

   Copy// /src/lib/notion.ts
   export async function getAllPostsFromNotion() {
     // ... existing code
   
     const posts = results.map(page => ({
       // ... existing fields
       author: extractPlainText(page.properties.author.rich_text)
     }));
   }
   

4. Invalidate Cache

   Copycurl -X POST "http://localhost:3000/api/revalidate?secret=dev_secret"
   

Best Practices

1. Always Cache

Copy// ✅ Correct - Always use caching
export const getPosts = cache(
  unstable_cache(
    async () => await notion.query(...),
    ['key'],
    { revalidate: 3600 }
  )
);

// ❌ Wrong - Direct API calls
export async function getPosts() {
  return await notion.query(...); // No caching!
}

2. Handle Missing Data

Copy// ✅ Correct - Provide defaults
const title = page.properties.title?.title?.[0]?.plain_text || 'Untitled';

// ❌ Wrong - Can crash if undefined
const title = page.properties.title.title[0].plain_text;

3. Use Tags for Invalidation

Copy// ✅ Correct - Use tags
unstable_cache(
  fetchFunction,
  ['key'],
  { tags: ['posts', 'notion'] } // Can invalidate by tag
);

// ❌ Wrong - No tags
unstable_cache(
  fetchFunction,
  ['key'],
  {} // Can't invalidate efficiently
);

4. Separate Concerns

Copy// ✅ Correct - API calls in notion.ts, caching in posts.ts
// /src/lib/notion.ts
export async function getAllPostsFromNotion() { }

// /src/lib/posts.ts
export const getAllPosts = cache(unstable_cache(...));

// ❌ Wrong - Mix concerns
export const getAllPosts = async () => {
  const response = await notion.databases.query(...); // Mixed!
}

5. Type Everything

Copy// ✅ Correct - Explicit types
import type { PageObjectResponse } from '@notionhq/client/build/src/api-endpoints';

const page = result as PageObjectResponse;

// ❌ Wrong - Any types
const page: any = result;

Performance Tips

1. RecordMap Caching

Copy// Cache post content separately
export const getPostContent = cache(
  unstable_cache(
    async (id: string) => await getPostRecordMap(id),
    ['post-content'],
    { revalidate: 3600, tags: ['notion'] }
  )
);

2. Parallel Fetching

Copy// Fetch multiple posts in parallel
const [post1, post2] = await Promise.all([
  getPostBySlug('slug-1'),
  getPostBySlug('slug-2')
]);

3. Partial Revalidation

Copy// Only revalidate specific posts
revalidatePath(`/posts/${slug}`);

// Instead of everything
revalidateTag('notion');

Common Patterns

Get Recent Posts

Copyexport async function getRecentPosts(limit: number = 5) {
  const allPosts = await getAllPosts();
  return allPosts.slice(0, limit);
}

Filter by Tag

Copyexport async function getPostsByTag(tag: string) {
  const allPosts = await getAllPosts();
  return allPosts.filter(post => post.tags.includes(tag));
}

Count Posts by Tag

Copy// /src/lib/tags.ts
export async function getTagCounts() {
  const posts = await getAllPosts();
  const counts = new Map<string, number>();

  posts.forEach(post => {
    post.tags.forEach(tag => {
      counts.set(tag, (counts.get(tag) || 0) + 1);
    });
  });

  return Array.from(counts.entries())
    .map(([tag, count]) => ({ tag, count }))
    .sort((a, b) => b.count - a.count);
}

Troubleshooting

Issue: Stale Data

Solution: Trigger revalidation

Copycurl -X POST "/api/revalidate?secret=YOUR_SECRET"

Issue: Rate Limited

Check: Are you calling API too frequently? Solution: Increase cache TTL, reduce manual revalidation

Issue: Missing Properties

Check: Is property name exactly matching? Solution: Use Notion API to inspect property names

Issue: Empty Content

Check: Is NOTION_TOKEN_V2 valid? Solution: Re-copy token from browser cookies

Quick Reference

Copy// Fetch all posts
import { getAllPosts } from '@/lib/posts';
const posts = await getAllPosts();

// Fetch single post
import { getPostBySlugFromNotion } from '@/lib/notion';
const post = await getPostBySlugFromNotion('slug');

// Fetch post content
import { getPostRecordMap } from '@/lib/notion';
const recordMap = await getPostRecordMap(postId);

// Render content
import { NotionRenderer } from 'react-notion-x';
<NotionRenderer recordMap={recordMap} />

// Invalidate cache
revalidateTag('notion');

// Environment variables
NOTION_API_KEY
NOTION_DATABASE_ID
NOTION_TOKEN_V2
NOTION_ACTIVE_USER
REVALIDATION_SECRET

Remember: Notion is the source of truth. Always cache and always handle missing data gracefully.