A fully-functional, drop-in proof-of-concept Next.js app using ButterCMS

This Next.js starter project fully integrates with dynamic sample content from your ButterCMS account, including main menu, pages, blog posts, categories, and tags, all with a beautiful, custom theme with already-implemented search functionality. All of the included sample content is automatically created in your account dashboard when you sign up for a free trial of ButterCMS.

A copy of this starter project can be easily and quickly deployed to Vercel with the click of a button.

This example showcases Next.js's Static Generation feature using ButterCMS as the data source.

Demo

Check out our live demo: https://nextjs-starter-buttercms.vercel.app/

Deploy your own

Once you have access to your Butter API token, you can deploy your Butterized proof-of-concept app to Vercel, the creators of Next.js, and spread your love of Butter. By clicking the button below, you'll create a copy of our starter project in your Git provider account, instantly deploy it, and institute a full content workflow connected to your ButterCMS account. Smooth.

Related examples

How to use

Option 1. Install via Github and NPM or Yarn

First, install the dependencies by cloning the repo and running one of the following commands, depending on your current setup:

git clone https://github.com/ButterCMS/nextjs-starter-buttercms.git
cd nextjs-starter-buttercms
npm install # or yarn install

Option 2. Install via Create-Next-App

Execute create-next-app with npm, Yarn, or pnpm to bootstrap the example:

npx create-next-app --example cms-buttercms cms-buttercms-app

yarn create next-app --example cms-buttercms cms-buttercms-app

pnpm create next-app --example cms-buttercms cms-buttercms-app

Configuration

Step 1. Create an account on ButterCMS

First, create an account on ButterCMS.

After signing up, you’ll be presented with your free API token. We’ll use this in the next step.

Step 2. Set up environment variables

Copy the .env.local.example file in this directory to .env.local (which will be ignored by Git):

cp .env.local.example .env.local

Then set each variable on .env.local:

NEXT_PUBLIC_BUTTER_CMS_API_KEY should be set as the API key.

Step 3. Run Next.js in development mode

When you sign up for ButterCMS, it creates all of the example content used by this starter project. You can run Next.js in development mode to view your fully-functional starter project, including landing page with API-based components, API-based menu, and a blog.

npm install
npm run dev

# or

yarn install
yarn dev

Your starter project should be up and running on http://localhost:3000! If it doesn't work, post on GitHub discussions.

Step 4. Try preview mode

Your starter project is automatically configured to show draft changes saved in your Butter account when run locally or deploy to a hosting provider. To disable this behavior, set the following value in your .env.local file: PREVIEW=false.

To try preview mode, create a blog post:

Set the Title as Draft Post Test.
Fill the content and summary with dummy text.

Most importantly, do not publish the blog post. Instead, click Save Draft.

If you have not already, set PREVIEW=false in your .env.local file and restart your local development server.

Now, if you go to the your blog list view page on localhost: http://localhost:3000/#blog, you won't see this post, as its status has not yet been updated to published. However, if you use Preview Mode by deleting PREVIEW=false from your .env.local file, your new post will appear (Documentation).

Tip: You can set a preview URL on ButterCMS for pages deployed to Vercel, allowing you to live-preview changes on the web from within your Butter account! Sweet!

Step 5. Deploy on Vercel

You can deploy this app to the cloud with Vercel (Documentation).

Deploy from our template

If you want to deploy a copy of our starter to Vercel without any changes, you can just click this button:

Deploy your local project

To deploy your local project to Vercel (one in which you've made changes), push it to GitHub/GitLab/Bitbucket and import to Vercel.

Important: When you import your project on Vercel, make sure to click on Environment Variables and set them to match your .env.local file.