# nextjs-notion-starter-kit: a Notion-backed Next.js site where one public page ID is the whole setup

> transitive-bullshit/nextjs-notion-starter-kit turns a public Notion page into a Next.js site deployed on Vercel. This piece covers the single config file, URL slug rules, the Vercel auth trap, and the optional Redis and analytics pieces.

**transitive-bullshit/nextjs-notion-starter-kit** — Deploy your own Notion-powered website in minutes with Next.js and Vercel.

- Repository: https://github.com/transitive-bullshit/nextjs-notion-starter-kit
- Website: https://transitivebullsh.it/nextjs-notion-starter-kit
- Stars: 7,040 · Forks: 5,637
- Language: TypeScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/transitive-bullshit-nextjs-notion-starter-kit

## The site is a public Notion page, so anything private on that page is already published

The whole architecture is one idea. Notion is the CMS, react-notion-x renders its blocks, Next.js builds the pages and Vercel hosts them. The repository is the code behind the author's own blog and portfolio at transitivebullsh.it, offered as a template.

The starting point is a Notion page. The setup text tells you to make your root page public, copy its link, and extract the last part of the URL, which looks like `7875426197cf461698809def95960ebf`. That 32-character string is the page's Notion ID. The consequence of this design is plain: a page the build can read is a page anyone can read, so nothing sensitive belongs under the root. There are no structural constraints on your workspace beyond that, and the author suggests putting a collection on the home page that lists your articles, projects or other content. Duplicating the default Notion page is the recommended way to start.

## Everything is configured in site.config.ts, and rootNotionPageId is the one value you must change

All configuration lives in site.config.ts. The project requires Node.js 22 or newer, and the quick path is a short list of steps: fork or clone, edit a few values, run `pnpm install`, run `pnpm dev` to test locally, run `pnpm deploy` to push to Vercel, then check the Vercel project settings. In package.json, `deploy` is simply `vercel deploy`, so the Vercel CLI must be available and signed in.

The author states that all you really need to edit to get started is `rootNotionPageId`. A Notion workspace ID is optional. To find it, load any of your pages, open the browser developer console, and enter `block.space_id`, because a global variable called `block` holds the Notion data for the current page. The same file holds the feature switches described below, such as `isPreviewImageSupportEnabled` and `isRedisEnabled`, so a surprising behaviour usually traces back to a value there.

## A default Vercel project returns 401 to social media crawlers

The sharpest edge is in the deployment step. Social media preview images will not work by default on Vercel. The cause is Vercel Authentication, which protects deployments, so crawlers that fetch your images receive `401 Unauthorized` responses instead of the picture.

The fix is in the Vercel project settings: disable Vercel Authentication under Project, Settings, Deployment Protection. If you forget, nothing about the site itself looks broken when you open it in your own browser. You only discover the problem when a link pasted into a social network shows no image. The kit generates social images automatically, so the feature is on, but it cannot work behind that protection. Check this setting before you announce a new site, not after.

## Dev and production use different URL paths, and renamed pages break old links

URLs are derived from Notion page titles. In development the path is a slugified title followed by the page's Notion ID, for example `/nextjs-notion-blog-d1b5dcf8b9ff425b8aef5ce6f0730202`, which the author finds useful for keeping the ID visible while working. In production the ID is dropped and the path becomes `/nextjs-notion-blog`. Pasting a dev pathname into production works, and the reverse works too.

The mapping from Notion ID to slugified title happens during the build. The limits are spelled out. If you change page titles over time, old links can stop working, and the project does not provide a way to detect them beyond the redirect support built into Next.js. If two pages in your workspace slugify to the same name, the app throws an error about duplicate URL pathnames. You can override the generated slug for a page by adding a `Slug` text property to your database; any page with that property uses it. The relevant code is lib/map-page-url.ts.

## Preview images are on by default and slow, and Redis caching is a separate opt-in

Images are served through next/image, with preview images optionally generated by lqip-modern. Previews are enabled by default, but they can be slow to generate. To turn them off, set `isPreviewImageSupportEnabled` to `false` in site.config.ts.

To cache generated previews and speed up later builds, you need an external Redis store. Set `isRedisEnabled` to `true` in site.config.ts and point two environment variables at your instance. Locally that is a .env file:

```bash
REDIS_HOST='TODO'
REDIS_PASSWORD='TODO'
```

Only REDIS_HOST and REDIS_PASSWORD are required, while `.env.example` also lists optional REDIS_USER with the value 'default' and REDIS_NAMESPACE with 'preview-images'. Forgetting to flip `isRedisEnabled` means the variables are ignored. Both previews and Redis are optional, and the author says that if you would rather not deal with them you can disable them in the site config. Redis Labs is named as an option with a free plan.

## Styling goes through notion.css and per-block class names

All CSS that customises Notion content is in styles/notion.css. It mainly targets global classes exported by the react-notion-x stylesheet. Every Notion block gets its own unique class name, so you can reach one block directly:

```css
.notion-block-260baa77f1e1428b97fb14ac99c7c385 {
  display: none;
}
```

This is a precise tool and a fragile one, because the class name is tied to the block's ID. Delete and recreate the block in Notion and the rule no longer matches. The kit also ships dark mode through next-themes, a table of contents, and a CMD+K or CMD+P quick search. Analytics are optional and keyed by environment variables: `NEXT_PUBLIC_FATHOM_ID` for Fathom and `NEXT_PUBLIC_POSTHOG_ID` for PostHog. An optional `TWITTER_ACCESS_TOKEN` is there for rendering tweets more efficiently.

## No tagged releases, a private package at 2.0.0, and a tooling stack built on oxc

The repository has no GitHub releases, so there is no version tag to pin. The package.json version is 2.0.0 and the package is marked private, which fits a template you fork and not a library you install. The last push was 2026-10-18. The demos clarify what each branch is: the default demo is deployed from `main`, while the author's own site is deployed from the `transitive-bullshit` branch.

The dependency list includes `next` at ^16.3.4, `notion-client` at ^8.0.8, `lqip-modern` at ^3.0.0 and `ky` at ^2.1.0. The scripts show a toolchain built on oxc: `test` runs `oxfmt --check`, `oxlint` and `tsc --noEmit` in parallel, and `fix` runs `oxfmt` and `oxlint --fix`. The `deps:update` script upgrades the notion packages and react-notion-x, and skips itself on CI. Because you fork a moving template, expect to merge upstream changes by hand.

## Conclusion

Use this kit if you want a personal site, blog or portfolio whose content lives in Notion and which you are content to deploy on Vercel. Skip it if your content cannot be a public Notion page or you need releases to pin against. Before you launch, turn off Vercel Authentication or social images will fail, and decide whether you will ever rename pages.

## FAQ

### What is NextJS and why is it used in nextjs-notion-starter-kit?

Here Next.js builds the pages of a website whose content is rendered from Notion by react-notion-x, and the result is hosted on Vercel. The package.json depends on next ^16.3.4.

### Is Next.js still relevant in 2026 for this starter kit?

The kit depends on next ^16.3.4 and its last push was 2026-10-18, so it is on a current Next.js line. It publishes no GitHub releases.

### Is Next.js free or paid when using nextjs-notion-starter-kit?

The starter kit itself is MIT licensed. Deployment uses Vercel through `vercel deploy`, so check your Vercel plan for hosting terms.

## Sources

- [Issues](https://github.com/transitive-bullshit/nextjs-notion-starter-kit/issues)
- [License: MIT](https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/LICENSE)
- [Project website](https://transitivebullsh.it/nextjs-notion-starter-kit)
- [README](https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/README.md)
- [transitive-bullshit/nextjs-notion-starter-kit on GitHub](https://github.com/transitive-bullshit/nextjs-notion-starter-kit)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/transitive-bullshit-nextjs-notion-starter-kit