mirror of
https://github.com/d0zingcat/nextjs-notion-starter-kit.git
synced 2026-05-13 23:16:47 +00:00
186 lines
10 KiB
Markdown
186 lines
10 KiB
Markdown
<p align="center">
|
||
<a href="https://transitivebullsh.it/nextjs-notion-starter-kit">
|
||
<img alt="Example article page" src="https://user-images.githubusercontent.com/552829/160132094-12875e09-41ec-450a-80fc-ae8cd488129d.jpg" width="689">
|
||
</a>
|
||
</p>
|
||
|
||
# Next.js Notion Starter Kit
|
||
|
||
> The perfect starter kit for building websites with Next.js and Notion.
|
||
|
||
[](https://github.com/transitive-bullshit/nextjs-notion-starter-kit/actions/workflows/build.yml) [](https://prettier.io)
|
||
|
||
## Intro
|
||
|
||
This repo is what I use to power my personal blog and portfolio site [transitivebullsh.it](https://transitivebullsh.it).
|
||
|
||
It uses Notion as a CMS, [react-notion-x](https://github.com/NotionX/react-notion-x), [Next.js](https://nextjs.org/), and [Vercel](http://vercel.com).
|
||
|
||
## Features
|
||
|
||
- Setup only takes a few minutes ([single config file](./site.config.js)) 💪
|
||
- Robust support for Notion content via [react-notion-x](https://github.com/NotionX/react-notion-x)
|
||
- Next.js / TS / React / Notion
|
||
- Excellent page speeds
|
||
- Smooth image previews
|
||
- Automatic pretty URLs
|
||
- Automatic table of contents
|
||
- Full support for dark mode
|
||
- Quick search via CMD+K / CMD+P
|
||
- Responsive for different devices
|
||
- Optimized for Next.js and Vercel
|
||
|
||
## Demos
|
||
|
||
- [Default demo](https://nextjs-notion-starter-kit.transitivebullsh.it) - Deployed from the `main` branch
|
||
- [My site](https://transitivebullsh.it) - Deployed from the `transitive-bullshit` branch
|
||
|
||
## Setup
|
||
|
||
**All config is defined in [site.config.js](./site.config.js).**
|
||
|
||
This project requires a recent version of Node.js (>= 14.17).
|
||
|
||
1. Fork / clone this repo
|
||
2. Change a few values in [site.config.js](./site.config.js)
|
||
3. `npm install`
|
||
4. `npm run dev` to test locally
|
||
5. `npm run deploy` to deploy to vercel 💪
|
||
|
||
I tried to make configuration as easy as possible.
|
||
|
||
All you really need to do to get started is edit `rootNotionPageId`. It defaults to rendering my site's public notion page [78fc5a4b88d74b0e824e29407e9f1ec1](https://notion.so/78fc5a4b88d74b0e824e29407e9f1ec1).
|
||
|
||
You'll want to make your root Notion page **public** and then copy the link to your clipboard. Then extract the last part of the URL that looks like `d1b5dcf8b9ff425b8aef5ce6f0730202`, which is your page's Notion iD.
|
||
|
||
In order to find your Notion workspace ID (optional), just load any of your site's pages into your browser and open up the developer console. There will be a global variable that you can access called `block` which is the Notion data for the current page. If you enter `block.space_id`, it will print out your page's workspace ID.
|
||
|
||
I recommend setting up a collection on your home page (optional; I use an inline gallery [here](https://notion.so/78fc5a4b88d74b0e824e29407e9f1ec1)) that contains all of your articles / projects / content. There are no structural constraints on your Notion workspace, however, so feel free to add content as you would normally in Notion.
|
||
|
||
## Production setup
|
||
|
||
When deploying to Vercel, you'll need to set up a few things.
|
||
|
||
### Vercel environment variables
|
||
|
||
Vercel is not aware of the environment variables defined in the `.env` file.
|
||
|
||
Therefore, those variable must be defined in Vercel, too. Once defined, they'll be available on the next builds.
|
||
See [their documentation](https://vercel.com/docs/concepts/projects/environment-variables) for more details.
|
||
|
||
## URL Paths
|
||
|
||
The app defaults to slightly different URL paths in dev vs prod (though pasting any dev pathname into prod will work and vice-versa).
|
||
|
||
In development, it will use `/nextjs-notion-blog-d1b5dcf8b9ff425b8aef5ce6f0730202` which is a slugified version of the page's title suffixed with its Notion ID. I've found that it's really useful to always have the Notion Page ID front and center during local development.
|
||
|
||
In production, it will use `/nextjs-notion-blog` which is a bit nicer as it gets rid of the extra ID clutter.
|
||
|
||
The mapping of Notion ID to slugified page titles is done automatically as part of the build process. Just keep in mind that if you plan on changing page titles over time, you probably want to make sure old links will still work, and we don't currently provide a solution for detecting old links aside from Next.js's built-in [support for redirects](https://nextjs.org/docs/api-reference/next.config.js/redirects).
|
||
|
||
See [mapPageUrl](./lib/map-page-url.ts) and [getCanonicalPageId](https://github.com/NotionX/react-notion-x/blob/master/packages/notion-utils/src/get-canonical-page-id.ts) for more details.
|
||
|
||
NOTE: if you have multiple pages in your workspace with the same slugified name, the app will throw an error letting you know that there are duplicate URL pathnames.
|
||
|
||
## Preview Images
|
||
|
||
<p align="center">
|
||
<img alt="Example preview image" src="https://user-images.githubusercontent.com/552829/160142320-35343317-aa9e-4710-bcf7-67e5cdec586d.gif" width="458">
|
||
</p>
|
||
|
||
We use [next/image](https://nextjs.org/docs/api-reference/next/image) to serve images efficiently, with preview images optionally generated via [lqip-modern](https://github.com/transitive-bullshit/lqip-modern). This gives us extremely optimized image support for sexy smooth images.
|
||
|
||
Preview images are **enabled by default**, but they can be slow to generate, so if you want to disable them, set `isPreviewImageSupportEnabled` to `false` in `site.config.js`.
|
||
|
||
If you want to cache generated preview images to speed up subsequent builds, you'll need to first set up an external [Redis](https://redis.io) data store. To enable redis caching, set `isRedisEnabled` to `true` in `site.config.js` and then set `REDIS_HOST` and `REDIS_PASSWORD` environment variables to point to your redis instance.
|
||
|
||
You can do this locally by adding a `.env` file:
|
||
|
||
```bash
|
||
REDIS_HOST='TODO'
|
||
REDIS_PASSWORD='TODO'
|
||
```
|
||
|
||
Note that preview images and redis caching are both optional features. If you’d rather not deal with them, just disable them in your site config.
|
||
|
||
### Configuring GitHub Actions
|
||
|
||
By default, the workflow "[Build](https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/.github/workflows/build.yml)" runs when commits are pushed to the repository.
|
||
|
||
If you have defined a Redis instance, you will need to slightly change the configuration, for GitHub Actions to be aware of those environment variables.
|
||
[Here is an example](https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/transitive-bullshit/.github/workflows/build.yml#L17-L21)
|
||
|
||
Additionally, you'll need to configure the [GitHub secrets](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-codespaces) for `REDIS_HOST` and `REDIS_PASSWORD`.
|
||
|
||
### Redis provider
|
||
|
||
If you want to use redis caching, you can use [Redis Labs](https://app.redislabs.com/), which provides a free plan.
|
||
|
||
## Styles
|
||
|
||
All CSS styles that customize Notion content are located in [styles/notion.css](./styles/notion.css). They mainly target global CSS classes exported by react-notion-x [styles.css](https://github.com/NotionX/react-notion-x/blob/master/packages/react-notion-x/src/styles.css).
|
||
|
||
Every notion block gets its own unique classname, so you can target individual blocks like this:
|
||
|
||
```css
|
||
.notion-block-260baa77f1e1428b97fb14ac99c7c385 {
|
||
display: none;
|
||
}
|
||
```
|
||
|
||
## Dark Mode
|
||
|
||
<p align="center">
|
||
<img alt="Light Mode" src="https://transitive-bs.notion.site/image/https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fsecure.notion-static.com%2F83ea9f0f-4761-4c0b-b53e-1913627975fc%2Ftransitivebullsh.it_-opt.jpg?table=block&id=ed7e8f60-c6d1-449e-840b-5c7762505c44&spaceId=fde5ac74-eea3-4527-8f00-4482710e1af3&width=2000&userId=&cache=v2" width="45%">
|
||
|
||
<img alt="Dark Mode" src="https://transitive-bs.notion.site/image/https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fsecure.notion-static.com%2Fc0839d6c-7141-48df-8afd-69b27fed84aa%2Ftransitivebullsh.it__(1)-opt.jpg?table=block&id=23b11fe5-d6df-422d-9674-39cf7f547523&spaceId=fde5ac74-eea3-4527-8f00-4482710e1af3&width=2000&userId=&cache=v2" width="45%">
|
||
</p>
|
||
|
||
Dark mode is fully supported and can be toggled via the sun / moon icon in the footer.
|
||
|
||
## Automatic Table of Contents
|
||
|
||
<p align="center">
|
||
<img alt="Smooth ToC Scrollspy" src="https://www.notion.so/image/https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fsecure.notion-static.com%2Fcb2df62d-9028-440b-964b-117711450921%2Ftoc2.gif?table=block&id=d7e9951b-289c-4ff2-8b82-b0a61fe260b1&cache=v2" width="240">
|
||
</p>
|
||
|
||
By default, every article page will have a table of contents displayed as an `aside` on desktop. It uses **scrollspy** logic to automatically update the current section as the user scrolls through your document, and makes it really easy to jump between different sections.
|
||
|
||
If a page has less than `minTableOfContentsItems` (default 3), the table of contents will be hidden. It is also hidden on the index page and if the browser window is too small.
|
||
|
||
This table of contents uses the same logic that Notion uses for its built-in Table of Contents block (see [getPageTableOfContents](https://github.com/NotionX/react-notion-x/blob/master/packages/notion-utils/src/get-page-table-of-contents.ts) for the underlying logic).
|
||
|
||
## Responsive
|
||
|
||
<p align="center">
|
||
<img alt="Mobile article page" src="https://user-images.githubusercontent.com/552829/160132983-c2dd5830-80b3-4a0e-a8f1-abab5dbeed11.jpg" width="300">
|
||
</p>
|
||
|
||
All pages are designed to be responsive across common device sizes.
|
||
|
||
## Fathom Analytics
|
||
|
||
[Fathom](https://usefathom.com/ref/42TFOZ) provides a lightweight alternative to Google Analytics.
|
||
|
||
To enable analytics, just add a `NEXT_PUBLIC_FATHOM_ID` environment variable, which will only be used in production.
|
||
|
||
Note that this feature is completely optional.
|
||
|
||
## PostHog Analytics
|
||
|
||
[PostHog](https://posthog.com/) provides a lightweight **and open source** alternative to Google Analytics.
|
||
|
||
To enable analytics, just add a `NEXT_PUBLIC_POSTHOG_ID` environment variable, which will only be used in production.
|
||
|
||
Note that this feature is completely optional.
|
||
|
||
## Contributing
|
||
|
||
See the [contribution guide](contributing.md) and join our amazing list of [contributors](https://github.com/transitive-bullshit/nextjs-notion-starter-kit/graphs/contributors)!
|
||
|
||
## License
|
||
|
||
MIT © [Travis Fischer](https://transitivebullsh.it)
|
||
|
||
Support my open source work by <a href="https://twitter.com/transitive_bs">following me on twitter <img src="https://storage.googleapis.com/saasify-assets/twitter-logo.svg" alt="twitter" height="24px" align="center"></a>
|