FeaturesCMS

Notion

Learn how to use Notion as Content Management System in your application.

In this guide, we gonna implement a blog using Notion as a content management system.

The @kit/notion package contains a type-safe client built using zod to validate the data. Our client is built on top of the notionhq/client package which is the official Notion client.

Create a notion database

The easiest way is to import our database template.

Download the database template.

Blog Template

We recommend you to use our template to make it work with the already existing ui. But you can customize it to your needs.

Import it in your Notion workspace.

Importing the blog database template in Notion

Set your Notion Connection to expose your data

Add a new integration.

In the browser, go to https://www.notion.so/profile/integrations and add a "New integration".

You can let the type to Public is not required, you can let it Internal.

Configure your integration settings.

In "Configuration" tab > Capabilities we gonna need :

Select "Read content" only (remove the other capabilities)
Select "No user information" (in the "User capabilities" section)

Set the `NOTION_INTEGRATION_SECRET` environment variable.

Show the "Internal Integration Secret" field and copy the value.

Use the copied value to set the NOTION_INTEGRATION_SECRET environment variable.

NOTION_INTEGRATION_SECRET=your-integration-secret

Set your config file

Create a config/cms.config.ts file in your application and set the NOTION_INTEGRATION_SECRET environment variable.

config/cms.config.ts

'server-only';
 
import { parseNotionConfig } from '@kit/notion/config';
import { envs } from '~/envs';
 
export const notionConfig = parseNotionConfig({
    auth: envs().NOTION_INTEGRATION_SECRET,
    contentTypes: { // edit this object to fit your needs
        // your content types here ...
    },
});

Prop	Type	Default
`contentTypes*`	`Record<string, { id: string; def: AnyContentTypeDef; }>`
`auth*`	`string`

Add a new content type

Connect you database

Connect you database to your previously created integration

Connecting your database to your previously created integration

Get your database source id

Getting your database source id

Set the NOTION_POSTS_DB_ID environment variable.

NOTION_POSTS_DB_ID=your-database-source-id

Set your notion definition in the config file

To let the @kit/notion package to know the nature of your database, you need to add it in the contentTypes object.

config/cms.config.ts


'server-only';
 
import { parseNotionConfig } from '@kit/notion/config';
import { envs } from '~/envs';
 
export const notionConfig = parseNotionConfig({
    auth: envs().NOTION_INTEGRATION_SECRET,
    contentTypes: {
        posts: {
            id: envs().NOTION_POSTS_DB_ID,
            def: {
                categories: 'multi_select',
                language: 'select',
                description: 'rich_text',
                slug: 'rich_text',
                image: 'files',
                status: 'status',
                title: 'title',
            },
        },
    },
});

Use the following tool to get your notion definition.

'use client';

import { highlightCode } from '@kit/cms/lib/highlight-code';
import { CmsCopyButton } from '@kit/cms/ui/mdx/cms-copy-button';
import { Alert, AlertDescription, AlertTitle } from '@kit/ui/alert';
import { Button } from '@kit/ui/button';
import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@kit/ui/form';
import { useZodForm } from '@kit/ui/hooks/use-zod-form';
import { Input } from '@kit/ui/input';
import { useEffect, useState } from 'react';
import { z } from 'zod';
import { fetchNotionSchemaAction } from '../../../lib/notion-fetch-action';

// Form schema
const notionSchemaFormSchema = z.object({
    auth: z.string().min(1, 'Notion auth token is required'),
    databaseId: z.string().min(1, 'Database ID is required'),
});

type NotionSchemaFormValues = z.infer<typeof notionSchemaFormSchema>;

export const NotionSchemaFetcher = () => {
    const [schema, setSchema] = useState<any>(null);
    const [highlightedCode, setHighlightedCode] = useState<string>('');
    const [isLoading, setIsLoading] = useState(false);
    const [error, setError] = useState<string | null>(null);

    const form = useZodForm({
        schema: notionSchemaFormSchema,
        defaultValues: {
            auth: '',
            databaseId: '',
        },
    });

    // Highlight code when schema changes
    useEffect(() => {
        if (schema) {
            const jsonString = JSON.stringify(schema, null, 2);
            highlightCode(jsonString, 'json').then(setHighlightedCode);
        } else {
            setHighlightedCode('');
        }
    }, [schema]);

    const onSubmit = async (values: NotionSchemaFormValues) => {
        setIsLoading(true);
        setError(null);

        try {
            const result = await fetchNotionSchemaAction(values);

            console.log( {result} )
            console.log( {values} )

            if (result?.data?.success) {
                setSchema(result.data.data);
                console.log(result.data);
            } else {
                setError(result?.serverError || 'An error occurred');
                setSchema(null);
            }
        } catch (err) {
            setError(err instanceof Error ? err.message : 'An error occurred');
            setSchema(null);
        } finally {
            setIsLoading(false);
        }
    };

    return (
        <div className="mx-auto w-full max-w-lg space-y-6 p-6">
            <Form {...form}>
                <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
                    <FormField
                        control={form.control}
                        name="auth"
                        render={({ field }) => (
                            <FormItem>
                                <FormLabel>Integration Secret</FormLabel>
                                <FormControl>
                                    <Input placeholder="Enter your Notion integration secret" {...field} />
                                </FormControl>
                                <FormMessage />
                            </FormItem>
                        )}
                    />

                    <FormField
                        control={form.control}
                        name="databaseId"
                        render={({ field }) => (
                            <FormItem>
                                <FormLabel>Database ID</FormLabel>
                                <FormControl>
                                    <Input placeholder="Enter your Notion database ID" {...field} />
                                </FormControl>
                                <FormMessage />
                            </FormItem>
                        )}
                    />

                    <Button type="submit" loading={isLoading} aria-label="Fetch Notion schema">
                        {isLoading ? 'Fetching...' : 'Fetch Schema'}
                    </Button>
                </form>
            </Form>

            {error && (
                <Alert variant="destructive">
                    <AlertTitle>Error</AlertTitle>
                    <AlertDescription>{error}</AlertDescription>
                </Alert>
            )}

            {highlightedCode && (
                <div className="space-y-2">
                    <h3 className="text-lg font-semibold">Schema Results</h3>
                    <figure data-rehype-pretty-code-figure="" className="[&>pre]:max-h-96">
                        <CmsCopyButton toCopy={JSON.stringify(schema, null, 2)} />
                        <div dangerouslySetInnerHTML={{ __html: highlightedCode }} />
                    </figure>
                </div>
            )}
        </div>
    );
};

Once your defintion is fetched, you can refresh your "Internal Integration Secret" if you want to have an easy mind.

Content type definition requirements

Some properties are using internally in the notion client from the @kit/notion package. For that reason, some properties are required and some optional allow you to implement some specific features.

Required fields

Here is the list of the required fields for a content type definition:

title: title
slug: rich_text (your slug do not must contains spaces)

Optional field

status: status (allow you to have a draft/published feature -> the pages will be loaded only if the status is published)

If you are implement a roadmap, definition requiements may be different. Check the roadmap definition requirements section.

Translations

You can easily manage your translations with the @kit/notion package.

Use the `language` property in your notion database (alredy present our the database template)

Filter your notion content items with the active i18n language

app/blog/page.tsx


'use server';
 
async function BlogPage(props: BlogPageProps): Promise<React.JSX.Element> {
    const { t, resolvedLanguage: language } = await getServerI18n();
 
    const blogPosts = await notionClient.getContentItems({
        contentType: 'posts',
        filter: {
            language,
        },
        sort: {
            by: ['createdTime'],
            direction: 'desc',
        },
        pagination: {
            limit,
            offset,
        },
        content: false,
    });
 
    return (
        <>
        {/* your page content here */}
        </>
    );
}

Environment variables

.env

NOTION_INTEGRATION_SECRET=your-integration-secret
 
# your database source id ...
NOTION_POSTS_DB_ID=your-database-source-id

Fumadocs

Implement your own documentation website with Fumadocs.

LLMs

Learn how to expose content for AI models.

How is this guide?

Last updated on 10/17/2025