Kickstart Next

If you want the fastest possible path from "new stack" to "working Next.js site with Contentstack", this is the one to start with.

The Next kickstart is a minimal Next.js app that already knows how to talk to Contentstack. It gives you a seeded stack, a working homepage, live preview, and Visual Builder support without making you build the plumbing first. That makes it a great starting point when you want to understand the integration before you design a larger architecture around it.

This page is a practical developer guide, not a replacement for the official docs. Use it to understand the shape of the project and why it works. Use the docs when you want the full setup steps and reference details.

Watch It First

If you prefer seeing the flow before reading through the project structure, this walkthrough is a good place to start:

What a kickstart is

A kickstart is the smallest useful project that connects a frontend framework to Contentstack. Think of it as a working baseline instead of a finished starter kit. It is intentionally light on abstraction so you can see the important pieces clearly:

how the SDK is initialized
how content is queried
how preview mode is enabled
how Visual Builder fields are mapped back into the page

For developers, that is the value: you are not reverse-engineering a large demo app. You are starting from a small codebase that is already wired correctly.

Why start with the Next kickstart

This kickstart is a good fit when you want to:

learn the core Contentstack-to-frontend flow in a familiar React setup
start from Next.js App Router instead of an older Pages Router example
give editors a better experience right away with Live Preview and Visual Builder
build on top of a simple content model before adding more content types and routes

It is especially useful for teams that want to prove the integration quickly before deciding whether they need a more specific variant like SSR, SSG, GraphQL, or middleware.

What you get out of the box

The current contentstack/kickstart-next repository is a lightweight Next.js app with:

Next.js App Router
the Contentstack Delivery SDK
Contentstack Live Preview utilities
Visual Builder field mapping
a seeded page content type with a sample homepage entry
modular blocks, rich text, and image rendering
simple Tailwind styling

In practice, that means you can seed a stack, add your API values, run the app, and immediately see a page that is driven by Contentstack content.

How this specific kickstart works

The codebase is intentionally small, so the main flow is easy to follow.

1. lib/contentstack.ts creates the connection

This file initializes the Delivery SDK using your stack API key, delivery token, preview token, region, and environment. It also sets up the Live Preview utility in builder mode.

That single file does most of the important integration work:

creates the stack client
enables preview when NEXT_PUBLIC_CONTENTSTACK_PREVIEW=true
configures region-aware endpoints
exposes a getPage(url) helper that fetches a page entry by its URL
adds editable tags in preview mode so Visual Builder can target the right fields

If you want to extend this kickstart later, this is the first file you will copy patterns from.

2. app/page.tsx loads the homepage

The homepage asks Contentstack for the entry whose URL is /.

When preview is off, the app fetches the page and renders it normally. When preview is on, it switches to the preview component so content authors can see changes reflected immediately.

3. components/Preview.tsx handles live updates

This is where the editing experience comes alive. The component initializes Live Preview on the client and listens for entry changes. When content changes in Contentstack, it re-fetches the page entry and updates the UI.

That makes this kickstart feel instant: edit content in Contentstack, and the local Next app updates without you having to rebuild anything.

4. components/Page.tsx renders the content model

The page renderer shows the content model in a very readable way:

a title
a description
a hero image
rich text
modular blocks with alternating image/text layouts

It also spreads the Visual Builder attributes onto the rendered fields, which is what makes click-to-edit overlays work inside the preview experience.

What you are really learning from this project

Even though the app is simple, it teaches a few important Contentstack patterns:

query by URL instead of hardcoding entry IDs into your page components
keep the SDK setup in one place
separate preview behavior from normal rendering
model flexible page sections with modular blocks
make fields editable in context instead of forcing editors back into form-only workflows

That is why this kickstart is more useful than a blank starter. It gives you a working pattern you can keep growing.

Fastest way to try it

There are two practical ways to get started:

Use csdx cm:bootstrap if you want the quickest guided path and want to choose the Next kickstart during setup.
Clone the repository directly if you want to inspect the code from the start and seed the stack yourself.

Either way, the flow is the same:

create or seed a stack
create a delivery token with preview enabled
add your stack values to .env
enable Live Preview for the same environment
run npm install and npm run dev

Once that is done, open the homepage locally and then open the matching entry in Contentstack. That is the moment this kickstart clicks: you can edit content in the CMS and watch the Next app react immediately.

When to use this one vs. another Next kickstart

Choose this kickstart when you want the cleanest baseline and the least amount of framework-specific complexity.

You may want a different Next variant if:

you need server-side rendering on every request
you want a static-generation pattern
you prefer GraphQL over the Delivery SDK
you need middleware-based request logic

This version is the best "learn the integration once" starting point. It is the easiest one to reason about before branching into the more specialized variants.

A good next step after the first run

After you get the homepage working, the best next move is not redesigning the UI right away. Start by extending the content model and repeating the same integration pattern:

add another content type such as blog_post or author
create a new query helper beside getPage
add a new route in the app
reuse the preview and editable-field approach

That keeps the project easy to understand while turning the kickstart into a real application.