Stackbit Setup for Next.js + Markdown

Begin the tutorial by setting up the Next.js example project that uses markdown files as the content source.

With your example project installed and running locally, let's begin the tutorial by installing Stackbit's local development environment.

This is a lesson within the Next.js + Markdown files tutorial. Following it requires running the example project locally on your machine.

How Content is Loaded

Stackbit's only real requirement is that content must be structured and separated from code. Learn more about content modeling basics in Stackbit.

While you craft your code however it best serves you, this project is uses a single composable page template. It works like this:

  1. Content is stored in markdown files in the content/pages directory (find the home page at content/pages/
  2. The content files are parsed by a set of utility functions in utils/content.js
  3. These utilities are used by an optional catch-all page template in pages/[[...slug]].jsx. This page template uses the structured content and maps it to the appropriate components in the components directory.
Content-Driven Development
Content-Driven Development

Configure Stackbit

Stackbit reads a configuration file in the root of your project directory. Add the stackbit.config.js file to your project with the minimal configuration for a Next.js site using files as the content source:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
export default {
  stackbitVersion: '~0.6.0',
  ssgName: 'nextjs',
  cmsName: 'git',
  pagesDir: 'content/pages',
  assets: {
    referenceType: 'static',
    staticDir: 'public',
    uploadDir: 'images',
    publicPath: '/',

If you see an ESLint warning in your code editor for import/no-anonymous-default-export, you can ignore it in this file by adding /* eslint-disable import/no-anonymous-default-export */ to the top of the file.

Also note that the configuration file can also be stackbit.config.ts for projects using TypeScript.

Local Development

We now have all we need inside the code to be able to run Stackbit's development server.

Install Stackbit CLI

Install the CLI, which provides the stackbit command used to run the local development server:

  • 1
npm install -g @stackbit/cli

Run Stackbit Dev

With your development server still running on port 3000, start the Stackbit dev server.

  • 1
stackbit dev

Both servers (Next.js and Stackbit) should now be running on your machine. Learn more about working modes.

Dev Servers Running in Parallel
Dev Servers Running in Parallel

Open the Visual Editor App

Stackbit dev outputs a URL unique to your user: Open the full URL in your browser and register or sign in.

After signing in, you should see your example project within the preview section of Stackbit's visual editor. (You won't be able to edit content just yet.)

Stackbit's Visual Editor
Stackbit's Visual Editor