How transitive-bullshit/nextjs-notion-starter-kit works
Project type and purpose
• This is a full-stack, content-driven website starter kit built with Next.js (React + TypeScript) that uses Notion as a headless CMS.
• It powers both static and dynamic pages (SSG, SSR, and serverless API routes) and is designed for deployment on Vercel.
File structure
• Top-level folders:
• components/ – shared React UI components (ErrorPage, NotionPage, Table of Contents, etc.)
• lib/ – service-layer utilities (Notion API client, image preview generator, sitemap, search, Redis cache, config)
• pages/ – Next.js routes:
◦ pages/[pageId].tsx – dynamic page rendering from Notion
◦ pages/api/ – serverless endpoints (search-notion, social-image)
◦ pages/_app, _document, _error – bootstrapping & error pages
• styles/ – global, Notion, syntax highlighting CSS
• site.config.ts – single config file controlling all site behavior
• .env.example & .github/workflows – deployment & build configurations
• Key config/build files: next.config.js, tsconfig.json, ESLint/Prettier, Vercel GitHub Action.
README for additional insights
• Describes architecture choices:
• Next.js + React for rendering
• react-notion-x for Notion content
• Vercel OG image generation for social images
• Optional Redis caching for preview images
• API end-points for search & OG image generation
• Highlights dynamic/static routing, preview images, dark mode, analytics, and environment variables.
Main components & relationships
a. Client (Browser/Mobile)
• Requests pages, triggers navigation (Next.js client router)
• Sends search queries (CMD+K) to /api/search-notion
• Fetches social images at /api/social-image?id=...
b. Next.js Application (Vercel Serverless)
• getStaticProps / getServerSideProps: fetch page data via lib/notion.ts + lib/get-canonical-page-id, build HTML/JSON
• React components (components/) render UI, assemble Notion blocks (react-notion-x)
• Serverless API functions in pages/api handle search & dynamic OG image generation
c. Notion API
• Source of truth for page content & metadata
• Accessed via lib/notion-api.ts using Notion SDK
d. Redis Cache (optional)
• Caches generated preview (low-quality placeholder) images to speed up builds
• Accessed via lib/preview-images.ts when isRedisEnabled
e. Vercel Edge / CDN
• Caches static assets (public/, autogenerated sitemap.xml, robots.txt, built pages)
• Edge function for OG image generation
f. External Services
• Fathom / PostHog (optional analytics)
• GitHub Actions for CI/CD (build + optional Redis env secrets)
Architectural patterns & design principles
• Separation of concerns: UI components vs. data-fetching libs vs. config
• Hybrid rendering: SSG for most pages, SSR/ISR for dynamic content, serverless API for specialized endpoints
• Single source of configuration (site.config.ts)
• Stateless serverless functions & CDN for scale
• Optional caching layer (Redis) to avoid re-fetching or re-processing heavy assets
Detail
• Every major lib in the data flow (preview-images, search-notion, map-page-url)
• Static asset pipeline (styles/, public/, Google Fonts bootstrap)
• Distinguish build-time (SSG, sitemap.xml) vs. runtime (SSR, API calls)