NotionNext: Publish a Notion Workspace as a Next.js Site

The problem NotionNext solves for Notion writers

Notion is a writing surface, not a publishing system. The README frames the gap directly: you keep managing posts, categories, tags, menus and pages inside Notion, and NotionNext is responsible for turning that content into a site that can be visited, searched and operated. The stated audience is people who accumulate content over time: writers, independent developers, designers, photographers, course authors, open source maintainers, and small teams that need a product site or knowledge base quickly.

The project's own comparison table maps goals to entry points. A personal blog points at the getting-started guide. A portfolio or personal brand site points at the theme catalog filtered by scenario. A product site or SaaS landing page points at the Starter, Landing and Proxio themes. A knowledge base points at GitBook and Claude. A link directory points at the Nav theme. That table is the honest summary of scope: NotionNext is a rendering and hosting layer, and the theme you pick decides what kind of site you actually get.

What it is not: a Notion replacement, a database product, or a general purpose CMS. The README states the data path plainly. Notion holds the content, the site handles display and distribution, and the README notes that content can later be migrated to Markdown or another system. That last point matters more than it looks. The lock-in is soft, because the source of truth stays in a tool you can export from.

How the Next.js and Notion API pipeline fits together

The stack listed in the README is Next.js for the framework, Tailwind CSS for styling, react-notion-x for rendering, and Vercel for deployment. Comments are handled by one of Twikoo, Giscus, Gitalk, Cusdis or Utterances. The repository layout matches that description: pages/ and components/ at the top level, a themes/ directory holding the theme implementations, a lib/ directory for shared logic, conf/ and blog.config.js for configuration, and a middleware.ts at the root.

Content flows from a Notion page ID into the build. The .env.example file lists NOTION_PAGE_ID as required, with a commented example value, and also shows API_BASE_URL defaulting to https://www.notion.so/api/v3. The Notion API is therefore the fetch layer, and react-notion-x turns the returned block tree into React components. Because the site is built rather than queried live on every request, the Notion API is touched during the build and during revalidation, not on each page view.

That build-time model shows up in the environment variables. The .env.example file exposes BUILD_PREFETCH_ENABLED, BUILD_PREFETCH_CONCURRENCY, NOTION_BUILD_RATE_MAX_PER_MINUTE, NOTION_BUILD_RATE_MIN_INTERVAL_MS, STATIC_PAGE_GENERATION_TIMEOUT and NOTION_BUILD_CACHE_PURGE_DATA. Those keys exist because a large Notion workspace means many API calls, and the project gives you knobs to throttle and cache them. There is also REVALIDATION_TOKEN, which the file says enables an immediate cache refresh through POST /api/revalidate once set. If you have ever wondered how a Notion-backed site stays current without a rebuild, that endpoint is the answer the repository provides.

Installing NotionNext locally with Node 22 and Yarn

The README is explicit about the toolchain: Node 22 and Yarn 1 are recommended, and Node 20 can no longer install the current dependencies because @ai-sdk/google requires Node >=22. The package.json engines field states node >=22 <25, so Node 24 is inside the supported range and Node 20 is outside it. Deployment platforms need the same Node 22 setting, according to the README.

The local setup sequence is short. The first block below switches to the pinned Node version and installs Yarn globally, then installs dependencies and starts the development server. Run these from the repository root after forking or cloning it.

nvm use || nvm install
npm i -g yarn
yarn
yarn dev

After yarn dev, Next.js starts a development server and you should see the site at the local address Next prints in the terminal. The README lists the other common commands in a table: yarn build for a production build, yarn export for static export, yarn docs:site:dev to preview the documentation site locally, and yarn docs:site:build to build it.

Configuration happens through environment variables. Copy .env.example to .env.local and uncomment the keys you need. The only mandatory one is the Notion page ID.

# .env.local
NOTION_PAGE_ID=097e5f674880459d8e1b4407758dc4fb
NEXT_PUBLIC_THEME=matery

The value shown for NOTION_PAGE_ID is the commented example that appears in .env.example; replace it with the ID of your own Notion page. NEXT_PUBLIC_THEME selects the theme, and the example file uses matery as its sample value. Everything else in that file, from contact links to fonts to Prism syntax highlighting paths, is optional and commented out by default.

For a container-based run, the repository includes a Dockerfile. It is a three-stage build on node:22-alpine, installs dependencies with yarn install --frozen-lockfile, runs yarn build with NEXT_BUILD_STANDALONE=true, copies the standalone output, exposes port 3000, and starts the server with node server.js.

FROM node:22-alpine AS base
WORKDIR /app
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile --network-timeout 600000

The Dockerfile takes NOTION_PAGE_ID and NEXT_PUBLIC_THEME as build arguments, and a comment in the runner stage notes that placing a configured .env.local in the project root lets the container pick up environment variables automatically.

Where NotionNext stops being the right tool

The clearest constraint is the hard dependency on the Notion API. If Notion changes its API, rate-limits your workspace, or your page structure stops mapping cleanly to a site, NotionNext has no fallback content source. The .env.example shows API_BASE_URL pointing at Notion's v3 endpoint, and there is no second provider in the repository. Teams that need a CMS they fully control should treat this as a dealbreaker rather than a caveat.

Build cost is the second constraint. The presence of NOTION_BUILD_RATE_MAX_PER_MINUTE, NOTION_BUILD_RATE_MIN_INTERVAL_MS and STATIC_PAGE_GENERATION_TIMEOUT in the environment file tells you the maintainers expect builds to be throttled. A workspace with thousands of blocks will not build instantly, and the throttling knobs exist to keep you inside rate limits rather than to make the build fast. If your publishing cadence is several times an hour, the revalidation endpoint matters more than the build settings, and the README does not document rollback behaviour for a failed revalidation.

The theme count cuts both ways. Twenty-six built-in themes is a lot of surface area, and the README's own scenario table implies you should pick by goal rather than browse. A theme that matches your goal may still not match your layout expectations, and the README does not describe a theme migration path once you have customized one. Finally, this is a site generator, not an application framework. If you need authentication, user accounts or dynamic server logic, nothing in the README suggests NotionNext provides it.

NotionNext compared with Elog's export approach

The README lists one related project: Elog, described as a Markdown batch export tool that combines writing platforms such as Notion, Yuque, FlowUs and Feishu with blog platforms such as Hexo, VitePress, Halo and WordPress. The difference in approach is structural rather than cosmetic.

NotionNext reads from the Notion API at build time and renders through react-notion-x, so your content stays in Notion and the site is a view over it. Elog exports Markdown files and hands them to a separate static site generator. With Elog, the output is portable Markdown that any of the listed blog platforms can consume, and the Notion connection is a one-way export step rather than a runtime dependency. With NotionNext, you get a single integrated system with themes and a deployment path, at the cost of staying coupled to Notion's API.

If your priority is owning the content as files, the export route is the more conservative choice. If your priority is keeping Notion as the editing surface and not managing a content pipeline, NotionNext is the shorter path. Neither is strictly better; they optimize for different failure modes.

Licence, maintenance and the cost of upgrading

NotionNext is MIT licensed, and package.json carries the same identifier. MIT permits commercial and private use, modification and redistribution with the licence and copyright notice preserved. That is a permissive starting point, but the README's usage statement adds a project-level restriction: the project describes itself as a free, public resource for personal study and lawful site building, and prohibits using it to publish illegal content or conduct illegal activity. Those two statements sit at different levels, and if you plan to run a commercial site on it, read both the LICENSE file and that statement rather than assuming MIT alone settles the question. This is not legal advice.

The repository is not archived, and the last push was on 2026-08-13, which is recent relative to the current date. Release v4.10.10 carries the same timestamp, with v4.10.9 on 2026-08-10 and v4.10.8 on 2026-07-22. The release cadence visible in the repository is therefore measured in days to weeks, not months, and the version in package.json matches the latest release tag.

Upgrade cost is mostly dependency cost. The engines field pins Node to >=22 <25, and the README states that Node 20 can no longer install current dependencies. That means an upgrade can force a Node version bump on your build platform, not just a dependency refresh. The repository provides yarn deps:check-lockfile, which runs yarn install --frozen-lockfile and then git diff --exit-code on yarn.lock, plus a quality script and a pre-commit hook chaining lint:fix, format and type-check. Those exist so you can verify a dependency bump before it reaches a deploy. The README also notes that the main repository moved to the notionnext-org GitHub organization and gives a git remote set-url command for clones made from the old address.

Editorial conclusion

Adopt NotionNext if you already write in Notion and want a Next.js site you can fork and deploy to Vercel without running a server, and if your toolchain can move to Node 22. Do not adopt it if you need a CMS independent of Notion's API, or if you want a plugin ecosystem rather than a theme picker. Before committing, check that your Notion page ID resolves, that the theme you want appears in the repository's theme catalog, and that your Node version satisfies the engines field.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes