---
title: "Your first Contentstack site"
url: "https://developers.contentstack.com/paths/your-first-contentstack-site"
type: "path_full"
level: "beginner"
outcome: "A Contentstack stack with a Next.js starter running locally and Live Preview working"
steps:
  - "https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/what-contentstack-is-and-why-veda-is-a-good-starting-point"
  - "https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/core-contentstack-concepts"
  - "https://developers.contentstack.com/guides/modular-blocks-references-or-global-fields"
  - "https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/account-region-cli-and-stack-setup"
  - "https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/running-kickstart-veda-locally"
  - "https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/how-veda-is-structured"
  - "https://developers.contentstack.com/kickstarts/kickstart-next"
  - "https://developers.contentstack.com/livestreams/tour-de-live-preview"
updated: "2026-11-15T11:47:36.502Z"
---

# Your first Contentstack site

- **Level:** Beginner
- **Steps:** 8
- **Overview:** https://developers.contentstack.com/paths/your-first-contentstack-site.md

---

For developers new to Contentstack. Learn the core model, set up a stack, run a real starter, and see Live Preview in action.

**You'll end up with:** A Contentstack stack with a Next.js starter running locally and Live Preview working

## Table of Contents

1. What Contentstack is and why Veda is a good starting point
2. Core Contentstack Concepts
3. Modular blocks, references or global fields?
4. Account, Region, CLI, and Stack Setup
5. Running Kickstart Veda Locally
6. How Veda Is Structured
7. Kickstart Next
8. Tour de Live Preview


---

## Step 1: What Contentstack is and why Veda is a good starting point

- **Source:** https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/what-contentstack-is-and-why-veda-is-a-good-starting-point
- **Checkpoint:** You know what a headless CMS does and why Veda is a good starter

- **Authors:** Tim Benniks, Lo Etheridge
- **Published:** 2026-04-07T09:27:48.691Z
- **Updated:** 2026-11-10T16:27:14.191Z
- **Level:** Beginner
- **Intent:** Learn

---

If you are new to Contentstack, the fastest way to get lost is to start by memorizing SDK calls before you understand the shape of the platform. This chapter keeps the focus on the platform itself first, then closes with a short explanation of why Veda is a useful example for the rest of the guide.

## What you'll learn

- What Contentstack actually is in day-to-day development terms
- What "headless CMS" means once code, content, and deployment are involved
- Why good platform vocabulary matters before setup and code
- Why Veda is more useful than a toy starter when you want to learn real patterns

## Contentstack in practical terms

Contentstack concept: Contentstack is a headless CMS. That means content management and content delivery are separated from the frontend that renders the experience.

In practical terms, your editors work in the Contentstack UI. They define structured content such as pages, product lines, categories, or articles. Your application then fetches that structured content over APIs and renders it however you want.

This is different from a traditional CMS where the backend often owns both the content model and the presentation layer. In Contentstack, your React, Next.js, Nuxt, native app, or middleware layer stays in control of presentation.

That separation gives you a few very concrete benefits:

- Your frontend can evolve independently from the editorial interface
- Content can be reused across multiple channels
- Developers can model content as structured data instead of unstructured page blobs
- Editors can work without asking developers to hardcode every content change

## What "headless" means once a project becomes real

Contentstack concept: "Headless" does not mean "simpler." It means the responsibilities are split differently.

You still need to answer the same real-world questions:

- What content types exist?
- Which content types link to each other?
- How should URLs map to entries?
- Which API serves published content?
- Which API serves draft content for preview?
- How do you make editing safe without exposing admin credentials?

Those are not abstract architecture questions. They become file structure, query logic, deployment rules, preview behavior, and debugging checklists.

That is why a good learning example matters so much. A minimal starter can show you one happy-path query. It usually cannot show you how a larger content model behaves once routing, metadata, filtering, preview, and reusable blocks all show up together.

## Why platform vocabulary comes before setup

Production note: Many early Contentstack problems are not caused by syntax errors. They usually come from mixing up concepts:

- using the wrong token for the wrong job
- misunderstanding what an environment means
- assuming preview behaves like production delivery
- treating modular blocks like arbitrary JSON instead of structured content

Those mistakes do not stay theoretical. They become broken preview flows, confusing route bugs, and fragile fetch helpers.

That is why this guide starts with mental models, then moves into stack setup, local development, content modeling, and code structure. Once the platform ideas are clear, the implementation chapters become much easier to reason about.

## Why Veda is a good example after the fundamentals

Veda implementation: Kickstart Veda is a strong teaching example because it is realistic enough to surface the questions that small demos usually hide.

It includes:

- multiple content types instead of one sample page
- route-driven fetching instead of one hardcoded entry
- modular blocks for flexible page composition
- preview support that behaves like a real editing mode
- production-minded helpers and structure instead of only SDK setup

That makes Veda useful for learning architecture, not only integration.

Veda is still just the example project for this guide. The goal is to understand the Contentstack and frontend patterns well enough to recognize which parts are portable and which parts are specific to this starter.

## Key takeaways

- Contentstack separates content management from presentation, but it does not remove architectural decisions
- A headless CMS becomes most useful when you model content as structured data and keep rendering logic in your application
- Clear platform vocabulary prevents a lot of setup and preview confusion later
- Veda is a strong learning example because it shows multiple content types, multiple routes, preview support, and production-minded patterns together
- Understanding the platform vocabulary first will make the implementation chapters much easier to follow



---

## Frequently asked questions

### What is Contentstack in day-to-day development terms?

Contentstack is a headless CMS where editors manage structured content in the UI and applications fetch it via APIs to render experiences in any frontend.

### What does “headless CMS” mean in a real project?

It means responsibilities are split: content modeling and delivery are separate from presentation. You still need to define content types, relationships, routing, preview, and deployment behavior.

### Why does platform vocabulary matter before setup and coding?

Many early issues come from mixing up concepts like tokens, environments, preview vs delivery APIs, and modular blocks. Clear vocabulary prevents broken preview flows and fragile fetch logic.

### Why is Veda a better learning example than a minimal starter?

Veda includes multiple content types, route-driven fetching, modular blocks, realistic preview support, and production-minded structure, so it surfaces real architectural patterns.

### Does headless mean simpler than a traditional CMS?

No. Headless changes the split of responsibilities rather than removing them, so architectural decisions still show up in file structure, routing, queries, and preview workflows.



---

## Chapter Navigation

**← Previous:** [Contentstack 0 to 100 for developers](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers)

**Next →:** [Core Contentstack Concepts](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/core-contentstack-concepts)

---

## Step 2: Core Contentstack Concepts

- **Source:** https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/core-contentstack-concepts
- **Checkpoint:** You can explain stacks, content types, entries, environments and the delivery vs preview APIs

- **Authors:** Tim Benniks, Lo Etheridge
- **Published:** 2026-04-07T09:46:57.497Z
- **Updated:** 2026-11-10T16:27:11.093Z
- **Level:** Beginner
- **Intent:** Learn

---

Before you seed a stack or open the Veda repo, you need a reliable vocabulary. Contentstack becomes much easier once you know which objects exist, what they are responsible for, and which API is supposed to touch them.

## What you'll learn

- The meaning of stack, content type, entry, asset, environment, and locale
- The difference between Delivery API, Preview API, and Management API
- How references and modular blocks shape real content models
- Where beginners usually get confused
- Which concepts are portable across projects and which ones are Veda-specific

## The object model you should keep in your head

### Stack

Contentstack concept: A stack is the top-level container for your project inside Contentstack.

A stack contains things like:

- content types
- entries
- assets
- environments
- tokens
- Live Preview configuration


If you are coming from databases, you can think of a stack as the broad project boundary. If you are coming from GitHub, think "repository plus configuration plus data," not just a single file tree.

### Content types

Contentstack concept: A content type is the schema for a kind of content.

Examples:

- page
- product
- category
- header

A content type defines fields such as title, description, URL, references, media, modular blocks, and validation rules.

This is one of the most important shifts in Contentstack. You do not start by designing pages. You start by designing content shapes.

### Entries

Contentstack concept: An entry is one actual item of content that follows a content type.

If product is the content type, one ring or necklace is an entry. If page is the content type, your homepage is one entry and your about page is another.


### Assets

Contentstack concept: Assets are files stored in Contentstack, such as images, videos, and documents.

They are delivered over Contentstack's CDN and can be referenced from entries. In a project like Veda, many visual experiences depend on asset URLs being part of the structured content rather than hardcoded in the frontend.

### Environments

Contentstack concept: Environments represent stages of content delivery such as development, staging, or production.

The important thing to remember is that environments matter for published delivery. An editor can save drafts at any time, but publication targets an environment.

### Locales

Contentstack concept: Locales represent language or regional variants such as en-us or fr-fr.

You do not need multiple locales to learn Veda, but once you understand Contentstack well, locales become part of how the same content model can serve multiple audiences.

## The three API modes that matter

This is where many first-time users get tripped up.

### Delivery API

Contentstack concept: The Delivery API is for reading published content.

Use it when:

- your public site is rendering live content
- you want stable, cacheable responses
- you are reading from a specific environment

### Preview API

Contentstack concept: The Preview API is for reading draft or unpublished content during preview workflows.

Use it when:

- editors need to see draft changes
- Live Preview is active
- your app needs to reflect unpublished changes safely

### Management API

Contentstack concept: The Management API is for creating, updating, deleting, and publishing content.

Use it when:

- you are writing automation scripts
- building import/export tools
- handling server-side content administration workflows

Production note: Never expose Management API credentials in a frontend application. Delivery and preview flows are one thing. Administrative write access is another.

## References: how entries connect to each other

Contentstack concept: References let one entry link to another entry.

This is how a project stops feeling like isolated pages and starts feeling like a content system.

For example, a product line might reference products. A header entry might reference navigation structures. A page might reference blocks, assets, or related content.

In Veda, references are part of what makes the project more realistic. Instead of fetching one flat page payload, the app often pulls connected content with deeper include settings because the site is modeling real relationships.

## Modular blocks: how editors compose pages without hardcoding layouts

Contentstack concept: Modular blocks let editors assemble a page from reusable content sections.

Examples from Veda include:

- hero
- list
- two column
- media
- rich text

This is a major strength of Contentstack when used well. Developers define the available block types and how they render. Editors decide which blocks to use and in what order.

That gives you a clean contract:

- developers own the rendering components
- editors own page composition within those allowed patterns

## Where beginners usually get confused

### Confusion 1: "Entry" versus "page"

Not every entry is a page. Some entries are pages, some are products, some are navigation data, and some are reusable supporting content.

### Confusion 2: "Preview" versus "published"

Preview is not just "the same content but earlier." It is a different delivery mode with different credentials and different expectations.

### Confusion 3: "Content type" versus "component"

A React component is not a content type. A modular block definition inside Contentstack is also not the same thing as a frontend component, even though the two are related.

The content model decides what data is available. The frontend decides how that data is rendered.

### Confusion 4: "Environment" versus "region"

An environment is a content lifecycle stage inside a stack. A region is the physical or cloud location where your stack and endpoints live. Those are separate concerns.

## What is portable beyond Veda

Contentstack concept: Everything in this chapter is portable.

The details of Veda will change:

- content type names
- component names
- route patterns
- visual style

But the core model stays the same:

- stacks contain schemas and content
- content types define structure
- entries hold actual content
- assets hold files
- environments and locales shape delivery
- references and modular blocks enable richer composition
- different APIs exist for different jobs

## Key takeaways

- Contentstack works best when you think in structured content, not only pages
- A stack is the project boundary; content types define structure; entries hold data
- Delivery, Preview, and Management APIs serve different jobs and should not be mixed casually
- References connect content types into a system
- Modular blocks are the bridge between editorial flexibility and developer-controlled rendering



---

## Frequently asked questions

### What is a stack in Contentstack?

A stack is the top-level container for a project in Contentstack. It holds content types, entries, assets, environments, tokens, and related configuration.

### What is the difference between a content type and an entry?

A content type is the schema (field structure and validation) for a kind of content. An entry is one instance of content that follows that schema.

### When should I use the Delivery API vs the Preview API?

Use the Delivery API to read published content from a specific environment with stable, cacheable responses. Use the Preview API to read draft or unpublished content for preview workflows such as Live Preview.

### What is the Management API used for in Contentstack?

The Management API is used to create, update, delete, and publish content. It is intended for automation and administrative workflows and should not be exposed in frontend apps.

### How do references and modular blocks affect content modeling?

References connect entries to other entries to model relationships. Modular blocks let editors compose pages from predefined, reusable section types while developers control how each block renders.



---

## Chapter Navigation

**← Previous:** [What Contentstack is and why Veda is a good starting point](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/what-contentstack-is-and-why-veda-is-a-good-starting-point)

**Next →:** [Account, Region, CLI, and Stack Setup](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/account-region-cli-and-stack-setup)

---

## Step 3: Modular blocks, references or global fields?

- **Source:** https://developers.contentstack.com/guides/modular-blocks-references-or-global-fields
- **Checkpoint:** You can choose between modular blocks, references and global fields for a new content type

- **Authors:** Tim Benniks
- **Published:** 2026-11-20T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:09.205Z
- **Level:** Beginner
- **Intent:** Learn
- **Tags:** content_modeling, headless

---

Every Contentstack content model comes down to a few choices repeated many times. Should this be a set of blocks inside the entry, a link to another entry, a reusable group of fields, or a label from a taxonomy? Each option changes how editors work, how many requests your front end makes, and what happens when someone publishes or translates.

This guide explains each option, compares them on the things that matter in production, and walks through three examples you will run into on almost every project.

## What you'll learn

- What modular blocks, references, global fields and taxonomies are


- Who owns the content in each case, and what gets reused


- How each option affects querying, localization and publishing


- How to model a landing page, a blog post with an author, and a product with shared SEO fields


- A decision table and flow you can use in modeling sessions



## The four options

### Modular blocks

Contentstack concept: A modular blocks field holds an ordered list of blocks. Each block follows one of the block types you define on the field.

A sections field on a landing page might allow hero, feature_grid, quote and cta blocks. Editors add the blocks they need, in the order they want. The content of every block is stored inside the entry.

If you are coming from page builders, modular blocks are the sections list. The developer defines which sections exist and how they render. The editor decides which ones to use.

### References

Contentstack concept: A reference field links an entry to one or more other entries, of the content types you allow.

A blog post with an author reference points at an entry of the person content type. The author is written once and reused by every post that references it. Change the author's bio and every post shows the new bio.

### Global fields

Contentstack concept: A global field is a reusable group of fields, defined once at the stack level and added to any content type.

An seo global field with meta_title, meta_description and canonical_url can be added to pages, blog posts and products. Change the global field's schema and every content type that uses it gets the change.

### Taxonomies

Contentstack concept: A taxonomy is a stack-level tree of terms that you attach to content types. Entries store the terms editors select.

Taxonomies are the fourth option, for classification. Levels, regions, product categories and topics are labels you filter by, not content you render. The [taxonomy querying guide](/guides/querying-content-by-taxonomy) covers how to query them.

## Ownership and reuse

The most useful question in a modeling session is: who owns this content, and where else does it appear?

- Modular blocks belong to one entry. A hero block on the homepage is the homepage's hero. If you copy it to another page, you have two heroes that drift apart.


- References point at content owned by another entry. The referenced entry is reused, and edits show up everywhere.


- Global fields reuse a structure, not values. Two products with the same seo global field each have their own meta title.


- Taxonomies reuse a vocabulary. The term beginner is defined once and every entry that selects it means the same thing.



A simple rule covers most cases: if the same content should appear in several places and stay in sync, it needs to be its own entry, which means a reference.

## Editorial experience

Modular blocks and global fields are edited in place. The editor stays in one entry and sees everything that belongs to it. This makes them the best fit for content that only makes sense in context, like the sections of one page.

References send the editor to another entry. That is the point when the content is shared, but it adds friction for content that is not. A landing page where every section is a separate referenced entry means opening ten entries to change one page, and ten entries to publish.

Taxonomies show up as a term picker. Editors choose from a controlled list and cannot invent new values, which is what you want for anything used in filters.

## Query cost

Modular blocks, global fields and taxonomy terms come back with the entry. One request, no extra parameters.

References come back as a UID and content type UID unless you ask for them to be resolved. With the TypeScript Delivery SDK, you resolve them with includeReference():

```typescript
import contentstack, { QueryOperation } from "@contentstack/delivery-sdk";

const stack = contentstack.stack({
  apiKey: process.env.CONTENTSTACK_API_KEY!,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
  environment: process.env.CONTENTSTACK_ENVIRONMENT!,
});

const post = await stack
  .contentType("blogpost")
  .entry("blt0123456789abcdef")
  .includeReference("author")
  .fetch();
```

References inside blocks use dot notation:

```typescript
const page = await stack
  .contentType("landing_page")
  .entry()
  .includeReference("sections.testimonial.person")
  .query()
  .where("url", QueryOperation.EQUALS, "/pricing")
  .find();
```

Every resolved reference adds entries to the response. A multiple reference field with ten items, where each item references three more entries, turns one entry into forty. Payloads grow, and so does the number of entries whose changes affect the page. Resolve only the paths a page renders, and use only() to keep the fields small.

## Localization and publishing

Modular blocks and global fields are part of the entry. They are localized with the entry, field by field, and published with the entry. One publish, one locale at a time, everything consistent.

A referenced entry has its own localized versions and its own publish state per environment and locale. That has two consequences:

- Publishing a blog post does not publish its author. If the author is not published to that environment, the resolved reference is missing from the response.


- Translating a page does not translate the entries it references. Each referenced entry is translated on its own.



Nested reference publishing helps with the first one. In the publish dialog, editors can send the entry together with its references, up to five levels deep. The [publishing explainer](/blog/releases-bulk-publish-and-nested-reference-publishing-explained) goes deeper into releases and bulk publishing.

Taxonomy terms are stored on the entry, so selecting a term publishes with the entry. The taxonomy itself is managed at the stack level.

## Worked example 1: a landing page

A marketing landing page has a hero, a few feature sections, a testimonial and a CTA. Editors want to reorder sections and add new ones without a deploy.

- Model the page as a landing_page content type with a sections modular blocks field.


- Give each block type its own fields: hero (title, image, CTA), feature_grid (group of items), cta (label, link).


- Make the testimonial block a reference to a testimonial content type, because the same quote appears on several pages.


- Add an seo global field to the content type.



The page stays one entry. Only the testimonial is shared, so only the testimonial needs includeReference().

## Worked example 2: a blog post with an author

A blog post has a title, a body, an author and a few topics.

- The author is a reference to a person entry. The same person writes many posts and has a profile page.


- Topics are taxonomy terms. You filter by them, but they have no content of their own.


- The SEO fields are a global field, shared in structure with every other page type.



The query resolves one reference (author). Topics and SEO come back with the entry.

## Worked example 3: a product with shared SEO and a category

A product has a name, price, images, SEO fields, and belongs to a category like "Rings" or "Necklaces".

- The SEO fields are a global field. Products, pages and blog posts all need the same SEO structure, but each product has its own values.


- If the category is a label used for filtering and breadcrumbs, make it a taxonomy. A category taxonomy can nest "Rings" under "Jewelry", and $eq_below returns everything below a category.


- If the category has its own landing page with a description, hero image and featured products, make it a category content type and reference it from the product.



Many projects end up with both: a taxonomy for filtering, and a category entry for the landing page content.

## Decision table

Question

Modular blocks

Reference

Global field

Taxonomy

Content shared and kept in sync across entries?

No

Yes

No

Terms only

Schema reused across content types?

No

No

Yes

Yes

Editor stays in one entry?

Yes

No

Yes

Yes

Extra query parameter needed?

No

includeReference()

No

No

Publishes with the parent entry?

Yes

No, separately

Yes

Yes

Localized with the parent entry?

Yes

No, per referenced entry

Yes

Yes

Good for filtering?

No

Possible, more work

No

Yes

## Decision flow

Use this flow when you are not sure which option fits:

flowchart TD  A[New piece of content] --> B{Is it a label you filter or group by?}  B -- Yes --> T[Taxonomy]  B -- No --> C{Does the same content appear in several entries and need to stay in sync?}  C -- Yes --> R[Reference to its own entry]  C -- No --> D{Do editors compose a variable list of sections?}  D -- Yes --> M[Modular blocks]  D -- No --> E{Is the same set of fields needed on several content types?}  E -- Yes --> G[Global field]  E -- No --> F[Plain fields or a group on the content type]## Where people get confused

### Global fields do not share content

A global field is a shared schema. If you add an seo global field to products, every product gets its own SEO values. Teams expecting "edit once, update everywhere" need a reference.

### Not everything shared needs a reference

Shared structure is a global field. Shared vocabulary is a taxonomy. Only shared content is a reference.

### Deep reference chains

A page that references sections, which reference cards, which reference authors, is three levels deep before you render anything. Every level adds query cost and publishing steps. Multi-content-type reference fields resolve up to three levels with include, and the GraphQL Content Delivery API stops at three levels too. If your model goes deeper, flatten it.

### Using modular blocks for one fixed layout

If a content type always has exactly one hero and one body, plain fields are simpler. Use modular blocks when the list of sections varies per entry.

## Limits to remember

- A content type can have up to 400 fields, counting the fields inside modular blocks, groups and global fields. See [Contentstack limits on one page](/guides/contentstack-limits-on-one-page).


- A reference field can allow up to 50 content types.


- A multiple content type reference field can hold up to 200 entries, and its references resolve up to three levels deep.


- Nested reference publishing sends references up to five levels deep.


- An entry can hold up to 25 taxonomy terms.



## Key takeaways

- Use modular blocks for content that belongs to one entry and varies in structure, like page sections.


- Use a reference when the same content must appear in several places and stay in sync. Resolve it with includeReference(), and remember it publishes and localizes separately.


- Use a global field to reuse a set of fields across content types. It shares the schema, not the values.


- Use a taxonomy for labels you filter by. Query it with taxonomies.<taxonomy_uid>.


- Keep reference chains shallow. Every level costs payload, cache surface and publishing steps.



## Next steps

- See these patterns applied to menus in [Modeling navigation in Contentstack](/guides/modeling-navigation-in-contentstack).


- Refresh the vocabulary in [Core Contentstack concepts](/guides/contentstack-0-to-100-for-developers/core-contentstack-concepts).


- Learn why this site classifies its content with taxonomies in [Taxonomies are your query layer](/blog/taxonomies-are-your-query-layer).





---

## Do this with AI

Install the cms-data-modeling-best-practices skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Content Modeler profile in MCP Profile Hub. Then ask your agent:

> Review the content types in my stack and point out modular blocks that should be global fields and reference chains deeper than three levels, with a short reason for each.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### Does a global field share content between entries?

No. A global field shares a schema. Every entry that uses it stores its own values. To share values, use a reference.

### Do referenced entries publish with the parent entry?

Not automatically. A referenced entry is its own entry with its own publish state. Nested reference publishing can send references along with the parent, up to five levels deep.

### Do I need includeReference for modular blocks?

No. Modular block content is stored inside the entry and comes back with it. You only need includeReference for reference fields, including reference fields inside blocks.

### When should I use a taxonomy instead of a reference?

When the value is a label you filter by, like a level or a region. Use a reference when the thing you point at has its own content to render.


---

## Step 4: Account, Region, CLI, and Stack Setup

- **Source:** https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/account-region-cli-and-stack-setup
- **Checkpoint:** You have a seeded stack, the CLI installed, and delivery and preview tokens

- **Authors:** Tim Benniks
- **Published:** 2026-04-07T10:35:25.069Z
- **Updated:** 2026-11-10T16:27:10.245Z
- **Level:** Beginner
- **Intent:** Build

---

Now that the platform vocabulary is in place, it is time to create the working foundation Veda expects: an account, the right region, a seeded stack, and the tokens your local app will use.

## What you'll learn

- Which account and stack setup path this guide assumes


- Why region selection matters early


- How to install the Contentstack CLI and log in


- How to seed the Veda stack content


- Which tokens and environment variables the Veda app expects


- Which values are safe to expose in the browser and which are not



## Start with the right account mindset

Contentstack concept: You do not need an enterprise rollout to learn Contentstack well. The Quick Start and Veda materials are designed to work with the platform's accessible onboarding paths, including Explorer-oriented flows.

That is useful because it means you can learn the platform in a realistic way without inventing your own seed data from scratch.

## Region matters sooner than most people expect

Contentstack concept: Your region determines which endpoints your app and tools should talk to.

This affects:

- CLI configuration


- delivery hosts


- preview hosts


- sometimes the exact values or aliases used in environment variables



The official Quick Start currently shows a provider-prefixed CLI region example:

```bash
csdx config:set:region EU
```

Production note: If your installed CLI rejects one form, check csdx --help or the current CLI guidance and use the value it expects. The important part is not the exact alias. The important part is that the CLI and your stack region agree.

## Install the CLI

Contentstack concept: The CLI is the fastest way to bootstrap a working stack for learning and demos.

Install it globally:

```bash
npm install -g @contentstack/cli
```

Then configure your region and log in:

```bash
csdx config:set:region EU
csdx auth:login
```

If your CLI expects a provider-prefixed region value, use that instead.

## Seed the Veda stack

Veda implementation: The current Veda setup path uses a seed repository so you do not have to manually create every content type and entry.

Use the seed command from the Veda setup flow:

```bash
csdx cm:stacks:seed --repo "contentstack/kickstart-veda-seed" --org "<YOUR_ORG_ID>" -n "Veda: The Revival Collection"
```

What this gives you:

- the content model


- starter entries


- assets


- the content relationships the frontend expects



Without the seed, the frontend can still run, but you would first need to recreate the full content structure by hand.

## Create the right tokens

Contentstack concept: The frontend needs read-oriented credentials, not administrative ones.

For Veda, create:

- an API key for the stack


- a delivery token for published content


- a preview token for draft content and preview flows



In the Veda setup instructions, this is done from the Contentstack dashboard under Settings and Tokens.

Production note: Do not use a management token in a frontend app. If you ever need write access, keep it on a server or inside controlled automation.

## Configure local environment variables

Veda implementation: The checked-in .env.example in the Veda repository currently uses these variables:

```bash
NEXT_PUBLIC_CONTENTSTACK_API_KEY=your_api_key_here
NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN=your_delivery_token_here
NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN=your_preview_token_here
NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT=preview
NEXT_PUBLIC_CONTENTSTACK_REGION=EU
NEXT_PUBLIC_CONTENTSTACK_PREVIEW=true
```

Two details matter here:

- The variables use NEXT_PUBLIC_ because Veda's preview experience needs values on the client side


- The app distinguishes between published delivery and preview behavior using NEXT_PUBLIC_CONTENTSTACK_PREVIEW



## Why Veda uses public-looking variables

Veda implementation: In many apps, developers are taught to avoid exposing anything that looks credential-like to the browser. That is a good instinct, but you still need to separate categories of credentials.

Veda uses:

- delivery token


- preview token


- API key



These support content delivery and preview behavior. They are not the same thing as a management token.

Production note: The rule is not "never expose any token-looking string." The rule is "never expose privileged write credentials." Read-only delivery and preview credentials have a different security profile than content administration credentials.

## Recommended setup sequence

If you want the path of least resistance, do it in this order:

- Create or access a Contentstack account


- Install the CLI


- Set the correct region


- Log in


- Seed the Veda stack


- Create delivery and preview tokens


- Prepare your .env.local values for the app



That keeps the frontend setup simple, because once you clone Veda you already know the stack exists and the credentials are ready.

## Key takeaways

- Region matters for both CLI behavior and runtime endpoints


- The Veda learning path is much easier if you seed the stack instead of hand-building the content model first


- The Veda app expects delivery and preview credentials, plus an API key and environment name


- NEXT_PUBLIC_ variables in Veda support preview-aware frontend behavior


- Management credentials are a different class of secret and should stay off the frontend






---

## Frequently asked questions

### Why does the Contentstack region need to be set before seeding a stack?

The region determines which endpoints the CLI and your app use. If the CLI region and stack region don’t match, commands and runtime hosts can be misconfigured.

### How do I install and log in to the Contentstack CLI for Veda setup?

Install with `npm install -g @contentstack/cli`, then run `csdx config:set:region <REGION>` and `csdx auth:login`. Use the region format your CLI version expects.

### What does the Veda stack seed command create?

It bootstraps the content model, starter entries, assets, and relationships the Veda frontend expects. Without seeding, you must recreate the structure manually.

### Which tokens does the Veda frontend need from Contentstack?

Veda uses a stack API key, a delivery token for published content, and a preview token for draft/preview flows. It does not require a management token in the frontend.

### Are NEXT_PUBLIC Contentstack variables safe to expose in the browser?

They can be acceptable when they only enable read-oriented delivery and preview access. Do not expose privileged write credentials such as management tokens.



---

## Chapter Navigation

**← Previous:** [Core Contentstack Concepts](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/core-contentstack-concepts)

**Next →:** [Running Kickstart Veda Locally](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/running-kickstart-veda-locally)

---

## Step 5: Running Kickstart Veda Locally

- **Source:** https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/running-kickstart-veda-locally
- **Checkpoint:** Veda runs locally against your stack

- **Authors:** Tim Benniks
- **Published:** 2026-04-07T10:38:11.446Z
- **Updated:** 2026-11-10T16:27:15.807Z
- **Level:** Beginner
- **Intent:** Build

---

At this point, you have the platform context and the stack setup. Now it is time to run the actual app, confirm the environment is wired correctly, and get a first feel for what the seeded project gives you.

## What you'll learn

- How to clone and install the Veda app


- How to create .env.local from the checked-in example


- Which commands matter for development versus verification


- What a healthy local startup looks like


- Which parts of the running app are worth inspecting first



## Clone the project

Veda implementation: Start by cloning the public repository and moving into it:

```bash
git clone https://github.com/contentstack/kickstart-veda.git
cd kickstart-veda
```

The current Veda repository is built with:

- Next.js


- React


- TypeScript


- Tailwind CSS


- @contentstack/delivery-sdk


- @contentstack/live-preview-utils


- @timbenniks/contentstack-endpoints



## Prepare your local environment file

Veda implementation: Copy the example file, then replace the placeholders with the values from the stack you seeded:

```bash
cp .env.example .env.local
```

Update .env.local so it reflects your real stack values:

```bash
NEXT_PUBLIC_CONTENTSTACK_API_KEY=...
NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN=...
NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN=...
NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT=preview
NEXT_PUBLIC_CONTENTSTACK_REGION=EU
NEXT_PUBLIC_CONTENTSTACK_PREVIEW=true
```

If your stack uses a different environment or region, update those values to match reality.

## Install dependencies and start the app

Use npm, since the project ships with package-lock.json:

```bash
npm install
npm run dev
```

The Veda README currently calls out Node.js 20+ as the safe baseline. If you hit engine or package issues, check your local Node version first.

## What success looks like

Veda implementation: A healthy local start usually looks like this:

- Next.js starts without credential-related runtime failures


- the homepage renders real seeded content instead of blank sections


- the /products area renders catalog data


- category and product-line pages resolve from actual Contentstack entries



If the app boots but content looks empty, the most likely causes are:

- wrong API key


- wrong delivery token


- wrong environment name


- region mismatch


- stack was not seeded successfully



## First pages worth inspecting

You do not need to click every route immediately. Start with the surfaces that teach the most.

### Homepage

Veda implementation: The homepage helps you see modular blocks in action. You are not just looking at a single static page. You are looking at a content-composed page assembled from block data.

### /products

This is where Veda starts to feel different from a tiny starter. The project includes product discovery and filtering logic, which shows how Contentstack content can support a catalog-like experience.

### Category and product-line routes

These routes show that different content types can have different page-level rendering behavior even while sharing the same content platform and utility layer.

## A useful local verification step

Production note: Once local development works, it is worth checking a production build too:

```bash
npm run build
```

That matters in Veda because the build step includes a prebuild hook that runs updateLaunchConfig.mjs, which generates a launch.json file for cache priming.

So a successful build is validating more than "Next.js compiles." It is also validating that your stack can be queried for route discovery during the build workflow.

## What to do if preview is not working yet

Do not panic if Live Preview is not the first thing that works. Focus on this order:

- published content fetch works


- routes render correctly


- build succeeds


- preview wiring is confirmed



That gives you a clean debugging sequence instead of trying to troubleshoot everything at once.

## Why this chapter matters

Contentstack concept: A lot of developer confidence comes from getting one real system running end to end. Once the app is live locally and your data is showing up, the later architecture chapters stop feeling theoretical.

You now know three important things:

- the stack exists


- the app can read from it


- the repository is worth studying in detail



## Key takeaways

- Use the public Veda repository as the codebase for this guide


- Start from .env.example, then replace placeholders with your real stack values


- npm install and npm run dev are the quickest path to a live local environment


- A successful npm run build validates both compilation and the cache-priming route discovery step


- Start by verifying published content before you diagnose preview behavior






---

## Frequently asked questions

### What Node.js version should I use to run Kickstart Veda locally?

Use Node.js 20+ as a safe baseline. If you see engine or package issues, verify your local Node version first.

### How do I create the .env.local file for Kickstart Veda?

Copy the checked-in example with `cp .env.example .env.local`. Then replace the placeholders with your Contentstack API key, tokens, environment name, and region.

### Which commands do I run to start the app in development?

Run `npm install` to install dependencies, then `npm run dev` to start the Next.js development server. The project ships with a package-lock.json, so npm is the expected package manager.

### What does a healthy local startup look like?

Next.js should start without credential-related runtime failures, and the homepage and `/products` should render real seeded content. Category and product-line routes should resolve from actual Contentstack entries.

### Why should I run `npm run build` during local verification?

A production build validates more than compilation because a `prebuild` hook runs `updateLaunchConfig.mjs` to generate `launch.json` for cache priming. It also confirms your stack can be queried for route discovery during the build workflow.



---

## Chapter Navigation

**← Previous:** [Account, Region, CLI, and Stack Setup](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/account-region-cli-and-stack-setup)

**Next →:** [Understanding the Veda Content Model](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/understanding-the-veda-content-model)

---

## Step 6: How Veda Is Structured

- **Source:** https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/how-veda-is-structured
- **Checkpoint:** You know where fetching, rendering and preview live in the codebase

- **Authors:** Tim Benniks
- **Published:** 2026-04-07T10:46:55.189Z
- **Updated:** 2026-11-10T16:27:11.585Z
- **Level:** Beginner
- **Intent:** Learn

---

You now understand the platform and the content model. This chapter maps that understanding onto the codebase so the repository stops looking like "a bunch of Next.js files" and starts reading like a deliberate architecture.

## What you'll learn

- How the main Veda folders divide responsibility


- Why the route structure mirrors the content model


- What lib/contentstack.ts and lib/pageUtils.ts are doing


- Why the component renderer and preview layer matter so much


- Which architectural ideas are portable beyond this specific starter



## Start with the top-level shape

Veda implementation: The public Veda materials describe a structure centered around three areas:

- app/


- components/


- lib/



That separation is already meaningful.

flowchart LR

  App[app routes] --> PageUtils[lib/pageUtils.ts]

  PageUtils --> Contentstack[lib/contentstack.ts]

  Contentstack --> API[Contentstack Delivery or Preview API]

  PageUtils --> PageComponents[components/Pages/*]

  PageComponents --> Renderer[ComponentsRenderer]

  Renderer --> Blocks[Hero List Media RichText TwoColumn]

This is the architecture at the level that matters most when you are onboarding:

- routes ask for page-shaped data


- utility functions normalize path and fetch logic


- one integration layer talks to Contentstack


- page components render the result


- the block renderer turns modular content into concrete UI



### app/

This is the Next.js App Router layer. It is where route-level behavior lives.

From the repo and public materials, you can see route shapes such as:

- app/[[...slug]]/page.tsx for general pages


- category routes


- product-line and product routes under /products/...



This mirrors the content model instead of forcing every page through one identical path strategy.

### components/

This layer contains reusable rendering pieces.

Two especially important ideas show up here:

- page-level components for major content shapes


- a modular block renderer that maps Contentstack data to React components



### lib/

This is the application logic layer where Contentstack integration, data fetching, typing, filtering, and page utilities live.

## lib/contentstack.ts: the shared content boundary

Veda implementation: This file is the main bridge between the frontend and Contentstack.

It is responsible for things like:

- initializing the Delivery SDK


- resolving region-aware endpoints


- enabling preview configuration


- exposing focused fetchers such as getPage, getHeader, getCategory, getProduct, and getProductLine


- applying editable tags in preview mode



This is a strong pattern because it keeps low-level SDK setup and query concerns out of page components.

Contentstack concept: A shared integration boundary is portable. Even if you never use Next.js again, the idea of centralizing stack configuration and data access still holds.

### Code example: the stack client and focused fetchers

Here is a shortened excerpt from the current Veda lib/contentstack.ts:

```typescript
const region = getRegionForString(process.env.NEXT_PUBLIC_CONTENTSTACK_REGION as string)
const endpoints = getContentstackEndpoints(region, true)
export const isPreview = process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW === "true";

export const stack = contentstack.stack({
  apiKey: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY as string,
  deliveryToken: process.env.NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN as string,
  environment: process.env.NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT as string,
  region: region ? region : process.env.NEXT_PUBLIC_CONTENTSTACK_REGION as any,
  host: process.env.NEXT_PUBLIC_CONTENTSTACK_CONTENT_DELIVERY || endpoints && endpoints.contentDelivery,
  live_preview: {
    enable: process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW === "true",
    preview_token: process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN,
    host: process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW_HOST || endpoints && endpoints.preview
  }
});
```

What this is doing:

- turns env vars into one shared SDK client


- resolves the right hosts for the selected region


- exposes a boolean isPreview flag the rest of the app can reuse


- configures preview delivery and published delivery in one place



That last point matters. Instead of every page guessing how preview works, the app has one source of truth.

## lib/pageUtils.ts: turning fetchers into a page system

Veda implementation: This file is one of the clearest signals that Veda is not just a minimal starter.

The public code shows it handling things like:

- caching fetchers with React cache()


- building paths from route parameters


- centralizing metadata generation


- exposing typed route-friendly wrapper functions



This matters because it normalizes a lot of repeated page concerns:

- derive the URL


- fetch the matching content


- fetch shared header content


- decide whether preview mode applies


- generate metadata consistently



That is the difference between a demo and an application skeleton.

### Code example: path building and unified fetch flow

This trimmed excerpt from lib/pageUtils.ts is worth studying:

```typescript
export function buildPath(type: "page" | "category" | "product" | "productLine",
  params: any): string {
  switch (type) {
    case "page":
      return params.slug ? `/${params.slug.join("/")}` : "/";
    case "category":
      return `/category/${params.category}`;
    case "product":
      return `/products/${params.line}/${params.slug}`;
    case "productLine":
      return `/products/${params.line}`;
  }
}

export async function fetchData(type: "page" | "category" | "product" | "productLine",
  params: any) {
  const path = buildPath(type, params);
  const header = await getHeaderCached();
  let content;

  switch (type) {
    case "page":
      content = await getPageCached(path);
      break;
    case "category":
      content = await getCategoryCached(path);
      break;
  }

  return { content, header, path, isPreview, previewType: type };
}
```

Why this is useful:

- route params are normalized into a stable path string


- shared header data is fetched once in the same utility layer


- page components receive a consistent return shape


- preview mode can be passed through without route files duplicating logic



The hidden benefit is architectural calm. A route file can stay focused on page behavior because path building, shared header fetching, and content-type dispatch are already standardized.

## Route types map to content types

Veda implementation: Veda does not assume every entry is rendered the same way.

That decision shows up in the route structure:

- general pages flow through the catch-all page route


- product-related pages have their own route behavior


- catalog experiences can own specialized fetching and rendering logic



This is a healthy pattern. It keeps your shared platform logic unified while letting important content domains have dedicated page behavior.

## ComponentsRenderer.tsx: the page builder bridge

Veda implementation: The modular block renderer maps block names like hero, list, two_column, media, and rich_text to actual React components.

That is one of the most educational files in the whole repo because it solves a common headless CMS problem cleanly:

- Contentstack stores structured modular data


- React needs concrete components


- preview mode needs wrappers and editable bindings



The renderer becomes the contract between editorial composition and frontend rendering.

Production note: Keeping that mapping centralized makes customization much safer. If you later add a new block type, you have one obvious place to wire it into the application.

### Code example: the block-to-component map

This is the core idea from the current Veda renderer:

```typescript
const componentMap = {
  hero: HeroComponent,
  list: ListComponent,
  two_column: TwoColumnComponent,
  media: MediaComponent,
  rich_text: RichTextComponent,
} as const;
```

That tiny map explains the whole page-builder approach:

- Contentstack says which block type an editor added


- the renderer looks up the matching React component


- the app stays explicit about what is supported



That is one of the cleanest architectural lessons in the repo.

### Code example: a page-level renderer

This excerpt from components/Pages/Page.tsx shows how simple page rendering becomes once the utility layers are in place:

```typescript
export default function Page({
  page,
  header,
}: {
  page: PageProps;
  header?: MegaMenuProps;
}) {
  const components = page?.components || [];

  return (
    <>
      {header && (
        <MegaMenu header={header.header} product_lines={header.product_lines} />
      )}
      {components && (
        <ComponentsRenderer
          components={components}
          cslp={page.$}
          cslpWrapper="components"
        />
      )}
      <Footer />
    </>
  );
}
```

The page component is not doing raw API work. It is doing what a good page component should do:

- render shared layout content


- render the block list


- pass preview bindings through to the renderer



## components/Pages/Preview.tsx: a first-class editing mode

Veda implementation: Veda uses a dedicated preview wrapper component that:

- initializes Live Preview


- subscribes to change events


- re-fetches the correct content type for the current route


- swaps in the correct page-level renderer



This is a smart design choice because it prevents preview behavior from leaking into every page component in an ad hoc way.

### Code example: one preview wrapper for multiple content types

Here is the part of the current preview component that shows the strategy most clearly:

```typescript
async function getPreviewData(
  type: "page" | "product" | "productLine" | "category",
  path: string
) {
  switch (type) {
    case "page":
      return getPage(path);
    case "product":
      return getProduct(path);
    case "productLine":
      return getProductLine(path);
    case "category":
      return getCategory(path);
  }
}
```

That is a great example of orchestration without chaos. Preview is centralized, but each content type still gets its own fetcher.

## Why this structure scales better than a tiny starter

A minimal starter often puts everything in a few files and calls it a day. That is okay for proving connectivity. It is not enough for understanding how a larger Contentstack app stays maintainable.

Veda's structure shows a more realistic split:

- routes own page entry points


- page utilities normalize route-specific concerns


- the Contentstack integration layer owns fetching and preview setup


- components focus on rendering


- page-level components distinguish major content experiences



That is what makes the repository worth studying.

## Portable lessons from this architecture

Contentstack concept: The specific file names are Veda-specific. The architectural lessons are portable:

- centralize stack configuration


- centralize reusable fetchers


- normalize route-to-content logic


- keep modular block mapping explicit


- treat preview as a dedicated runtime mode



If you internalize those ideas, you can recreate the same strengths in other frameworks and codebases.

## Key takeaways

- Veda mirrors its content model in both its route structure and its data-fetching utilities


- lib/contentstack.ts is the integration boundary for SDK setup, preview wiring, and content fetchers


- lib/pageUtils.ts turns low-level fetchers into a consistent page system


- ComponentsRenderer.tsx is the bridge between modular block data and React components


- Preview.tsx keeps editing behavior centralized instead of scattering preview logic everywhere






---

## Frequently asked questions

### What is the purpose of the app/ folder in Veda?

app/ contains the Next.js App Router routes and route-level behavior. Its route shapes mirror the content model (pages, categories, products) instead of forcing one generic path strategy.

### What does lib/contentstack.ts handle?

It centralizes Contentstack SDK initialization, region-aware endpoints, and Live Preview configuration. It also exposes focused fetchers like getPage, getHeader, getCategory, getProduct, and getProductLine.

### Why does Veda use lib/pageUtils.ts?

pageUtils normalizes route params into stable paths, caches fetchers, fetches shared header data, and returns a consistent data shape to page components. This reduces duplicated logic across route files.

### What problem does ComponentsRenderer.tsx solve?

It maps modular Contentstack block types (for example hero, list, rich_text) to concrete React components. This makes supported blocks explicit and keeps the page-builder contract centralized.

### How is preview mode implemented in Veda?

Preview behavior is centralized in a dedicated Preview.tsx wrapper that initializes Live Preview, listens for changes, and re-fetches the correct content type for the current route. This avoids scattering preview logic across page components.



---

## Chapter Navigation

**← Previous:** [Understanding the Veda Content Model](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/understanding-the-veda-content-model)

**Next →:** [Fetching Content, Routing, and Rendering](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/fetching-content-routing-and-rendering)

---

## Step 7: Kickstart Next

- **Source:** https://developers.contentstack.com/kickstarts/kickstart-next
- **Checkpoint:** You have seen the same pattern in the smallest possible Next.js starter

- **Published:** 2026-03-17T11:53:05.337Z
- **Updated:** 2026-11-10T15:04:27.361Z
- **Level:** Beginner
- **Intent:** Build
- **Tags:** next, react

---

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.


---

## Step 8: Tour de Live Preview

- **Source:** https://developers.contentstack.com/livestreams/tour-de-live-preview
- **Checkpoint:** You know which Live Preview setup fits SSR, SSG and CSR

- **Hosts:** Lo Etheridge, Tim Benniks
- **Published:** 2025-02-12
- **Updated:** 2026-11-10T15:04:27.452Z
- **Level:** Intermediate
- **Intent:** Learn
- **Tags:** api, visual_editing, headless
- **Watch:** https://www.youtube.com/watch?v=9vYYsyv67QE

---

We go over every possible Live Preview configuration from SSG to SSR, and from CSR to GraphQL. This is the final guide on setting up Contentstack Live Previe...



---

## About this livestream

We go over every possible Live Preview configuration from SSG to SSR, and from CSR to GraphQL. This is the final guide on setting up Contentstack Live Previe...



---

> **Originally written here:** [https://www.youtube.com/watch?v=9vYYsyv67QE](https://www.youtube.com/watch?v=9vYYsyv67QE)
