---
title: "From prototype to real project"
url: "https://developers.contentstack.com/paths/from-prototype-to-real-project"
type: "path_full"
level: "intermediate"
outcome: "A multi-locale site with modeled navigation, Visual Editor and a production-ready setup"
steps:
  - "https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/understanding-the-veda-content-model"
  - "https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/fetching-content-routing-and-rendering"
  - "https://developers.contentstack.com/guides/modeling-navigation-in-contentstack"
  - "https://developers.contentstack.com/guides/querying-content-by-taxonomy"
  - "https://developers.contentstack.com/guides/building-a-multi-language-website-using-contentstack-and-next-js-i18n"
  - "https://developers.contentstack.com/guides/the-ultimate-guide-to-contentstack-visual-building"
  - "https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/customizing-veda-for-your-own-project"
  - "https://developers.contentstack.com/guides/safe-content-model-changes-with-branches-and-aliases"
  - "https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/production-readiness-troubleshooting-and-next-steps"
  - "https://developers.contentstack.com/livestreams/just-automate-it"
updated: "2026-11-15T11:47:35.673Z"
---

# From prototype to real project

- **Level:** Intermediate
- **Steps:** 10
- **Overview:** https://developers.contentstack.com/paths/from-prototype-to-real-project.md

---

For developers with a working starter who want to model real content, add locales and give editors a proper visual editing experience.

**You'll end up with:** A multi-locale site with modeled navigation, Visual Editor and a production-ready setup

## Table of Contents

1. Understanding the Veda Content Model
2. Fetching Content, Routing, and Rendering
3. Modeling navigation in Contentstack
4. Querying content by taxonomy
5. Building a Multi-Language Website Using Contentstack and Next.js i18n
6. The Ultimate Guide to Contentstack Visual Editor
7. Customizing Veda for your own project
8. Safe content model changes with branches and aliases
9. Production readiness, troubleshooting, and next steps
10. Just Automate It!


---

## Step 1: Understanding the Veda Content Model

- **Source:** https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/understanding-the-veda-content-model
- **Checkpoint:** You can read a content model and trace it to the code

- **Authors:** Tim Benniks, Lo Etheridge
- **Published:** 2026-04-07T10:39:31.776Z
- **Updated:** 2026-11-10T16:27:13.181Z
- **Level:** Intermediate
- **Intent:** Learn

---

Once the app runs, the next thing to understand is the shape of the content itself. This is where Contentstack starts to feel different from a simple data fetch exercise. Veda works because the content model already encodes relationships, reusable structures, and route-friendly fields.

## What you'll learn

- Which content types Veda uses and what each one is responsible for


- How modular blocks fit into page composition


- How the content types relate to one another


- Why the model supports both flexible pages and purpose-built product experiences


- How editors and developers divide responsibilities inside this model



## The main Veda content types

Before we go content type by content type, here is a compact developer-oriented view of the core Veda models.

Content type

Main purpose

Key props in the Veda types

Frontend use

page

Flexible marketing and editorial pages

title, url, description, image, components, $

Catch-all page routes render it through ComponentsRenderer

product

Individual catalog item pages

title, url, short_description, description, price, category, product_line, media, taxonomies, $

Product page, breadcrumbs, related lists, filtering context

product_line

Collection or line-level landing page

title, url, description, image, products, taxonomies, $

Collection pages and featured product groupings

category

Browsing-oriented grouping

title, url, description, media, products, taxonomies, $

Category pages and product discovery

header

Shared global navigation content

title, logo, links, $

Mega menu and shared site chrome

### What the most important props really mean

Prop

Meaning in practice

Why it matters

url

Canonical path stored in content

Lets the frontend resolve routes from content instead of hardcoded IDs

components

Array of modular blocks such as hero or rich_text

Powers flexible page composition

category / product_line

Reference arrays to related entries

Enables breadcrumbs, related products, and richer page context

media / image / logo

Asset references

Keeps images and media in Contentstack instead of the codebase

taxonomies

Structured classification terms

Supports filtering and grouping without custom hardcoded logic

$

Preview/edit metadata bindings

Lets Live Preview and Visual Editor map UI elements back to fields

### page

Veda implementation: The page content type powers the more flexible, content-composed parts of the site.

This is usually where modular blocks do their most visible work. A page entry can describe a route such as / or another marketing-style URL and assemble its content from a series of reusable sections.

### product

Products represent individual catalog items. They carry the sort of data you expect a product experience to need:

- title


- URL


- media


- short descriptive content


- taxonomy-related data


- product-specific display information



### product_line

Product lines group products into larger branded collections. In Veda, this supports richer merchandising and collection storytelling instead of treating the catalog like one flat list.

### category

Categories represent browsing-oriented groupings. These are useful for navigation and product discovery because users do not always browse by brand story alone.

### header

The header content type supports shared navigation data and helps the frontend render consistent global navigation without hardcoding it into the app.

## How these content types relate to each other

This is the simplest way to picture the Veda model:

flowchart TD

  Page[page] --> Blocks[components modular blocks]

  Page --> Asset[image asset]

  Header[header] --> Logo[logo asset]

  Header --> Nav[links]

  Header --> ProductLine

  ProductLine[product_line] --> Product

  Category[category] --> Product

  Product --> Media[media assets]

  Product --> Taxonomies[taxonomies]

  Product --> ProductLine

  Product --> Category

This is not trying to show every field. It is showing the relationships that matter most when you read the frontend code:

- pages are block-driven


- navigation is shared content


- products sit inside broader browsing structures


- assets and taxonomy data are part of the content model, not bolted on later



## What the API data looks like in practice

Veda implementation: One of the nicest things about the Veda repo is that the TypeScript interfaces make the expected Contentstack response shape much easier to understand.

Here is a trimmed version of the current Page and Product types from lib/types.ts:

```typescript
export interface Page extends SystemFields {
  title: string;
  url?: string;
  description?: string;
  image?: File | null;
  components?: Components[];
  $?: {
    title?: CSLPFieldMapping;
    url?: CSLPFieldMapping;
    description?: CSLPFieldMapping;
    image?: CSLPFieldMapping;
    components?: CSLPFieldMapping;
  };
}

export interface Product extends SystemFields {
  title: string;
  url?: string;
  short_description?: string;
  description?: string;
  price?: number | null;
  category?: Category[];
  product_line?: ProductLine[];
  media?: File[] | null;
  taxonomies?: Taxonomy[];
  $?: {
    title?: CSLPFieldMapping;
    url?: CSLPFieldMapping;
    short_description?: CSLPFieldMapping;
    description?: CSLPFieldMapping;
    price?: CSLPFieldMapping;
    category?: CSLPFieldMapping;
    product_line?: CSLPFieldMapping;
    media?: CSLPFieldMapping;
    taxonomies?: CSLPFieldMapping;
  };
}
```

That tells you a lot right away:

- Page is built around flexible modular content in components


- Product is a richer detail shape with relationships to category and product_line


- both can carry a $ object for preview/edit bindings



## How to read the Veda types as a developer

Veda implementation: The most useful habit here is to treat each interface as a contract between Contentstack and the React app.

For example:

- required-looking fields such as title: string are fields the frontend expects to exist for a healthy render


- optional fields such as description? or media? are fields the frontend can handle conditionally


- arrays such as product_line?: ProductLine[] mean the content type is relational, not isolated


- nested objects like image?: File | null tell you the frontend expects fully resolved asset objects, not just asset IDs



That means the TypeScript file is doing two jobs at once:

- documenting the content model


- documenting the data shape the components are built around



## A mental model for the response payload

Contentstack concept: The Delivery SDK eventually gives you normal JavaScript objects. The TypeScript interfaces are not the payload themselves, but they are a strong guide to the payload shape.

A page entry fetched for a route like / will look roughly like this:

```json
{
  "uid": "blt-page-home",
  "title": "The Revival Collection",
  "url": "/",
  "description": "Luxury jewelry with modular content sections.",
  "image": {
    "uid": "blt-asset-hero",
    "title": "Homepage hero",
    "url": "https://images.contentstack.io/v3/assets/..."
  },
  "components": [{
    "hero": {
      "title": "The Revival Collection",
      "description": "An upscale unisex jewelry line",
      "image": {
        "url": "https://images.contentstack.io/v3/assets/..."
      }
    }
  },
  {
    "list": {
      "title": "Explore the collections",
      "reference": [{
        "title": "Digital Dawn",
        "url": "/products/digital-dawn"
       }]
      }
    }]
  }
```

This is not a copy-pasted live response. It is an inferred shape based on the Veda types and query behavior. The important part is the structure:

- system fields such as uid


- content fields such as title, url, and description


- nested asset objects


- modular blocks represented as keyed objects inside the components array




## Why the modular block array looks a little unusual

Veda implementation: The components field is not just an array of identical objects. Each item is a one-key object whose key identifies the block type:

```json
[{ "hero": { "...": "..." } },{ "rich_text": { "...": "..." } },{ "media": { "...": "..." } }]
```

That design is the reason Veda needs a central renderer. The renderer inspects the key, then decides which React component to use.

## What the $ field is for

Contentstack concept: The $ object is preview-oriented metadata added by the frontend utility layer so rendered elements can be linked back to content fields during editing.

Readers often see $ in the Veda code and assume it is normal published content. It is better to think of it as editor-facing metadata attached to the content object for Live Preview and Visual Editor behavior.

That means:

- title is content


- $?.title is field-binding metadata about that content



Both matter, but they serve different audiences.

## Why this model is stronger than a single "page" schema

Contentstack concept: A common beginner mistake is to overuse one generic content type for everything.

That can work for small demos, but it breaks down fast. Product detail pages, collection pages, and generic editorial pages often have different rendering needs, different data relationships, and different editorial expectations.

Veda avoids that trap by modeling content domains separately while still allowing flexible composition where it makes sense.

## Modular blocks in Veda

Veda implementation: The current Veda materials describe these core modular blocks:

- hero


- list


- two column


- media


- rich text



Here is the developer-facing summary of those block props:

Block type

Key props

What the block is good for

hero

title, description, ctas, image, video, design

Top-of-page storytelling and visual entry points

list

title, description, reference, cards, load_first_image_eager

Featured collections, related products, grouped content

two_column

side_a, side_b

Structured paired layouts without hardcoding a one-off page

media

image, width, height, crop, widths

Image-led sections with delivery and layout hints

rich_text

title, content, alternative_content, ctas

Editorial copy blocks with optional call-to-action support

This is one of the most important ideas in the guide.

The content model does not say, "Editors can build anything." It says, "Editors can build anything from this approved set of structured building blocks."

That is the right kind of flexibility. It creates freedom without turning the frontend into an unbounded renderer.

## Full component inventory from the Veda types

Veda implementation: The Veda repo has both top-level page-builder blocks and smaller supporting component shapes nested inside those blocks. This table helps you read lib/types.ts without having to guess which pieces are page sections and which pieces are sub-objects.

Type or component

Kind

Key props

Why it exists

Hero

Top-level modular block

title, title_tag, description, ctas, image, video, design

Hero section with copy, CTA, and media support

List

Top-level modular block

title, title_tag, description, load_first_image_eager, reference, cards

Reusable listing block for product references, cards, and grouped content

TwoColumn

Top-level modular block

side_a, side_b

Two-column layout that can hold other nested content objects

Media

Top-level modular block and nested media object

image, width, height, crop, widths

Structured image block with rendering hints

RichText

Top-level modular block and nested editorial object

title, title_tag, content, alternative_content, ctas

Rich editorial content with optional CTA support

Card

Supporting nested component

title, description, image, link

Small repeatable promo or summary unit inside a list

Cards

Supporting wrapper object

card

Gives the list a repeatable array of card objects in the Contentstack schema

Cta

Supporting nested component

text, link

Reusable call-to-action shape

Ctas

Supporting wrapper object

cta

Lets a hero carry one or more CTA items in a structured way

SideA

Supporting nested layout item

list, media, rich_text

Defines the allowed content shapes inside each column

Components

Top-level modular block union object

hero, list, two_column, media, rich_text

The union-like content structure the renderer inspects block by block

Links

Supporting navigation component

label, item, reference, featured_product, show_product_lines, show_all_products_links

Structured nav link definition used by the mega menu

PageHeader

Supporting reference wrapper

reference

Reference container for header content when header data is modeled as referenced content

Link

Shared value object

title, href

Generic link shape reused across the content model

File

Shared asset object

title, url, description, dimension, publish_details

Standard Contentstack asset payload used throughout the app

### How to interpret this table

- The top-level page-builder blocks are Hero, List, TwoColumn, Media, and RichText


- Wrapper types like Cards and Ctas exist because Contentstack schemas often model repeatable nested items through small wrapper objects


- Shared objects like Link and File are not page sections by themselves, but they appear all over the content model and are essential to understanding the payload shape


- Components is especially important because it is the type that lets page.components hold different block kinds in one array



If you are trying to understand what the renderer is doing, focus first on Components, then on the five top-level blocks, then on the nested helper types those blocks use.

## How the content types relate to each other

The real power of Veda is not the list of content types. It is the fact that those types work together.

Veda implementation: From the repository and guide materials, you can see patterns like these:

- pages use modular composition


- header data is fetched alongside page-level content


- product lines and categories support dedicated route experiences


- product filtering uses taxonomy-aware logic


- richer queries often include related content instead of treating entries as isolated records



This is why the Veda repo uses deeper include behavior in its fetch layer. The app is not merely asking for a title and body. It is asking for connected content that can support a full page experience.

## A concrete relationship example from product data

Veda implementation: The Product type tells you that a product payload is not flat. It can include related categories, product lines, media arrays, and taxonomy data:

```typescript
export interface Product extends SystemFields {
  title: string;
  url?: string;
  price?: number | null;
  category?: Category[];
  product_line?: ProductLine[];
  media?: File[] | null;
  taxonomies?: Taxonomy[];
}
```

So a product response can look conceptually like this:

```json
{"title": "Silver Orbit Ring","url": "/products/digital-dawn/silver-orbit-ring","price": 240,"category": [
    { "title": "Rings", "url": "/category/rings" }],"product_line": [
    { "title": "Digital Dawn", "url": "/products/digital-dawn" }],"media": [
    { "url": "https://images.contentstack.io/v3/assets/..." }],"taxonomies": [
    { "taxonomy_uid": "materials", "term_uid": "silver" },
    { "taxonomy_uid": "product_type", "term_uid": "ring" }]}
```

That is why catalog features like breadcrumbs, related listings, and filters can work without hardcoded lookup tables in the frontend.

## What editors control versus what developers control

Contentstack concept: Good Contentstack architecture makes the editor/developer boundary obvious.

Editors control:

- entry values


- page composition using allowed blocks


- ordering of sections


- text, media, and content relationships within the defined schema



Developers control:

- the content type schema itself


- which blocks exist


- how each block renders


- how URLs map to routes


- how queries fetch and normalize data



That is a healthy collaboration model. Editors gain flexibility without silently changing the application's architecture.

## Why Veda is a good teaching model

Veda implementation: Veda demonstrates that a project can mix:

- flexible content-composed pages


- dedicated page templates for important content types


- shared navigation content


- catalog-oriented data behavior



That blend is exactly what many production sites need. Not everything should be one generic block page. Not everything should be one rigid template either.

## Questions to ask when adapting this model

As you study the Veda model, keep these questions in mind:

- Which content types in my project deserve dedicated page templates?


- Which content should stay modular and editor-composed?


- Which fields need stable URLs?


- Which relationships are editorially meaningful enough to model as references?


- Which repeated page patterns should become modular blocks instead of duplicated fields?



Those questions matter more than copying Veda field-for-field.

## Key takeaways

- Veda uses multiple content types because multiple page behaviors exist in the site


- page handles flexible composition, while product-oriented types support more purpose-built experiences


- Modular blocks provide the right balance between editorial flexibility and frontend control


- References and richer queries turn the model into a connected system instead of disconnected entries


- The useful lesson is not to clone the exact schema blindly, but to understand why each content type exists






---

## Frequently asked questions

### What are the main Veda content types and what do they do?

Veda centers on page (modular marketing/editorial pages), product (catalog detail), product_line (collection landing), category (browsing group), and header (global navigation). Each type encodes both fields and relationships used by the frontend.

### How do modular blocks work in Veda pages?

The page.components field is an array of one-key objects, where the key identifies the block type (for example hero or rich_text). A central renderer inspects the key and selects the matching React component.

### Why does Veda store a url field in content?

The url field acts as the canonical path so the frontend can resolve routes from content rather than hardcoded IDs. It supports predictable routing for pages, products, and collection-like entries.

### What is the $ field in the Veda types?

The $ object carries preview/edit field-binding metadata used by Live Preview and Visual Builder. It is not normal published content, but it is attached to content objects to map rendered UI back to fields.

### How should developers read lib/types.ts in the Veda repo?

Treat each TypeScript interface as a contract for the expected Delivery API response shape. Required fields indicate render expectations, optional fields are handled conditionally, and arrays/references signal relational content.



---

## Chapter Navigation

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

**Next →:** [How Veda Is Structured](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/how-veda-is-structured)

---

## Step 2: Fetching Content, Routing, and Rendering

- **Source:** https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/fetching-content-routing-and-rendering
- **Checkpoint:** You know how entries become routes and rendered pages

- **Authors:** Tim Benniks, Lo Etheridge
- **Published:** 2026-04-07T10:51:27.341Z
- **Updated:** 2026-11-10T16:27:13.883Z
- **Level:** Intermediate
- **Intent:** Learn

---

This chapter gets into the mechanics of how Veda turns Contentstack data into pages. If earlier chapters gave you the vocabulary and the architecture, this is where the moving parts connect.

## What you'll learn

- How the Delivery SDK is initialized in a region-aware way


- How Veda fetches by content type and URL


- Why cached helpers improve consistency


- How metadata generation fits into the page system


- How modular block data becomes React output


- Which patterns are generic Contentstack practice versus Veda-specific implementation



## SDK initialization

Contentstack concept: A Contentstack frontend starts by creating a stack client with the correct API key, delivery token, environment, and region.

Veda implementation: Veda goes a little further by resolving endpoints from the configured region instead of hardcoding hostnames. That is why the repo includes @timbenniks/contentstack-endpoints.

A simplified version of the idea looks like this:

```typescript
import contentstack from "@contentstack/delivery-sdk";

export const stack = contentstack.stack({
  apiKey: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY!,
  deliveryToken: process.env.NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN!,
  environment: process.env.NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT!,
  region: process.env.NEXT_PUBLIC_CONTENTSTACK_REGION!,
});
```

Veda expands that pattern with region parsing, explicit hosts, and preview-aware configuration.

### Code example: the real Veda stack setup

This shortened excerpt from the current Veda repo shows the actual pattern:

```typescript
const region = getRegionForString(process.env.NEXT_PUBLIC_CONTENTSTACK_REGION as string)
const endpoints = getContentstackEndpoints(region, 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
  }
});
```

This is worth understanding line by line:

- region is derived, not trusted as an arbitrary string alone


- endpoint resolution is centralized


- delivery and preview configuration live on the same shared client


- the rest of the app does not need to keep rebuilding this logic



## Why region-aware host handling is a good idea

Production note: Hardcoded hosts are easy to forget and annoying to audit later. Region-aware endpoint resolution gives you a cleaner contract:

- your environment variables declare which region you are in


- the code derives the correct delivery and preview hosts


- moving between supported regions becomes less error-prone



That is a great pattern to borrow even if you do not copy Veda line for line.

## URL-based entry fetching

Veda implementation: One of the central Veda patterns is fetching content by URL rather than by hardcoded entry UID in page routes.

That makes sense for a site:

- routes are URL-shaped


- content entries store URL fields


- the query layer translates from route path to matching content entry



That approach is especially visible in the page fetchers, where a URL is used to resolve the correct page, category, product, or product_line entry.

### Code example: getPage() by URL

This excerpt from lib/contentstack.ts is one of the best pieces of teaching material in the repo:

```typescript
export async function getPage(url: string): Promise<Page> {
  const pageQuery = stack
    .contentType("page")
    .entry()

  pageQuery.addParams({ include_all: true });
  pageQuery.addParams({ include_all_depth: 2 });

  const result = await pageQuery
    .query()
    .where("url", QueryOperation.EQUALS, url)
    .find<Page>();

  if (result.entries) {
    const entry = result.entries[0]

    if (isPreview) {
      contentstack.Utils.addEditableTags(entry as EmbeddedItem, "page", true);
    }

    return entry
  }

  throw new Error(`Page not found for url: ${url}`);
}
```

What this tells you:

- Veda stores stable URLs in content


- the frontend queries by that URL field


- the SDK returns a result object with an entries array


- Veda uses the first matching entry as the page


- preview mode mutates the returned object with editable field metadata



## Why Veda uses richer include behavior

Veda implementation: The public repo shows Veda adding deeper include parameters when fetching certain content types.

That is not accidental. A content-rich site often needs related content in the same query:

- assets


- referenced entries


- modular content structures



If you fetch too narrowly, your rendering layer ends up making repeated follow-up requests or receiving incomplete data. Veda chooses to pull richer page-shaped payloads where that helps the page render in one pass.

## What the result object looks like before Veda picks entries[0]

Contentstack concept: The SDK query result is not just the entry itself. It is a wrapper object that usually contains an entries array and sometimes a count.

So the conceptual shape is closer to this:

```json
{
  "entries": [
    {
      "title": "The Revival Collection",
      "url": "/",
      "components": [
        {
          "hero": {
            "title": "The Revival Collection"
          }
        }
      ]
    }],
  "count": 1
}
```

Veda then unwraps that structure and works with the first matching entry:

```typescript
const entry = result.entries[0]
```

That is why the data-fetching helpers feel simpler than the raw SDK response shape.

## Cached fetch helpers

Veda implementation: lib/pageUtils.ts wraps key fetchers in React cache().

That gives the app a cleaner, more repeatable data layer. Instead of every route reinventing fetching and metadata logic, Veda normalizes it with helper functions.

Production note: Caching here is not just about speed. It is also about consistency. Reusing the same fetch helper reduces the chance that one route forgets a query parameter, a shared header request, or a preview condition.

### Code example: the unified fetch helper

The current fetchData() flow in lib/pageUtils.ts is a good example of normalization:

```typescript
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;
    case "product":
      content = await getProductCached(path);
      break;
    case "productLine":
      content = await getProductLineCached(path);
      break;
  }

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

That return shape is exactly why the route files stay readable. They do not need to know every fetch detail.

## Metadata generation

Veda implementation: Veda generates metadata from fetched content instead of hardcoding route metadata separately from content.

That is a useful pattern because page metadata usually belongs to the content model:

- title


- description


- Open Graph image


- canonical page intent



Once metadata is part of your content-aware fetch layer, dynamic routes stay easier to manage.

## How modular blocks become components

Veda implementation: The renderer maps block names from Contentstack to React components in one central place.

That means the rendering flow looks roughly like this:

- fetch entry data


- read the modular block list


- inspect each block's type


- choose the matching React component


- render in order



A simplified sketch looks like this:

```typescript
const blockMap = {
  hero: Hero,
  list: List,
  media: Media,
};
```

That explicit mapping is one of the best habits you can take from Veda. It keeps the page builder model understandable.

## How the API shape becomes React props

Veda implementation: The components array in a page entry is transformed before rendering:

```typescript
export function mapComponentsToKV(components: Components[]): ComponentKV[] {
  return components.map((component) => {
    const entries = Object.entries(component) as [ComponentName, any][];
    const [name, props] = entries[0];
    return { name, props };
  });
}
```

That means an API block like this:

```json
{ "hero": { "title": "The Revival Collection" } }
```

becomes a renderer-friendly shape like this:

```json
{ "name": "hero", "props": { "title": "The Revival Collection" } }
```

That translation step is small, but it makes the rest of the rendering logic much cleaner.

## A product page example: using related data directly

Veda implementation: The components/Pages/Product.tsx file shows how the app consumes related data from the API shape:

```typescript
if (entry && "product_line" in entry && entry.product_line?.[0]) {
  breadcrumbLinks.push({
    title: entry.product_line[0].title,
    url: entry.product_line[0].url || "",
  });
}

<List
  reference={entry.product_line?.[0].products || []}
  title={`Explore ${entry.product_line?.[0].title}`}
  description={entry.product_line?.[0].description}
  load_first_image_eager={true}
  $={entry.$}
/>
```

This is a great example of why richer relational responses are useful. The product page can render:

- breadcrumb context


- related products from the product line


- more products from the current category



without a second hardcoded data source.

## Route handling and content handling stay close, but not tangled

Contentstack concept: The route layer should know how to ask for the right content. It should not contain the entire content access policy inline.

Veda gets this mostly right:

- routes call page utilities


- page utilities call focused fetchers


- fetchers talk to the SDK


- components render the results



That creates a clear chain of responsibility.

## The important distinction in this chapter

Here is the mental split to keep:

Contentstack concept: URL-driven fetching, structured content models, and modular block rendering are broadly portable ideas.

Veda implementation: The specific helpers, file names, block types, and route shapes are Veda's way of applying those ideas.

If you keep that distinction clear, you can learn from the repo without turning it into dogma.

## Key takeaways

- Veda initializes the Delivery SDK with region-aware configuration instead of relying on fragile hardcoded hosts


- Page routes fetch by content-aware URLs rather than by scattered entry IDs


- Rich include behavior helps Veda fetch connected page data in fewer steps


- Cached page utilities improve consistency across routes


- Metadata generation and modular block rendering are treated as first-class parts of the page system






---

## Frequently asked questions

### How does Veda initialize the Contentstack Delivery SDK across regions?

It derives the region from environment configuration and resolves delivery/preview hosts via centralized endpoint helpers. This avoids hardcoded hostnames and keeps preview configuration on the shared client.

### How does Veda fetch entries for routes without hardcoded entry UIDs?

Routes are resolved by querying Contentstack entries using a stored URL field (for example, querying the "page" content type where "url" equals the request path). The helper then unwraps the SDK result and uses the first matching entry.

### Why does Veda use include_all and include_all_depth in queries?

To fetch assets, references, and modular content in a single request when a page needs related data to render. This reduces follow-up requests and avoids incomplete payloads in the rendering layer.

### What problem do cached fetch helpers solve in Veda?

Wrapping key fetchers with React cache() improves repeatability and consistency across routes. It reduces the risk of missing shared query params, preview conditions, or other fetch policies in individual route files.

### How are modular blocks converted into React components?

Veda maps Contentstack modular block names to React components in a centralized block map. It also normalizes each block object into a { name, props } shape to make the renderer straightforward.



---

## Chapter Navigation

**← Previous:** [How Veda Is Structured](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/how-veda-is-structured)

**Next →:** [Live Preview and Visual Editor](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/live-preview-and-visual-editor)

---

## Step 3: Modeling navigation in Contentstack

- **Source:** https://developers.contentstack.com/guides/modeling-navigation-in-contentstack
- **Checkpoint:** Your navigation is modeled as content, not hardcoded

- **Authors:** Lo Etheridge
- **Published:** 2026-03-17T12:14:29.698Z
- **Updated:** 2026-11-10T16:27:24.930Z
- **Level:** Intermediate
- **Intent:** Learn
- **Tags:** content_modeling, api, visual_editing

---

This guide shows how to model navigation in Contentstack using content types, references, Global Fields, and Modular Blocks. You will build three navigation models that build on each other:

- Simple navigation: internal and external links


- Drop-down navigation: internal and external links under a parent item


- Mega menu: internal and external links, nested drop-down items, plus optional CTAs and images per item (not per column)



## When to use it

Use these patterns when:

- Marketing and product teams need to manage navigation without deploys


- Navigation must link to multiple internal page types (for example Page, Landing Page)


- You need predictable front-end rendering while keeping authoring simple



## Prerequisites

- A Contentstack stack with access to Content Types, Global Fields, and Modular Blocks


- At least two internal page content types (examples used below): Page and Landing Page


- A front end that can resolve referenced entries to URLs (via a url/slug field, or your routing layer)



## How it works

The core problem is modeling a “link” that can point to either:

- An internal entry (one of your page-like content types)


- An external URL



In Contentstack, you typically solve this by creating a reusable Link Global Field using a Modular Block with two mutually exclusive options: Internal and External. Navigation items then compose these links and add structure (drop-downs, mega menu content) around them.

### Assumptions used in this guide

- Internal destinations are references to specific page content types (for example Page and Landing Page).


- Each page type exposes a URL field (for example url or slug) that the front end can use.


- Navigation is modeled as a dedicated content type so it can be versioned, localized, and referenced by pages/layouts.



## Step by step

### Step 1 — Create a reusable Link Global Field

Create a Global Field named link. This will be reused across all navigation use cases.

#### Global Field: link

- label (Single line text, required)


- link (Modular Blocks, required) with blocks:



- internal

- entry (Reference, required; limit to: Page, Landing Page)


- open_in_new_tab (Boolean, default false)




- external

- url (Single line text, required)


- open_in_new_tab (Boolean, default true)





Authoring rule: allow exactly one block instance in link. This makes it explicit that a link is either internal or external.

#### Common pitfalls

- Allowing multiple blocks in the Link field. If authors can add both internal and external, your rendering logic becomes ambiguous.


- Not restricting reference content types. Keep internal links constrained to your page-like types to avoid “linking to anything”.



### Use case 1 — Simple navigation (internal + external links)

## What this does

Models a flat list of navigation items, where each item is a link (internal or external).

## When to use it

- Top bars and footers with one level of links


- Early project phase where you want a stable, minimal model



### Content Type: navigation_simple

- title (Single line text, required)


- items (Group, multiple, required)



#### Group: items[]

- item (Global Field: link, required)



### How it works

items[] is an ordered list. The front end renders each item as a single anchor based on whether the link is internal or external.

### Example entry shape (simplified)

```json
{
  "title": "Header nav",
  "items": [
    {
      "item": {
        "label": "Home",
        "link": [{ "internal": { "entry": { "uid": "home" }, "open_in_new_tab": false } }]
      }
    },
    {
      "item": {
        "label": "Docs",
        "link": [{ "external": { "url": "https://docs.example.com", "open_in_new_tab": true } }]
      }
    }
  ]
}
```

### Common pitfalls

- Missing ordering requirements. Confirm the field preserves order (Groups do) and render in that order.


- Assuming referenced entries include URL by default. Your delivery query needs to include the referenced fields required to build URLs.



### Next steps

Once flat navigation is stable, add drop-down behavior by allowing a parent item to optionally contain child links.

### Use case 2 — Drop-down navigation (internal + external links)

## What this does

Models top-level navigation items that can either be a direct link or a parent item containing a drop-down list of links.

## When to use it

- Header navigation with one drop-down level


- Information architecture where top-level categories expand into child links



### Approach

Use a single nav item structure where each top-level item can be one of:

- A direct link


- A drop-down with child links



### Global Field: nav_item_dropdown

Create a Global Field named nav_item_dropdown using a Modular Block. This keeps the entry shape explicit and avoids optional-field ambiguity.

- item (Modular Blocks, required; allow exactly one block) with blocks:



- link_item

- link (Global Field: link, required)




- dropdown_item

- label (Single line text, required)


- children (Group, multiple, required)





#### Group: dropdown_item.children[]

- link (Global Field: link, required)



### Content Type: navigation_dropdown

- title (Single line text, required)


- items (Group, multiple, required)



#### Group: items[]

- item (Global Field: nav_item_dropdown, required)



### How it works

- link_item renders as a standard navigation link.


- dropdown_item renders as a label (or button) that expands into children[].



### Example entry shape (simplified)

```json
{
  "title": "Header nav",
  "items": [
    {
      "item": {
        "item": [
          { "link_item": { "link": { "label": "Pricing", "link": [{ "internal": { "entry": { "uid": "pricing" } } }] } } }
        ]
      }
    },
    {
      "item": {
        "item": [
          {
            "dropdown_item": {
              "label": "Products",
              "children": [
                { "link": { "label": "Product A", "link": [{ "internal": { "entry": { "uid": "product-a" } } }] } },
                { "link": { "label": "API", "link": [{ "external": { "url": "https://api.example.com" } }] } }
              ]
            }
          }
        ]
      }
    }
  ]
}
```

### Common pitfalls

- Making both a link and children optional in the same object. That produces “sometimes link, sometimes group” logic that breaks validation and authoring.


- Not defining click behavior for drop-down labels. Decide whether the parent label is clickable or only toggles the menu. If clickable, model it as a link too (see next use case).



### Next steps

If you need richer navigation content (promos, CTAs, images) and deeper nesting, introduce a mega menu model that supports multiple item types and optional media per item.

### Use case 3 — Mega menu / complex navigation

## What this does

Models a navigation system that supports:

- Internal and external links


- Drop-downs with nested items


- Optional CTA and images per item (not per column)



## When to use it

- Large sites where navigation contains promoted items, editorial content, or visual tiles


- Multiple navigation “item types” in the same menu (link, group, promo)


- When you need explicit structure to keep rendering deterministic



### Approach

Use a single Navigation content type with a list of top-level items. Each item is a nav node with a specific type. Nodes can contain children, enabling nested structures. Promo content (CTA, image) is attached to nodes, not to columns.

### Global Field: nav_promo

Create a Global Field named nav_promo:

- eyebrow (Single line text, optional)


- description (Single line text or JSON RTE, optional)


- image (Asset, optional; restrict to images if your governance requires it)


- cta (Global Field: link, optional)



### Global Field: nav_node

Create a Global Field named nav_node using Modular Blocks (required; allow exactly one block). This enforces a single node type per item.

- node (Modular Blocks) with blocks:



- link_node

- link (Global Field: link, required)


- promo (Global Field: nav_promo, optional)




- dropdown_node

- label (Single line text, required)


- link (Global Field: link, optional; use if the parent label is clickable)


- items (Group, multiple, required)


- promo (Global Field: nav_promo, optional)





#### Group: dropdown_node.items[]

- item (Global Field: nav_node, required)



This recursion (a node containing a list of nodes) supports deeper nesting while keeping each level typed and predictable.

### Content Type: navigation

- title (Single line text, required)


- location (Dropdown, required; example values: header, footer)


- items (Group, multiple, required)



#### Group: items[]

- item (Global Field: nav_node, required)



### How it works

- Top-level items[] are rendered in order.


- Each item is either a link_node or dropdown_node.


- dropdown_node contains nested items[] of the same nav_node type, allowing multi-level menus.


- Any node can optionally carry promo (image + CTA + copy). This is per item, not per column.



### Example entry shape (simplified)

```json
{
  "title": "Header nav",
  "location": "header",
  "items": [
    {
      "item": {
        "node": [
          {
            "dropdown_node": {
              "label": "Solutions",
              "link": { "label": "All solutions", "link": [{ "internal": { "entry": { "uid": "solutions" } } }] },
              "promo": {
                "eyebrow": "New",
                "description": "See what’s new this quarter",
                "image": { "uid": "asset_uid" },
                "cta": { "label": "Explore", "link": [{ "internal": { "entry": { "uid": "whats-new" } } }] }
              },
              "items": [
                {
                  "item": {
                    "node": [
                      {
                        "link_node": {
                          "link": { "label": "E-commerce", "link": [{ "internal": { "entry": { "uid": "ecommerce" } } }] }
                        }
                      }
                    ]
                  }
                },
                {
                  "item": {
                    "node": [
                      {
                        "dropdown_node": {
                          "label": "Developers",
                          "items": [
                            {
                              "item": {
                                "node": [
                                  {
                                    "link_node": {
                                      "link": { "label": "API Docs", "link": [{ "external": { "url": "https://docs.example.com" } }] }
                                    }
                                  }
                                ]
                              }
                            }
                          ]
                        }
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
  ]
}
```

### Common pitfalls

- Unbounded depth. Recursive models are powerful, but teams often need a maximum depth (for example 2 or 3 levels) to keep UX and accessibility manageable. If you need a hard limit, enforce it in editorial guidelines and front-end validation.


- Promo content without rendering rules. Define where promos appear (for example right rail, inline tile) and what happens when both an image and CTA are missing.


- Overusing references for navigation nodes. Keep nodes embedded in the navigation entry unless you truly need node reuse across multiple navigations. Reference-heavy navigation increases query complexity and makes preview/debugging harder.


- Inconsistent internal URL resolution. Ensure all referenced page types expose the fields your router needs, and your query includes them.



## Next steps

- Define a routing contract for internal pages (for example each page type must have url).


- Add validation in your front end (or webhook) to enforce maximum depth and required fields per node type.


- Decide how navigation is selected per locale/site (for example one navigation entry per locale and location).





---

## Step 4: Querying content by taxonomy

- **Source:** https://developers.contentstack.com/guides/querying-content-by-taxonomy
- **Checkpoint:** Listings are filtered by taxonomy terms through the Delivery API

- **Authors:** Tim Benniks
- **Published:** 2026-11-18T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:21.262Z
- **Level:** Intermediate
- **Intent:** Build
- **Tags:** taxonomy, api, sdk

---

Most listing pages are a filter in disguise. "All beginner guides." "Everything about Next.js." "Blog posts in Europe, including the ones tagged Germany." Taxonomies let you express those filters once, in the stack, and query them from any content type with the same syntax.

This guide covers how taxonomy terms end up on entries, the query operators the Content Delivery API (CDA) supports, how to write them with the TypeScript Delivery SDK, and how developers.contentstack.com uses taxonomies to build its own filtered listings.

## What you'll learn

- How taxonomies, terms and entries relate


- How to filter entries by one term, several terms, or a combination of taxonomies


- How to query a term hierarchy with $eq_below, $below, $eq_above and $above


- How to query across content types with /taxonomies/entries


- How to write those queries with @contentstack/delivery-sdk


- When to filter in the query and when to filter in memory



## How taxonomies attach to entries

Contentstack concept: A taxonomy is a stack-level tree of terms. You create it once and attach it to any content type that needs it.

The taxonomy is not owned by a content type. If your stack has a level taxonomy with the terms beginner, intermediate and advanced, your guide, blogpost and kickstart content types can all use it. A term means the same thing everywhere, and a query for beginner works the same way on all three.

To use a taxonomy, add the Taxonomy field to a content type and pick which taxonomies editors can choose from. Editors then select terms in the entry editor. The entry stores its selection as a list of pairs:

```json
{
  "title": "Querying content by taxonomy",
  "taxonomies": [
    { "taxonomy_uid": "subjects", "term_uid": "taxonomy" },
    { "taxonomy_uid": "subjects", "term_uid": "api" },
    { "taxonomy_uid": "level", "term_uid": "intermediate" },
    { "taxonomy_uid": "intent", "term_uid": "build" }
  ]
}
```

The entry only stores UIDs. It does not store the term's position in the tree. That is why you can move a term to a different parent without rewriting every entry that uses it, and why hierarchical queries resolve the tree at query time.

If you are coming from WordPress, a taxonomy is close to a custom taxonomy with hierarchical terms. The difference is that in Contentstack you query it through the same API and query language you use for every other field.

## Filter on a single term

Every taxonomy query uses the field path taxonomies.<taxonomy_uid>. The simplest form matches entries that carry one term:

```bash
curl -G "https://cdn.contentstack.io/v3/content_types/guide/entries" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  --data-urlencode "environment=production" \
  --data-urlencode 'query={"taxonomies.level": "beginner"}'
```

This returns every published guide entry tagged beginner in the level taxonomy. Use your region's CDA host if your stack is not in AWS North America.

## Match any of several terms with $in

$in matches entries that carry at least one of the listed terms in a taxonomy:

```json
{ "taxonomies.subjects": { "$in": ["taxonomy", "content_modeling"] } }
```

This is the operator behind a multi-select filter where checking two subjects should widen the results, not narrow them.

## Combine taxonomies with $and and $or

$and and $or take a list of conditions. Use them to combine terms from different taxonomies:

```json
{
  "$and": [
    { "taxonomies.level": "beginner" },
    { "taxonomies.intent": "build" }
  ]
}
```

That query returns entries that are both beginner level and build intent. Swap $and for $or to get entries that match either condition.

Watch for: $in on one taxonomy is an OR between terms. $and across taxonomies is an AND between facets. A typical filter UI needs both: OR inside a facet, AND between facets.

## Find entries that use a taxonomy at all

$exists matches entries that have any term from a taxonomy:

```json
{ "taxonomies.level": { "$exists": true } }
```

Use it for listings like "everything that has a level", or to check how many entries of a content type are tagged at all.

## Query a term hierarchy

Taxonomies are trees, and four operators let you query along the tree. Take a region taxonomy where europe has the children germany and france, and germany has the child berlin.

Operator

Matches entries tagged with

Example with europe or berlin

$eq_below

The term or any term below it

europe, germany, france, berlin

$below

Only the terms below it

germany, france, berlin

$eq_above

The term or any term above it

berlin, germany, europe

$above

Only the terms above it

germany, europe

All four accept an optional levels value that limits how far the query walks:

```json
{ "taxonomies.region": { "$eq_below": "europe", "levels": 1 } }
```

With levels: 1, the query matches europe, germany and france, but not berlin. If you leave levels out, the API walks up to 10 levels, which is also the maximum depth of a taxonomy.

$eq_below is the operator you want for landing pages. A page for "Europe" should show content tagged with any European country without you listing every country in the query.

## Query across content types

The examples above query one content type. To query every content type that uses a taxonomy, call the taxonomies entries endpoint with the same query syntax:

```bash
curl -G "https://cdn.contentstack.io/v3/taxonomies/entries" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  --data-urlencode "environment=production" \
  --data-urlencode 'query={"taxonomies.level": {"$in": ["beginner"]}}'
```

This returns guides, blog posts and any other content type tagged beginner in one response. It is the cheapest way to build a "start here" page that mixes formats.

## Write the queries with the TypeScript Delivery SDK

The TypeScript Delivery SDK writes taxonomy filters with the same methods you use for other fields. Field paths with dots are valid, so taxonomies.level works like any field UID.

```typescript
import contentstack, {
  QueryOperation,
  TaxonomyQueryOperation,
} 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!,
});

// Single term
const beginnerGuides = await stack
  .contentType("guide")
  .entry()
  .query()
  .where("taxonomies.level", QueryOperation.EQUALS, "beginner")
  .find();

// Any of several terms ($in)
const modelingPosts = await stack
  .contentType("blogpost")
  .entry()
  .query()
  .containedIn("taxonomies.subjects", ["taxonomy", "content_modeling"])
  .find();

// Term and everything below it, two levels deep
const europe = await stack
  .contentType("article")
  .entry()
  .query()
  .where("taxonomies.region", TaxonomyQueryOperation.EQ_BELOW, "europe", { levels: 2 })
  .find();
```

The fourth argument of where() merges extra keys into the condition, which is how levels ends up next to $eq_below. exists("taxonomies.level") gives you $exists: true.

For $and and $or, build sub-queries and pass them to and() or or():

```typescript
const guides = stack.contentType("guide").entry();

const result = await guides
  .query()
  .and(
    guides.query().where("taxonomies.level", QueryOperation.EQUALS, "beginner"),
    guides.query().where("taxonomies.intent", QueryOperation.EQUALS, "build")
  )
  .find();
```

### Cross-type queries from TypeScript

stack.taxonomy() without a UID returns a TaxonomyQuery. In recent 5.x versions of the SDK, calling find() on it lists the stack's published taxonomies. It does not return entries, and it ignores conditions you added with where(). Check the behavior of the version you run. When you need entries from several content types in one call, a plain fetch against /v3/taxonomies/entries is short and predictable:

```typescript
const CDA_HOST = process.env.CONTENTSTACK_CDA_HOST ?? "https://cdn.contentstack.io";

export async function findEntriesByTaxonomy(query: Record<string, unknown>) {
  const params = new URLSearchParams({
    environment: process.env.CONTENTSTACK_ENVIRONMENT!,
    query: JSON.stringify(query),
  });

  const response = await fetch(`${CDA_HOST}/v3/taxonomies/entries?${params}`, {
    headers: {
      api_key: process.env.CONTENTSTACK_API_KEY!,
      access_token: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
    },
  });

  if (!response.ok) {
    throw new Error(`Taxonomy query failed: ${response.status}`);
  }

  return (await response.json()) as { entries: Record<string, unknown>[] };
}

const { entries } = await findEntriesByTaxonomy({
  "taxonomies.level": { "$in": ["beginner"] },
});
```

## Worked example: filtered listings on this site

developers.contentstack.com tags blog posts, guides, kickstarts and live streams with four taxonomies: subjects, technology, intent and level. Those terms drive the cards on listing pages, the level and intent filters on /search, and the level and intent lines in each page's markdown frontmatter.

Listing pages are built from a List block in the CMS. Its custom_card_query group holds the content type, a set of term UIDs, a limit, a sort order and a show_filters toggle. Editors build "All beginner guides" without a deploy.

Here is a simplified version of the server-side query for one List block. It fetches only the fields a card needs and filters by terms in the query:

```typescript
import { stack } from "./config";

const CARD_FIELDS = ["title", "url", "date", "taxonomies"];

interface CardQuery {
  contentType: "guide" | "blogpost";
  taxonomyUid: string;
  terms: string[];
  limit: number;
}

export async function getCards({ contentType, taxonomyUid, terms, limit }: CardQuery) {
  const query = stack
    .contentType(contentType)
    .entry()
    .only(CARD_FIELDS)
    .query()
    .orderByDescending("date")
    .limit(limit);

  if (terms.length > 0) {
    query.containedIn(`taxonomies.${taxonomyUid}`, terms);
  }

  const result = await query.find();
  return result.entries ?? [];
}
```

Because the filter runs in the query, limit() returns the right slice. Filter after the query instead and a limit of 10 can leave you with three cards.

The /search page takes a different route on purpose. It shows a count next to every level, intent, subject and technology term, and it updates those counts as you combine filters. A taxonomy query returns matching entries, not counts per term. So the site fetches one small dataset per content type (title, URL, taxonomies and a few card fields) and filters and counts in memory:

```typescript
type Entry = { taxonomies?: { taxonomy_uid: string; term_uid: string }[] };

function termsOf(entry: Entry, taxonomyUid: string) {
  return (entry.taxonomies ?? [])
    .filter((t) => t.taxonomy_uid === taxonomyUid)
    .map((t) => t.term_uid);
}

function countTerms(entries: Entry[], taxonomyUid: string) {
  const counts = new Map<string, number>();
  for (const entry of entries) {
    for (const term of termsOf(entry, taxonomyUid)) {
      counts.set(term, (counts.get(term) ?? 0) + 1);
    }
  }
  return counts;
}
```

That trade-off works because the content set is small: a few lean requests return every entry, and the server filters and counts in memory for each search. On a large catalog, filter in the query and get counts from a search index instead.

flowchart TD  A[Need a filtered list] --> B{Need counts per term?}  B -- No --> C{One content type?}  C -- Yes --> D[content_types/uid/entries with a taxonomy query]  C -- No --> E[taxonomies/entries with a taxonomy query]  B -- Yes --> F{Small dataset?}  F -- Yes --> G[Fetch minimal fields once, filter and count in memory]  F -- No --> H[Use a search index for facets]## Where people get confused

### Term UIDs versus term names

Queries use term UIDs, not the labels editors see. If an editor renames "Beginner" to "Getting started", the UID stays beginner and your queries keep working. Hardcode UIDs, never labels.

### Filtering after the query

Filtering in application code after a limit() drops results silently. Either filter in the query or fetch enough entries to cover the filter.

### Taxonomies and references

A taxonomy term is a label, not an entry. It has no fields of its own to render, so you do not need includeReference() to read taxonomy_uid and term_uid from an entry. If you need rich content per category (a description, an image, a landing page), model that as a content type and reference it. The [modeling decision guide](/guides/modular-blocks-references-or-global-fields) covers when to pick which.

## Limits to remember

- An entry can hold up to 25 terms. A Taxonomy field can set a lower maximum per taxonomy.


- A taxonomy can hold up to 10,000 terms, nested up to 10 levels deep.


- The number of taxonomies per stack depends on your plan.


- Queries go in the URL, and the CDA has an 8 KB URL limit. A long $in list or many $or branches can hit it.



## Key takeaways

- Taxonomies live at the stack level. One query syntax works across every content type that uses them.


- Filter with taxonomies.<taxonomy_uid>: a plain value for one term, $in for any of several, $and/$or to combine taxonomies, $exists for audits.


- Use $eq_below with levels for landing pages that cover a branch of the tree.


- Use /v3/taxonomies/entries to query across content types. In recent SDK versions, call it with fetch rather than stack.taxonomy().find().


- Filter in the query when you use limit(). Count in memory or in a search index when the UI needs facet counts.



## Next steps

- Read [Taxonomies are your query layer](/blog/taxonomies-are-your-query-layer) for why this site models its learning content with four taxonomies.


- Follow the [Personalize your site](/paths/personalize-your-site) path to combine taxonomy queries with personalized listings.


- Revisit [rewriting queries for the TypeScript Delivery SDK](/guides/migrating-from-the-javascript-delivery-sdk-to-the-typescript-delivery-sdk/rewrite-queries-pagination-sorting-and-field-selection) for the rest of the query API.





---

## Do this with AI

Install the cms-taxonomy and dx-delivery-sdk skills from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Content Explorer profile in MCP Profile Hub. Then ask your agent:

> Find all blog_post entries classified under any term in the frameworks taxonomy, child terms included, and write the Delivery SDK query that returns the same list.

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




---

## Frequently asked questions

### Are taxonomies defined per content type?

No. A taxonomy lives at the stack level. You attach it to as many content types as you want, and every one of them shares the same terms.

### Which endpoint queries entries across content types by taxonomy?

GET /v3/taxonomies/entries with a query parameter. Per content type, use the normal /v3/content_types/{uid}/entries endpoint with the same query syntax.

### What does levels do in $eq_below and $below?

It limits how many levels of the hierarchy the operator walks. If you leave it out, the API walks up to 10 levels.

### Can a taxonomy query return facet counts?

No. A taxonomy query returns matching entries. If you need counts per term for a filter UI, count them yourself from the entries you fetched.


---

## Step 5: Building a Multi-Language Website Using Contentstack and Next.js i18n

- **Source:** https://developers.contentstack.com/guides/building-a-multi-language-website-using-contentstack-and-next-js-i18n
- **Checkpoint:** Your site serves localized content with i18n routing

- **Authors:** Lo Etheridge
- **Published:** 2026-03-17T12:14:29.882Z
- **Updated:** 2026-11-10T16:27:10.533Z
- **Level:** Intermediate
- **Intent:** Build
- **Tags:** content_modeling, next

---

Delivering content in a single language is no longer sufficient. Users expect personalized experiences that literally "speak their language" with cultural context or localization. This tutorial explores how to build a multilingual blog site using Contentstack and Next.js, a React framework that handles language-based routing out of the box. You'll learn to connect Next.js and Contentstack to build a blog supporting multiple languages.

Internationalization (i18n) refers to designing your application to adapt easily to different languages and regions, while localization (i10n) entails translating and adapting content for specific locales. Supporting multiple languages can be complex, but using the right tools streamlines the process. In this article, you will discover how to use Contentstack and [Next.js](https://www.contentstack.com/docs/developers/sample-apps/build-a-starter-website-using-next-js-and-contentstack) to build a multi-lingual blog site.

## What is Contentstack

Contentstack is a Digital Experience Platform (DXP) comprising a CMS and tools for personalization, automations, and AI. It decouples content storage from presentation, delivering it over APIs ([REST](https://www.contentstack.com/blog/tech-talk/graphql-vs-rest-api-which-is-better-for-querying-data) or [GraphQL](https://www.contentstack.com/docs/developers/graphql-api)). Its localization features allow you to define multiple locales and manage translations, delivering dynamic content based on language or region.

## What is Next.js

Next.js is a React framework for fast, scalable web apps, offering server-side rendering (SSR), static site generation (SSG), file-based routing, and internationalization (i18n). It enables high performance and SEO while integrating seamlessly with Contentstack to render localized content efficiently.

## Multi-language website tutorial

This tutorial explains how to connect Next.js and Contentstack to build a multilingual blog site.

## 1. Project setup

### Prerequisites

- Install [Node](https://nodejs.org/en) v22 or greater


- Create a [Contentstack account](https://www.contentstack.com/)


- Basic Next.js knowledge is helpful but not required.



### Initializing your Next.js app

Run the following command to create a new Next.js app:

```
npx create-next-app@latest my-contentstack-blog && cd my-contentstack-blog
```

During setup, follow the recommended options. The app's routes will live in the app folder, with page.js as the home page.

![](https://images.contentstack.io/v3/assets/blt77d44a06c81b1730/blt440a22d2e0c4b4f4/68a4f007b3d99b4a1cda124b/Sullivan1-CAP.png)

## Setting up UI components

Create a components folder for shared UI elements, such as a Header component.

```javascript
export default function Header() {
  return (
    <header classname="p-4 bg-gray-100">
      <h1 classname="text-2xl font-bold">Contentstack Blog</h1>
    </header>
  );
}
```

Now, update page.js .

```
import Header from "@/components/Header";

export default function Home() {
  return (
    <div classname="grid grid-rows-[20px_1fr_20px] items-center justify-items-center min-h-screen p-8 pb-20 gap-16 sm:p-20 font-[family-name:var(--font-geist-sans)]">
      <header>
        <div classname="flex flex-col items-center justify-center">
          <h1 classname="text-4xl font-bold mb-4">
            Welcome to Contentstack Blog
          </h1>

          <p classname="text-lg text-gray-700 mb-8">
            Discover the latest articles and insights from our team.
          </p>
        </div>

        <footer classname="text-center text-gray-500">
          © 2025 Contentstack. All rights reserved.
        </footer>
      </header>
    </div>
  );
}
```

### Previewing the Home page

Run npm run dev and preview the home page at http://localhost:3000/.

## 2. Configuring localization in Contentstack

### Creating a new stack

From your Contentstack dashboard, create a new stack as your project's content space.

### Enabling multiple languages

Under Settings > Languages, add Spanish so you have both English and Spanish, with English as fallback.

IMAGE HERE

### Creating an Environment

Create an environment (e.g., example-blog) to publish content to.

IMAGE HERE

## 3. Defining content types and add entries

### Creating content types

Under Content Models, add a content type called Article (type: Multiple). Use fields title (default) and a multi-line content field. Save and start adding entries.

IMAGE HERE

### Adding sample entries in multiple languages

Add an article in English and then use the language dropdown to add the Spanish version. Publish to make the localized entries available.

IMAGE HERE

## 4. Setting up i18n in Next.js

### Using App router for localization

Create a new directory [lng] in app/ representing each locale. Move the home page and add a [blogId]/page.tsx file for articles:

```
- 📁 app/
  - 📁 [lng]/
    - 📄 page.tsx
    - 📁  [blogId]/
      - 📄 page.tsx
```

## 5. Connecting Contentstack with Next.js

You can use the Contentstack JavaScript [SDK](https://www.contentstack.com/docs/developers/sdks) or REST API. Install the SDK:

`npm install contentstack`Initialize it in lib/contentstack.js with your API credentials (see documentation for guidance).

### Handling locale mapping

Create a utility function to map Next.js locales (en, es) to Contentstack codes:

```
export function toContentstackLocale(locale) {
  return locale === "en" ? "en-us" : locale;
}
```

## 6. Fetching and display content

Write a helper fetchArticles that fetches articles by locale from Contentstack. Use this function in your homepage component to display article links. Update your frontend to route links by language and article ID.

## Implementing middleware for language detection

To automatically detect and redirect users based on their browser language, create middleware.js to route them to the correct localized path.

### Update Homepage to display Articles

Update app/page.js to display fetched articles for the current locale, linking to the detailed blog pages.

![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXfp-5jh-cu5DLtnCvx_Vxo-gRvCG9OW0E4TxC_KAHVgwEUzDUeSCNecCV7ESzDyQrYjAZ55PXI2ltFSAsm2dHhI5nEdJEdbIWi6d-HEqyzs9Ee6XChrOsBHF1X3ia-P4o9kZAf1?key=qRMmvzh2tjIfIKSBYBDUtQ)

## 7. Creating Article pages

Make a fetchSingleArticle helper to get a specific article by ID and locale. Use this in [blogId]/page.js to render individual posts per language.

## 8. Preview and test application

Change the URL’s language code to see different localized content. Clicking an article link fetches the correct version.

![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXeFT5BgEA4C-yGe2_dtud78p09aQmya1cdeQvCeXaUsqKUWxeliEvmORVzpwkdb0QEzcqU3NZnRkqYSdCHO9CPG_H9eCwN7-6I4X126YHxi8RJ35irIKByvmNLUtnnepG1ccE-T?key=qRMmvzh2tjIfIKSBYBDUtQ)

You've now built a basic multilingual blog, set up localized routing and content in Contentstack, and configured Next.js for i18n.

## Tips and best practices

### Use fallback languages

Always use fallback content to prevent empty pages. Contentstack handles this automatically based on your fallback settings.

### Handle untranslated content clearly

Flag untranslated entries for editors and display a "not available" message on the frontend when content is missing.

### Structure content types for reusability

Use modular fields in Contentstack to minimize duplication and only translate necessary content.

### SEO for localized routes

Reflect locale in your URLs (e.g., /en/article1, /es/article1). Use the [hreflang](https://ahrefs.com/seo/glossary/hreflang) tag to help search engines serve the right language.

## Contentstack + Next.js = powerful multi-lingual applications

Combining Contentstack and Next.js delivers flexible, scalable, high-performance, multi-language applications with ease of management for global teams and editors.

### About Contentstack

The [Contentstack team](https://www.contentstack.com/blog/author/the-contentstack-team) specializes in product marketing, acquisition, retention, and digital strategies, offering solutions for leading global brands. In 2025, Contentstack was recognized as a Visionary in the Gartner Magic Quadrant for DXP and as a Leader in the Forrester Wave CMS report. Follow [Contentstack on LinkedIn](https://www.linkedin.com/company/contentstack/mycompany/).



---

## Frequently asked questions

### How do I add additional languages beyond English and Spanish to my Contentstack project?

Go to Settings > Languages in Contentstack and add your desired languages. You can then localize content for each language and set a fallback for missing translations.

### How does Next.js handle localization and routing for multiple languages?

Next.js uses its App Router and folder structure to easily create separate routes per locale. Each locale is represented by a directory (e.g., [lng]) and dynamic routing loads content for the correct language.

### Why use the Contentstack SDK instead of REST API directly?

The Contentstack JavaScript SDK simplifies fetching and managing content, handling authentication and requests for you, while the REST API offers more control if needed.


---

## Step 6: The Ultimate Guide to Contentstack Visual Editor

- **Source:** https://developers.contentstack.com/guides/the-ultimate-guide-to-contentstack-visual-building
- **Checkpoint:** Live Preview and Visual Editor work for your rendering mode

- **Authors:** Tim Benniks, Lo Etheridge
- **Published:** 2026-03-31T22:00:00.000Z
- **Updated:** 2026-11-10T16:27:26.892Z
- **Level:** Intermediate
- **Intent:** Learn
- **Tags:** content_modeling, visual_editing, headless, sdk

---

> **Full guide available:** [View all 8 chapters in one document](https://developers.contentstack.com/guides/the-ultimate-guide-to-contentstack-visual-building/full.md)

Everything you need to build bulletproof real-time preview experiences.

Live Preview creates a continuous feedback loop where editors see their changes materialize instantly. This guide gives you the mental models and practical knowledge to implement it correctly, debug it when things break, and adapt it to any rendering strategy.

## What You'll Build

This guide uses the [Contentstack Next.js Kickstart](https://github.com/contentstack/kickstart-next) as a running example. For a variant that routes all content through a middleware API layer (keeping tokens server-side), see the [Next.js Middleware Kickstart](https://github.com/contentstack/kickstart-next-middleware). By the end, you'll understand every line across these four files.

lib/contentstack.ts configures the SDK, initializes Live Preview, and fetches content:

```typescript
import contentstack, { QueryOperation } from "@contentstack/delivery-sdk";
import ContentstackLivePreview, { IStackSdk } from "@contentstack/live-preview-utils";

// Delivery SDK instance: when the live preview hash is present, requests go to the Preview API (drafts).
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,
  live_preview: {
    enable: true,
    preview_token: process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN,
    host: "rest-preview.contentstack.com",
  },
});

// Run in the browser only. Wires the iframe session to your stack and enables Visual Editor chrome.
export function initLivePreview() {
  ContentstackLivePreview.init({
    ssr: false, // CSR: refetch in place instead of full reloads
    mode: "builder",
    stackSdk: stack.config as IStackSdk, // So the SDK can inject hash + content type context
    stackDetails: { apiKey: "...", environment: "..." },
    editButton: { enable: true },
  });
}

export async function getPage(url: string) {
  const result = await stack
    .contentType("page").entry().query()
    .where("url", QueryOperation.EQUALS, url)
    .find();
  const entry = result.entries?.[0];
  // Populates `entry.$` with data-cslp props for click-to-edit in preview
  if (entry) contentstack.Utils.addEditableTags(entry, "page", true);
  return entry;
}
```

components/Preview.tsx runs the Live Preview loop, refetching content on every editor change:

```typescript
"use client";
import { useState, useEffect, useCallback } from "react";
import ContentstackLivePreview from "@contentstack/live-preview-utils";
import { getPage, initLivePreview } from "@/lib/contentstack";
import Page from "./Page";

export default function Preview({ path }: { path: string }) {
  const [page, setPage] = useState();
  const getContent = useCallback(async () => {
    setPage(await getPage(path)); // Preview API returns latest draft for current hash
  }, [path]);

  useEffect(() => {
    initLivePreview();
    // Fires on every editor change in the stack UI → refetch → re-render
    ContentstackLivePreview.onEntryChange(getContent);
  }, [path]);

  if (!page) return <p>Loading...</p>;
  return <Page page={page} />;
}
```

components/Page.tsx renders content with edit tags so editors can click any element to jump to its field:

```typescript
import { VB_EmptyBlockParentClass } from "@contentstack/live-preview-utils";

export default function ContentDisplay({ page }: { page: Page | undefined }) {
  return (
    <main>
      {/* Spreads add data-cslp (and related attrs) so Visual Editor can target each field */}
      <h1 {...page.$?.title}>{page?.title}</h1>

      {/* VB_EmptyBlockParentClass marks the modular-blocks container when empty so VB can add blocks */}
      <div className={`blocks ${VB_EmptyBlockParentClass}`} {...page.$?.blocks}>
        {page?.blocks?.map((item, index) => (
          <section key={index} {...page.$?.[`blocks__${index}`]}>
            <h2 {...item.block.$?.title}>{item.block.title}</h2>
          </section>
        ))}
      </div>
    </main>
  );
}
```

app/page.tsx routes between preview and production:

```typescript
import { getPage, isPreview } from "@/lib/contentstack";
import Page from "@/components/Page";
import Preview from "@/components/Preview";

export default async function Home() {
  // Preview session: client wrapper subscribes to Live Preview; production: one server fetch
  if (isPreview) return <Preview path="/" />;
  const page = await getPage("/");
  return <Page page={page} />;
}
```

The first file connects to Contentstack and sets up preview credentials. The second subscribes to editor changes and refetches on every keystroke. The third renders content with data-cslp edit tags and VB_EmptyBlockParentClass for empty modular blocks. The fourth decides which rendering path to use.

## Who This Guide Is For

- Frontend developers implementing Live Preview across CSR, SSR, or SSG architectures


- Full-stack engineers working with middleware, BFFs, and database-backed content systems


- Technical architects evaluating Live Preview for enterprise deployments


- Anyone debugging a Live Preview issue who wants to isolate problems systematically



## Guide Structure

### Foundations

- [1. How Live Preview Works](/guides/the-ultimate-guide-to-contentstack-visual-building/how-live-preview-works) - The mental model, architecture, session lifecycle, and APIs



### Rendering Strategies

- [2. Client-Side Rendering](/guides/the-ultimate-guide-to-contentstack-visual-building/client-side-rendering) - SDK setup, subscriptions, and refetch patterns for SPAs


- [3. Server-Side Rendering](/guides/the-ultimate-guide-to-contentstack-visual-building/server-side-rendering) - Reload-based preview, request-scoped clients, hash propagation


- [4. Static Site Generation](/guides/the-ultimate-guide-to-contentstack-visual-building/static-site-generation) - Preview mode, framework escape hatches


- [5. Middleware and Complex Architectures](/guides/the-ultimate-guide-to-contentstack-visual-building/middleware-and-database-backed-architectures) - BFF, edge middleware, database caching



### Advanced Features

- [6. Edit Tags and Visual Editor](/guides/the-ultimate-guide-to-contentstack-visual-building/edit-tags-and-visual-editor) - Click-to-edit, field paths, Visual Editor integration



### Operations

- [7. Debugging and Best Practices](/guides/the-ultimate-guide-to-contentstack-visual-building/debugging-pitfalls-and-best-practices) - Systematic debugging, common pitfalls, checklists



## Prerequisites

Before diving in, you should have:

- A working Contentstack stack with content types and entries


- A frontend application (any framework) that fetches and renders Contentstack content


- Basic familiarity with your framework's data fetching and rendering


- Access to your stack's Settings to enable Live Preview and generate preview tokens



### Enabling Live Preview in Your Stack

Enable Live Preview in your stack settings, set a default preview environment, and add base URLs for each locale in your environment configuration. For step-by-step instructions, see the [official setup guide](https://www.contentstack.com/docs/developers/set-up-live-preview/set-up-live-preview-for-your-website).

Optionally, enable the "Display Setup Status" toggle for real-time configuration feedback during setup. Enable "Always Open in New Tab" if you run SDK v4.0.0+ to preview outside the iframe.

## What's Next

You now have the prerequisites in place and basic configuration done. Next, lets take a quick deep dive into how Live Preview works and how it works with different rendering strategies. Proceed to [How Live Preview Works](/guides/the-ultimate-guide-to-contentstack-visual-building/how-live-preview-works) to get started.


---

## Step 7: Customizing Veda for your own project

- **Source:** https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/customizing-veda-for-your-own-project
- **Checkpoint:** The starter is branded and shaped for your own project

- **Authors:** Tim Benniks, Lo Etheridge
- **Published:** 2026-04-07T10:58:05.856Z
- **Updated:** 2026-11-10T16:27:12.138Z
- **Level:** Intermediate
- **Intent:** Build

---

By now, you should understand enough to avoid the two common bad outcomes: either treating Veda as untouchable, or tearing it apart so quickly that you destroy the patterns that made it useful in the first place. This chapter is about customizing with intent.

## What you'll learn

- Which changes are safe to make first


- How to replace brand-specific content without destabilizing the architecture


- How to extend content types and modular blocks deliberately


- How to adapt route behavior while keeping content contracts clear


- How to preserve preview and editorial workflows while evolving the starter



## Start with the lowest-risk customizations

Veda implementation: The safest first wave of changes is usually content and branding, not architecture.

That includes:

- replacing copy


- replacing images and visual branding


- renaming product lines and categories


- updating navigation content


- adjusting seeded entries to fit your domain



This lets your team get comfortable with the content model and editorial workflow before changing the app's structural assumptions.

## Then decide what should stay generic and what should become project-specific

Contentstack concept: Not every content type should remain as it is in the starter.

Ask:

- Are your "products" really products, or are they case studies, destinations, or services?


- Do you need product_line, or would another grouping concept make more sense?


- Should the current page type remain your flexible page-builder type?


- Which block types are truly reusable in your domain?



The goal is not to preserve Veda terminology forever. The goal is to preserve the quality of the modeling decisions.

## Add new modular blocks carefully

Veda implementation: When you add a new modular block, there are usually at least three responsibilities to update:

- the content model definition in Contentstack


- the frontend component that renders the block


- the central component mapping layer



If you only do one of these, the system becomes inconsistent.

Production note: The central renderer is your friend here. It gives you one obvious place to wire in new block types and one obvious place to fail loudly if the frontend does not yet support a newly modeled block.

## Evolve routes only after content assumptions are clear

Contentstack concept: Routes are a contract between the frontend and the content model.

If you change URL strategy, revisit:

- which content type owns the URL


- how routes derive paths


- which fetchers query by that URL


- how metadata is generated


- how preview identifies the correct content type for the current page



This is why route changes should usually happen after, not before, you understand the current model.

## Keep preview support intact while you customize

Veda implementation: It is easy to break preview accidentally by focusing only on visible UI changes.

Watch these areas closely:

- editable bindings on rendered fields


- empty-state wrappers for modular regions


- preview-aware fetchers


- the preview wrapper's content-type routing logic



If you rename content types or add new previewable page types, update the preview orchestration layer deliberately.

## Recommended customization sequence

If you want to change Veda without losing its strengths, use this order:

- update content and branding


- validate the content model against your real domain


- rename or reshape content types if needed


- add or remove block types


- adjust route strategy


- revisit preview and metadata behavior


- optimize performance and deployment details



That order keeps the risk lower because each stage builds on a stable earlier stage.

## What to keep even if your domain changes completely

Even if your project is not remotely commerce-shaped, these are still worth preserving:

- centralized SDK setup


- focused content fetchers


- a page utility layer


- an explicit modular block renderer


- preview as a dedicated runtime mode


- route-aware metadata generation



Those are architectural strengths, not jewelry-store-specific decisions.

## What to throw away without guilt

You do not need to keep:

- the brand story


- the exact content type names


- the category and product semantics


- the visual design


- any route pattern that no longer matches your domain



The rule is simple: keep the good abstractions, not the accidental branding.

## Key takeaways

- Start by changing content and branding before you change architecture


- Preserve the quality of the modeling decisions even if you rename the domain concepts


- Add new modular blocks by updating both the content model and the frontend renderer


- Treat route changes as content contract changes, not only page file changes


- Review preview support explicitly whenever content types, blocks, or routes evolve






---

## Frequently asked questions

### What are the lowest-risk changes to make first when customizing Veda?

Start with content and branding updates: copy, images, navigation content, and seeded entries. Avoid architectural changes until the team understands the model and workflow.

### How do you add a new modular block without breaking consistency?

Update three places together: the Contentstack content model, the frontend rendering component, and the central component mapping layer. Missing any one creates mismatches between authored content and rendering.

### Why should route changes happen after content assumptions are clear?

Routes are a contract between the frontend and the content model. Changing URL strategy affects which type owns the URL, how fetchers query, metadata generation, and how preview resolves the current page.

### What commonly breaks Contentstack preview during customization?

Preview often breaks when editable bindings, empty-state wrappers, preview-aware fetchers, or preview routing logic are not updated after renaming content types or adding new page types.

### What parts of Veda are worth keeping even if the domain changes completely?

Keep the architectural abstractions: centralized SDK setup, focused fetchers, page utilities, an explicit block renderer, preview as a dedicated runtime mode, and route-aware metadata generation.



---

## Chapter Navigation

**← Previous:** [Live Preview and Visual Editor](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/live-preview-and-visual-editor)

**Next →:** [Production readiness, troubleshooting, and next steps](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/production-readiness-troubleshooting-and-next-steps)

---

## Step 8: Safe content model changes with branches and aliases

- **Source:** https://developers.contentstack.com/guides/safe-content-model-changes-with-branches-and-aliases
- **Checkpoint:** You change content types on a branch and switch the frontend with an alias

- **Authors:** Tim Benniks
- **Published:** 2026-11-22T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:25.494Z
- **Level:** Intermediate
- **Intent:** Ship
- **Tags:** cli, content_modeling, automation

---

Changing a content type on a live stack is the riskiest thing most teams do in Contentstack. Delete a field and every entry loses that data. Rename one and your frontend breaks until the next deploy. Branches give you a place to make those changes in isolation, and aliases let you switch the frontend to the new model without touching your code.

This guide walks through the full loop: fork a branch from main, change the model with a migration script, diff it, merge it back, and decide when to repoint an alias instead. At the end you have a CI workflow that runs the same steps on every pull request.

## What you'll learn

- How branches and aliases relate to each other


- Which modules a branch copies and which stay global


- How to script content type changes with cm:stacks:migration


- How to diff and merge branches with the CLI and the API


- When to merge and when to repoint an alias


- How to scope tokens and run the flow from CI



## Branches, aliases, and how they fit together

Contentstack concept: A branch is an isolated copy of a stack's content model and content. Every stack starts with a main branch, and you fork new branches from main or from any other branch.

If you are coming from Git, the mental model is close. You branch off main, make changes, compare, and merge back. The difference is what merges: Contentstack merges content types and global fields, not entries. More on that below.

Contentstack concept: An alias is a named pointer to one branch. Your frontend reads from the alias, for example production, instead of a branch UID. Repointing the alias to another branch changes what the frontend renders without a code change or a redeploy.

Think of an alias as a symlink. The frontend always opens the same path. You decide where it points.

flowchart LR  A[main] -->|fork| B[model-v2]  B -->|migration script| B  B -->|cm:branches:diff| C{Ship how?}  C -->|merge into main| A  C -->|repoint alias| D[alias: production]  A -.->|today| D## What a branch copies and what stays global

A new branch inherits the content of its source branch. Changes on the child do not touch the parent, and the other way around. Not everything is branch-scoped, though, and that list matters more than people expect.

Branch-specific

Global across all branches

Content types and global fields

Taxonomies and terms

Entries and assets

Environments

Languages

Users and roles

Extensions

Delivery and management tokens (scoped to branches or aliases)

Releases and the publish queue

Webhooks (you pick which branch triggers each one)

Labels

Workflows and publish rules (you pick which branches they apply to)

Audit logs and global search

Marketplace apps

The one that catches people most often is taxonomies. They are global. If your model change on a branch includes new taxonomy terms, adding those terms changes every branch, including the one your production site reads from. That is usually harmless, since unused terms do nothing, but deleting or moving a term is not something you can test in isolation.

When you create a branch you also choose which environments to clone: all of them, none, or a specific set. Cloning an environment copies its published content into the new branch, so the branch can serve real content the moment you point an alias at it.

## Create a branch from main

Create the branch with the CLI. The --uid is the branch name, and --source is the branch you fork from.

```bash
csdx cm:branches:create --source main --uid model-v2 -k <stack-api-key>
```

Branch creation runs in the background. List the branches to see when it is ready:

```bash
csdx cm:branches -k <stack-api-key> --verbose
```

The verbose table shows each branch with its source and aliases. Creating a branch requires a user session (an authtoken), so run this as a logged-in user, not with a management token.

## Change the model with a migration script

You can edit content types in the UI on the new branch, and for exploration that is fine. For anything you want to repeat, review, or run in CI, write a migration script. The cm:stacks:migration command runs a JavaScript file against a branch and gives you a small API for content types and fields.

Here is a script that adds a summary field to the blog_post content type and moves it below the title:

```javascript
// migrations/01-add-blog-summary.js
module.exports = ({ migration }) => {
  const blogPost = migration.editContentType('blog_post');

  blogPost
    .createField('summary')
    .display_name('Summary')
    .data_type('text')
    .mandatory(false);

  blogPost.moveField('summary').afterField('title');
};
```

Run it against the branch, never against main:

```bash
csdx cm:stacks:migration \
  --file-path ./migrations/01-add-blog-summary.js \
  --branch model-v2 \
  -k <stack-api-key>
```

To run every script in a folder, pass --multiple with the folder path. Prefix the filenames with numbers so the order is obvious when you read them, and keep each script small so a failure points at one change.

Migration scripts stay safe when you follow these rules:

- Add before you remove. A new optional field never breaks a frontend. A deleted field does.


- Keep new fields optional until existing entries have values, or the next save on every old entry fails validation.


- Treat the script as code. Commit it, review it, and run it on a branch first.



The command runs your file with Node and with your own permissions, so only run scripts you have read.

## Diff the branches

Before you merge, look at what actually changed. cm:branches:diff compares a compare branch (your changes) against a base branch (where they go).

```bash
csdx cm:branches:diff \
  --base-branch main \
  --compare-branch model-v2 \
  --module content-types \
  -k <stack-api-key>
```

The default compact-text output lists added, modified, and deleted content types. For field-level changes, use --format detailed-text, which also writes a CSV report you can attach to a pull request:

```bash
csdx cm:branches:diff \
  --base-branch main \
  --compare-branch model-v2 \
  --module all \
  --format detailed-text \
  --csv-path ./reports/model-v2-diff.csv \
  -k <stack-api-key>
```

--module accepts content-types, global-fields, or all. Those are the only modules compare and merge support.

## Merge into main

cm:branches:merge shows the diff, asks for a merge strategy, and applies it.

```bash
csdx cm:branches:merge \
  --base-branch main \
  --compare-branch model-v2 \
  --comment "Add summary field to blog_post" \
  -k <stack-api-key>
```

The strategy decides what happens with new items, modified items, and conflicts. These are the API values; the CLI prompt shows the same options by name.

Strategy

What it does

merge_prefer_base

Adds compare changes to base. On conflict, keeps base.

merge_prefer_compare

Adds compare changes to base. On conflict, keeps compare.

overwrite_with_compare

Replaces base content with compare content.

merge_new_only

Adds only new items from compare. Ignores modified items.

merge_modified_only_prefer_base

Adds only modified items. On conflict, keeps base.

merge_modified_only_prefer_compare

Adds only modified items. On conflict, keeps compare.

ignore

Leaves base unchanged. Use it as the default and set per-item strategies.

For a branch that only adds fields and content types, merge_prefer_compare is the usual choice. If editors also changed content types on main while you worked, merge_prefer_base keeps their changes and only brings in yours where there is no conflict.

### Backup branches and merge status

By default, a merge first creates a backup of the base branch. That backup is your undo button: point your alias at it and the site renders the pre-merge model while you sort things out. The backup counts as one extra branch beyond your plan's limit, so delete it before the next merge if you are at the cap. Pass --no-revert to skip it, which you should only do on throwaway branches.

Merges run as background jobs. The command polls until the job finishes. If you lose the terminal or the polling times out, check the job by its UID:

```bash
csdx cm:branches:merge-status -k <stack-api-key> --merge-uid <merge-job-uid>
```

### Entries need their own migration

The merge moves content types and global fields. It does not move entries. If you filled in summary on twenty entries in model-v2, those values are still only on model-v2 after the merge.

The CLI can generate entry migration scripts for the content types you merged. It writes them to a merge_scripts folder and prints the command to run them. You run them with cm:stacks:migration against the base branch:

```bash
csdx cm:stacks:migration \
  --multiple \
  --file-path ./merge_scripts \
  --inline-config compare-branch:model-v2 \
  --branch main \
  -k <stack-api-key>
```

The generated scripts cover straightforward create and update cases. Read them before running, and edit them for anything more involved, such as splitting one field into two.

## Point delivery at an alias

Merging is the right move when the change is additive and editors keep working on main. For a large rewrite, such as a new page model, you often want to build the new content on the branch and switch the whole site at once. That is what aliases are for.

Create an alias called production in Settings > Branches > Aliases and point it at main. Then configure the Delivery SDK with the alias instead of a branch UID:

```typescript
import contentstack from '@contentstack/delivery-sdk';

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

The SDK sends production as the branch header on every request. Contentstack resolves the alias to its target branch.

When model-v2 is ready, repoint the alias. In the UI, edit the alias and pick the new target branch. Through the Content Management API, it is one request:

```bash
curl -X PUT "https://api.contentstack.io/v3/stacks/branch_aliases/production" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "authtoken: $CONTENTSTACK_AUTHTOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "branch_alias": { "target_branch": "model-v2" } }'
```

The next request from your frontend reads from model-v2. Rolling back is the same call with main as the target. An alias points to exactly one branch at a time.

Production note: Deploy frontend code that handles both the old and the new model before you repoint the alias. If the new code only understands model-v2, rolling back the alias breaks the site instead of saving it.

If your site is statically generated, repointing the alias changes what the next build fetches. Trigger a rebuild or revalidation after the switch.

## Scope tokens to branches and aliases

Tokens are global modules, but you choose which branches and aliases each token can reach.

- Delivery tokens: scope the frontend's token to the alias it reads from, for example production. If the token does not include the alias, the request fails.


- Management tokens: give CI a token scoped to the branches it migrates. A token for the feature branch workflow does not need write access to main until the merge step.



Keep a separate token for preview or staging deployments that read from a branch directly. That way a staging build never reads from the production alias by accident, and you can revoke one without touching the other.

## Run the flow from CI

The pieces above map onto a pull request workflow. The developer creates the branch once with the CLI. CI then applies the migration scripts to that branch on every push, so the branch always matches the scripts in the repository.

```yaml
# .github/workflows/content-model.yml
name: Content model
on:
  pull_request:
    paths: ['migrations/**']

jobs:
  migrate-branch:
    runs-on: ubuntu-latest
    env:
      CS_BRANCH: model-v2
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @contentstack/cli
      - name: Save management token alias
        run: >
          csdx auth:tokens:add --management -y
          --alias ci-token
          --stack-api-key "${{ secrets.CS_API_KEY }}"
          --token "${{ secrets.CS_MANAGEMENT_TOKEN }}"
      - name: Run migrations on the feature branch
        run: >
          csdx cm:stacks:migration --multiple
          --file-path ./migrations
          --branch "$CS_BRANCH"
          --alias ci-token
```

Watch out for repeat runs. A script that calls createField('summary') assumes the field does not exist yet, and the migration command does not track which scripts already ran. Keep that record yourself, for example a list of applied filenames stored as a CI artifact or committed to the repository, and skip those files on the next push. Once a pull request merges, move its scripts to an applied folder so they never run again.

For the merge itself, the branches_merge endpoint accepts a management token, which makes it a good fit for a deploy job after the pull request merges:

```bash
curl -X POST "https://api.contentstack.io/v3/stacks/branches_merge?base_branch=main&compare_branch=model-v2&default_merge_strategy=merge_prefer_compare&merge_comment=Merge%20model-v2" \
  -H "api_key: $CS_API_KEY" \
  -H "authorization: $CS_MANAGEMENT_TOKEN"
```

The response contains the merge job uid and merge_details.status. Poll GET /v3/stacks/branches_queue/{uid} until queue[0].merge_details.status is complete or failed, and fail the job on failed.

Keep the alias repoint as a manual step or a separate approved job. It needs a user authtoken, and it is the moment your production site changes, so a person should own it.

## Where people get confused

### Confusion 1: "Merge" means everything merges

It doesn't. Only content types and global fields merge. Entries, assets, releases, and labels stay on the branch where you created them. Plan the entry work as its own step.

### Confusion 2: Editors keep working on main

A branch is a snapshot at fork time. Entries that editors create or publish on main after you fork do not appear on your branch. If you plan to switch the site by repointing an alias, agree on a content freeze for the switch, or copy the late changes over with a script. If you merge instead, this problem goes away, because editors never leave main.

### Confusion 3: Taxonomies feel branch-scoped

They aren't. Taxonomies and terms are shared by every branch. Content types reference them per branch, but the terms themselves are global.

### Confusion 4: The alias is the branch

An alias has no content of its own. Publishing, workflows, and releases happen on the target branch. Editors working "on production" are working on whatever branch the alias points to at that moment.

## Limits to remember

- The number of branches depends on your plan. The merge backup branch can exceed the limit by one, but you may need to delete it before the next merge.


- Compare and merge cover content types and global fields only.


- Creating a branch and assigning an alias require an authtoken. Merge, compare, and merge-status calls accept a management token.


- Owners, admins, and developers can create branches and assign aliases.


- Releases are branch-specific. A release created on model-v2 deploys items from model-v2 only.



## Key takeaways

- Fork with csdx cm:branches:create --source main --uid <branch> and never run migrations against main first.


- Script model changes with cm:stacks:migration --branch <branch> and keep them additive.


- Review cm:branches:diff --format detailed-text before every merge.


- cm:branches:merge moves content types and global fields; run the generated merge_scripts for entries.


- Point the Delivery SDK at an alias with branch: 'production' and repoint it to ship or roll back.


- Taxonomies, environments, and tokens are global; scope tokens to the branches and aliases they need.



## Next steps

- Read [Modular blocks, references or global fields](/guides/modular-blocks-references-or-global-fields) before you plan a large model change.


- Automate the deploy side with [Deploy from CI with the Launch CLI and API](/guides/deploy-from-ci-with-the-launch-cli-and-api).


- Learn how the CLI plugin system works in [Write your own csdx plugin](/guides/write-your-own-csdx-plugin).





---

## Do this with AI

Install the cms-branches-aliases 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:

> Compare the content types on my feature branch with main and list every field that was added, removed or changed type, without merging anything.

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




---

## Frequently asked questions

### Does merging a branch also merge entries?

No. Compare and merge cover content types and global fields only. Entry changes need migration scripts, which the CLI can generate for the content types you merged.

### Are taxonomies copied into a new branch?

No. Taxonomies are a global module, so every branch in the stack sees the same taxonomies and terms. Changing a taxonomy on one branch changes it everywhere.

### How do I undo a merge?

By default a merge creates a backup of the base branch first. Point your alias at that backup branch to roll the site back while you fix things.

### Can a delivery token read from an alias?

Yes. Delivery and management tokens can be scoped to specific branches or to aliases. A token that does not include the branch or alias you request cannot read from it.


---

## Step 9: Production readiness, troubleshooting, and next steps

- **Source:** https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/production-readiness-troubleshooting-and-next-steps
- **Checkpoint:** Tokens, preview and caching are ready for production

- **Authors:** Tim Benniks, Lo Etheridge
- **Published:** 2026-04-07T11:00:23.254Z
- **Updated:** 2026-11-10T16:27:13.509Z
- **Level:** Intermediate
- **Intent:** Ship

---

The last mile matters. A Contentstack project can look great in local development and still fail in preview, misbehave in production, or become hard to operate if the boundaries are unclear. This chapter focuses on the things that make a starter safe to grow up.

## What you'll learn

- Which security boundaries matter most in a Contentstack-powered frontend


- How preview and production delivery differ operationally


- Why Veda includes launch-time cache priming


- Which problems show up most often in real projects


- What Veda intentionally leaves out


- Where to go next once you outgrow the initial learning phase



## Security boundaries to keep clear

Contentstack concept: Not all credentials are equal.

You should keep these distinctions sharp:

- delivery token: published read access


- preview token: draft-aware read access


- management token: privileged write access



Production note: The most important rule is still the simplest one: do not expose management credentials in the frontend.

Veda's env setup is designed around delivery and preview workflows. That is appropriate for the kind of project it is demonstrating.

## Preview and production are not the same runtime

Contentstack concept: Published delivery and preview delivery are related but not interchangeable.

Published delivery is optimized for stable, environment-targeted content reads.

Preview delivery is optimized for:

- draft visibility


- editor workflows


- visual verification before publication



If a page works in production but not in preview, or vice versa, that usually means you are debugging a configuration or runtime-mode issue, not necessarily a general data-fetch issue.

## Why Veda includes launch-time cache priming

Veda implementation: Veda ships with updateLaunchConfig.mjs, and the package scripts run it before build.

That script queries the stack for URLs across several content types and generates launch.json so deployments can pre-prime cacheable routes.

Why this matters:

- first visits are less likely to pay cold-start costs


- the deployment process knows more about the site's route surface


- the template already nudges you toward thinking operationally



This is one of the quieter but more valuable parts of the repo because it teaches that content architecture and deployment behavior are related.

## Common problems and the fastest checks

### Problem: the app runs, but no content appears

Check:

- API key


- delivery token


- environment name


- region value


- whether the stack was seeded successfully



### Problem: published pages work, but preview does not

Check:

- preview token exists


- preview mode is enabled in env vars


- Live Preview is configured in the stack


- preview bindings are still present in the rendered UI



### Problem: a route resolves, but the wrong content shows up

Check:

- the entry's URL field


- route parameter handling


- path-building logic in the utility layer


- content-type-specific fetcher being used for that route



### Problem: a new block was added in Contentstack but does not render

Check:

- block exists in the content model


- frontend component exists


- central block mapping includes the new type


- preview wrappers still behave correctly for the block area



### Problem: builds fail in ways local dev did not

Check:

- npm run build output


- whether route-discovery or cache-priming logic is trying to read missing content


- whether .env.local values are complete for build-time scripts



## What Veda intentionally does not include

Veda implementation: Veda is a strong content and experience template, but it is still intentionally scoped.

It does not include:

- shopping cart


- checkout


- payments


- user accounts


- order management



That means you should treat it as:

- a learning reference


- a content architecture starting point


- a polished experience layer



Not as a total commerce platform.

## A sensible next-step path after this guide

Once you understand Veda, your next move depends on your goal.

If you want to go deeper into platform behavior:

- study the official Delivery API and SDK docs


- read the Live Preview setup documentation closely


- review the Visual Editor guide for debugging and operational detail



If you want to build your own project:

- adapt the content model to your domain


- keep the shared integration and preview patterns


- add project-specific block types and route behavior deliberately



If you want to automate content workflows:

- learn the Management API separately


- keep it off the frontend


- treat it as a server-side or automation concern



## Key takeaways

- The most important security rule is to keep management credentials out of the frontend


- Preview and published delivery are related but operationally distinct runtime modes


- Veda's cache-priming script is a strong example of production-minded thinking in a starter


- Most issues can be isolated quickly if you debug configuration, routing, and preview behavior in the right order


- Veda is best used as a content-rich experience layer, not a full commerce platform






---

## Frequently asked questions

### Which Contentstack tokens should never be exposed in a frontend app?

Never expose management tokens in the frontend. Use delivery tokens for published read access and preview tokens for draft-aware reads.

### Why can preview work differently from production even with the same content?

Preview and published delivery are different runtime modes with different goals. A mismatch usually indicates configuration or preview-mode setup issues rather than general data fetching.

### What does Veda's updateLaunchConfig.mjs cache-priming script do?

It queries the stack for route URLs across content types and generates launch.json before build. Deployments can then pre-prime cacheable routes to reduce cold-start costs.

### What are the fastest checks when the app runs but no content appears?

Verify API key, delivery token, environment name, region value, and that the stack seeding completed successfully.

### What is intentionally out of scope for Veda?

Veda does not include commerce features like cart, checkout, payments, user accounts, or order management. Treat it as a content and experience template, not a complete commerce platform.



---

## Chapter Navigation

**← Previous:** [Customizing Veda for your own project](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers/customizing-veda-for-your-own-project)


---

## Step 10: Just Automate It!

- **Source:** https://developers.contentstack.com/livestreams/just-automate-it
- **Checkpoint:** You know where Automate can take repetitive work off your team

- **Hosts:** Lo Etheridge, Tim Benniks
- **Published:** 2025-03-26
- **Updated:** 2026-11-10T15:04:35.368Z
- **Level:** Intermediate
- **Intent:** Learn
- **Tags:** automation
- **Watch:** https://www.youtube.com/watch?v=KhEV1dHs-aY

---

Join us for a hands-on demonstration of Contentstack's Automate and how to configure it to set content teams up for success. Take a deep dive with special gu...



---

## About this livestream

Join us for a hands-on demonstration of Contentstack's Automate and how to configure it to set content teams up for success. Take a deep dive with special gu...



---

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