# Contentstack 0 to 100 for developers - **Authors:** Tim Benniks - **Published:** 2026-04-07 - **Updated:** 2026-04-07T11:06:50.778Z - **Chapters:** 10 - **Source:** [https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers](https://developers.contentstack.com/guides/contentstack-0-to-100-for-developers) --- ## Table of Contents 1. [What Contentstack is and why Veda is a good starting point](#what-contentstack-is-and-why-veda-is-a-good-starting-point) 2. [Core Contentstack Concepts](#core-contentstack-concepts) 3. [Account, Region, CLI, and Stack Setup](#account-region-cli-and-stack-setup) 4. [Running Kickstart Veda Locally](#running-kickstart-veda-locally) 5. [Understanding the Veda Content Model](#understanding-the-veda-content-model) 6. [How Veda Is Structured](#how-veda-is-structured) 7. [Fetching Content, Routing, and Rendering](#fetching-content-routing-and-rendering) 8. [Live Preview and Visual Builder](#live-preview-and-visual-builder) 9. [Customizing Veda for your own project](#customizing-veda-for-your-own-project) 10. [Production readiness, troubleshooting, and next steps](#production-readiness-troubleshooting-and-next-steps) ## What this guide is for This guide is aimed at developers who are new to Contentstack and want a practical path from platform basics to a realistic implementation. It explains the core Contentstack mental model, then uses a real starter project to show how those ideas turn into code, routing, preview behavior, and content modeling decisions. ## Why this guide uses Kickstart Veda This guide uses [Kickstart Veda](https://github.com/contentstack/kickstart-veda) as the running example. Veda is a public Next.js starter from Contentstack built around a content-rich luxury jewelry site called "The Revival Collection." It is a strong teaching project because it is bigger than a toy demo, but still focused enough to study clearly. The codebase includes: - a realistic Contentstack content model with pages, products, categories, and product lines - route-driven content fetching instead of one hardcoded entry - modular blocks for flexible page composition - Live Preview and Visual Builder support - production-minded patterns such as shared fetch utilities and launch-time route priming Use Veda as an example of how a content-heavy frontend can be structured, not as a prescription for every project or as a full commerce platform. Useful references: - [Veda codebase](https://github.com/contentstack/kickstart-veda) - [Veda guide page](/kickstarts/kickstart-veda) - [Veda demo](https://kickstart-veda.vercel.app/) ## How to use this guide - If you are completely new to Contentstack, start with chapter 1 and read in order. - If you already understand headless CMS fundamentals, chapters 3 through 8 are the fastest path into the real Veda implementation. ## Chapter Index ### 01. What Contentstack Is and Why Veda Is a Good Starting Point Start here for the platform framing. This chapter explains what Contentstack is in practical development terms, what "headless" changes once a project becomes real, and why the guide begins with architecture and vocabulary before setup commands. ### 02. Core Contentstack Concepts Build the vocabulary you need before touching the starter. This chapter covers stacks, content types, entries, assets, environments, locales, and the difference between Delivery, Preview, and Management APIs. ### 03. Account, Region, CLI, and Stack Setup Create the foundation Veda expects. This chapter walks through region selection, CLI setup, seeding the Veda stack, and the environment variables and tokens the app needs. ### 04. Running Kickstart Veda Locally Move from setup to a running app. This chapter shows how to clone the Veda repository, configure .env.local, install dependencies, and verify that the seeded content is rendering correctly. ### 05. Understanding the Veda Content Model Study how the content is shaped. This chapter maps the main content types, explains how they relate to one another, and shows why the model supports both flexible editorial pages and product-oriented experiences. ### 06. How Veda Is Structured Map the content model onto the codebase. This chapter explains the role of app/, components/, and lib/, and shows how the Contentstack integration layer, page utilities, and renderer work together. ### 07. Fetching Content, Routing, and Rendering Follow the main runtime flow. This chapter explains how Veda initializes the SDK, resolves region-aware endpoints, fetches entries by URL, reuses cached helpers, and turns modular content into rendered pages and metadata. ### 08. Live Preview and Visual Builder Understand the editing runtime. This chapter explains preview tokens, editable bindings, preview re-fetch loops, and the frontend behavior that makes Live Preview and Visual Builder work. ### 09. Customizing Veda for Your Own Project Change the starter deliberately instead of breaking it accidentally. This chapter covers low-risk first customizations, evolving content types and blocks, route changes, and preserving preview behavior. ### 10. Production Readiness, Troubleshooting, and Next Steps Finish with the operational layer. This chapter covers token boundaries, preview versus production runtime differences, cache priming, common failure modes, and where to go after the starter phase. --- ## What Contentstack is and why Veda is a good starting point If you are new to Contentstack, the fastest way to get lost is to start by memorizing SDK calls before you understand the shape of the platform. This chapter keeps the focus on the platform itself first, then closes with a short explanation of why Veda is a useful example for the rest of the guide. ## What you'll learn - What Contentstack actually is in day-to-day development terms - What "headless CMS" means once code, content, and deployment are involved - Why good platform vocabulary matters before setup and code - Why Veda is more useful than a toy starter when you want to learn real patterns ## Contentstack in practical terms Contentstack concept: Contentstack is a headless CMS. That means content management and content delivery are separated from the frontend that renders the experience. In practical terms, your editors work in the Contentstack UI. They define structured content such as pages, product lines, categories, or articles. Your application then fetches that structured content over APIs and renders it however you want. This is different from a traditional CMS where the backend often owns both the content model and the presentation layer. In Contentstack, your React, Next.js, Nuxt, native app, or middleware layer stays in control of presentation. That separation gives you a few very concrete benefits: - Your frontend can evolve independently from the editorial interface - Content can be reused across multiple channels - Developers can model content as structured data instead of unstructured page blobs - Editors can work without asking developers to hardcode every content change ## What "headless" means once a project becomes real Contentstack concept: "Headless" does not mean "simpler." It means the responsibilities are split differently. You still need to answer the same real-world questions: - What content types exist? - Which content types link to each other? - How should URLs map to entries? - Which API serves published content? - Which API serves draft content for preview? - How do you make editing safe without exposing admin credentials? Those are not abstract architecture questions. They become file structure, query logic, deployment rules, preview behavior, and debugging checklists. That is why a good learning example matters so much. A minimal starter can show you one happy-path query. It usually cannot show you how a larger content model behaves once routing, metadata, filtering, preview, and reusable blocks all show up together. ## Why platform vocabulary comes before setup Production note: Many early Contentstack problems are not caused by syntax errors. They usually come from mixing up concepts: - using the wrong token for the wrong job - misunderstanding what an environment means - assuming preview behaves like production delivery - treating modular blocks like arbitrary JSON instead of structured content Those mistakes do not stay theoretical. They become broken preview flows, confusing route bugs, and fragile fetch helpers. That is why this guide starts with mental models, then moves into stack setup, local development, content modeling, and code structure. Once the platform ideas are clear, the implementation chapters become much easier to reason about. ## Why Veda is a good example after the fundamentals Veda implementation: Kickstart Veda is a strong teaching example because it is realistic enough to surface the questions that small demos usually hide. It includes: - multiple content types instead of one sample page - route-driven fetching instead of one hardcoded entry - modular blocks for flexible page composition - preview support that behaves like a real editing mode - production-minded helpers and structure instead of only SDK setup That makes Veda useful for learning architecture, not only integration. Veda is still just the example project for this guide. The goal is to understand the Contentstack and frontend patterns well enough to recognize which parts are portable and which parts are specific to this starter. ## Key takeaways - Contentstack separates content management from presentation, but it does not remove architectural decisions - A headless CMS becomes most useful when you model content as structured data and keep rendering logic in your application - Clear platform vocabulary prevents a lot of setup and preview confusion later - Veda is a strong learning example because it shows multiple content types, multiple routes, preview support, and production-minded patterns together - Understanding the platform vocabulary first will make the implementation chapters much easier to follow --- ## Core Contentstack Concepts Before you seed a stack or open the Veda repo, you need a reliable vocabulary. Contentstack becomes much easier once you know which objects exist, what they are responsible for, and which API is supposed to touch them. ## What you'll learn - The meaning of stack, content type, entry, asset, environment, and locale - The difference between Delivery API, Preview API, and Management API - How references and modular blocks shape real content models - Where beginners usually get confused - Which concepts are portable across projects and which ones are Veda-specific ## The object model you should keep in your head ### Stack Contentstack concept: A stack is the top-level container for your project inside Contentstack. A stack contains things like: - content types - entries - assets - environments - tokens - Live Preview configuration If you are coming from databases, you can think of a stack as the broad project boundary. If you are coming from GitHub, think "repository plus configuration plus data," not just a single file tree. ### Content types Contentstack concept: A content type is the schema for a kind of content. Examples: - page - product - category - header A content type defines fields such as title, description, URL, references, media, modular blocks, and validation rules. This is one of the most important shifts in Contentstack. You do not start by designing pages. You start by designing content shapes. ### Entries Contentstack concept: An entry is one actual item of content that follows a content type. If product is the content type, one ring or necklace is an entry. If page is the content type, your homepage is one entry and your about page is another. ### Assets Contentstack concept: Assets are files stored in Contentstack, such as images, videos, and documents. They are delivered over Contentstack's CDN and can be referenced from entries. In a project like Veda, many visual experiences depend on asset URLs being part of the structured content rather than hardcoded in the frontend. ### Environments Contentstack concept: Environments represent stages of content delivery such as development, staging, or production. The important thing to remember is that environments matter for published delivery. An editor can save drafts at any time, but publication targets an environment. ### Locales Contentstack concept: Locales represent language or regional variants such as en-us or fr-fr. You do not need multiple locales to learn Veda, but once you understand Contentstack well, locales become part of how the same content model can serve multiple audiences. ## The three API modes that matter This is where many first-time users get tripped up. ### Delivery API Contentstack concept: The Delivery API is for reading published content. Use it when: - your public site is rendering live content - you want stable, cacheable responses - you are reading from a specific environment ### Preview API Contentstack concept: The Preview API is for reading draft or unpublished content during preview workflows. Use it when: - editors need to see draft changes - Live Preview is active - your app needs to reflect unpublished changes safely ### Management API Contentstack concept: The Management API is for creating, updating, deleting, and publishing content. Use it when: - you are writing automation scripts - building import/export tools - handling server-side content administration workflows Production note: Never expose Management API credentials in a frontend application. Delivery and preview flows are one thing. Administrative write access is another. ## References: how entries connect to each other Contentstack concept: References let one entry link to another entry. This is how a project stops feeling like isolated pages and starts feeling like a content system. For example, a product line might reference products. A header entry might reference navigation structures. A page might reference blocks, assets, or related content. In Veda, references are part of what makes the project more realistic. Instead of fetching one flat page payload, the app often pulls connected content with deeper include settings because the site is modeling real relationships. ## Modular blocks: how editors compose pages without hardcoding layouts Contentstack concept: Modular blocks let editors assemble a page from reusable content sections. Examples from Veda include: - hero - list - two column - media - rich text This is a major strength of Contentstack when used well. Developers define the available block types and how they render. Editors decide which blocks to use and in what order. That gives you a clean contract: - developers own the rendering components - editors own page composition within those allowed patterns ## Where beginners usually get confused ### Confusion 1: "Entry" versus "page" Not every entry is a page. Some entries are pages, some are products, some are navigation data, and some are reusable supporting content. ### Confusion 2: "Preview" versus "published" Preview is not just "the same content but earlier." It is a different delivery mode with different credentials and different expectations. ### Confusion 3: "Content type" versus "component" A React component is not a content type. A modular block definition inside Contentstack is also not the same thing as a frontend component, even though the two are related. The content model decides what data is available. The frontend decides how that data is rendered. ### Confusion 4: "Environment" versus "region" An environment is a content lifecycle stage inside a stack. A region is the physical or cloud location where your stack and endpoints live. Those are separate concerns. ## What is portable beyond Veda Contentstack concept: Everything in this chapter is portable. The details of Veda will change: - content type names - component names - route patterns - visual style But the core model stays the same: - stacks contain schemas and content - content types define structure - entries hold actual content - assets hold files - environments and locales shape delivery - references and modular blocks enable richer composition - different APIs exist for different jobs ## Key takeaways - Contentstack works best when you think in structured content, not only pages - A stack is the project boundary; content types define structure; entries hold data - Delivery, Preview, and Management APIs serve different jobs and should not be mixed casually - References connect content types into a system - Modular blocks are the bridge between editorial flexibility and developer-controlled rendering --- ## Account, Region, CLI, and Stack Setup Now that the platform vocabulary is in place, it is time to create the working foundation Veda expects: an account, the right region, a seeded stack, and the tokens your local app will use. ## What you'll learn - Which account and stack setup path this guide assumes - Why region selection matters early - How to install the Contentstack CLI and log in - How to seed the Veda stack content - Which tokens and environment variables the Veda app expects - Which values are safe to expose in the browser and which are not ## Start with the right account mindset Contentstack concept: You do not need an enterprise rollout to learn Contentstack well. The Quick Start and Veda materials are designed to work with the platform's accessible onboarding paths, including Explorer-oriented flows. That is useful because it means you can learn the platform in a realistic way without inventing your own seed data from scratch. ## Region matters sooner than most people expect Contentstack concept: Your region determines which endpoints your app and tools should talk to. This affects: - CLI configuration - delivery hosts - preview hosts - sometimes the exact values or aliases used in environment variables The official Quick Start currently shows a provider-prefixed CLI region example: ```bash csdx config:set:region EU ``` Production note: If your installed CLI rejects one form, check csdx --help or the current CLI guidance and use the value it expects. The important part is not the exact alias. The important part is that the CLI and your stack region agree. ## Install the CLI Contentstack concept: The CLI is the fastest way to bootstrap a working stack for learning and demos. Install it globally: ```bash npm install -g @contentstack/cli ``` Then configure your region and log in: ```bash csdx config:set:region EU csdx auth:login ``` If your CLI expects a provider-prefixed region value, use that instead. ## Seed the Veda stack Veda implementation: The current Veda setup path uses a seed repository so you do not have to manually create every content type and entry. Use the seed command from the Veda setup flow: ```bash csdx cm:stacks:seed --repo "contentstack/kickstart-veda-seed" --org "" -n "Veda: The Revival Collection" ``` What this gives you: - the content model - starter entries - assets - the content relationships the frontend expects Without the seed, the frontend can still run, but you would first need to recreate the full content structure by hand. ## Create the right tokens Contentstack concept: The frontend needs read-oriented credentials, not administrative ones. For Veda, create: - an API key for the stack - a delivery token for published content - a preview token for draft content and preview flows In the Veda setup instructions, this is done from the Contentstack dashboard under Settings and Tokens. Production note: Do not use a management token in a frontend app. If you ever need write access, keep it on a server or inside controlled automation. ## Configure local environment variables Veda implementation: The checked-in .env.example in the Veda repository currently uses these variables: ```bash NEXT_PUBLIC_CONTENTSTACK_API_KEY=your_api_key_here NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN=your_delivery_token_here NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN=your_preview_token_here NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT=preview NEXT_PUBLIC_CONTENTSTACK_REGION=EU NEXT_PUBLIC_CONTENTSTACK_PREVIEW=true ``` Two details matter here: - The variables use NEXT_PUBLIC_ because Veda's preview experience needs values on the client side - The app distinguishes between published delivery and preview behavior using NEXT_PUBLIC_CONTENTSTACK_PREVIEW ## Why Veda uses public-looking variables Veda implementation: In many apps, developers are taught to avoid exposing anything that looks credential-like to the browser. That is a good instinct, but you still need to separate categories of credentials. Veda uses: - delivery token - preview token - API key These support content delivery and preview behavior. They are not the same thing as a management token. Production note: The rule is not "never expose any token-looking string." The rule is "never expose privileged write credentials." Read-only delivery and preview credentials have a different security profile than content administration credentials. ## Recommended setup sequence If you want the path of least resistance, do it in this order: - Create or access a Contentstack account - Install the CLI - Set the correct region - Log in - Seed the Veda stack - Create delivery and preview tokens - Prepare your .env.local values for the app That keeps the frontend setup simple, because once you clone Veda you already know the stack exists and the credentials are ready. ## Key takeaways - Region matters for both CLI behavior and runtime endpoints - The Veda learning path is much easier if you seed the stack instead of hand-building the content model first - The Veda app expects delivery and preview credentials, plus an API key and environment name - NEXT_PUBLIC_ variables in Veda support preview-aware frontend behavior - Management credentials are a different class of secret and should stay off the frontend --- ## Running Kickstart Veda Locally At this point, you have the platform context and the stack setup. Now it is time to run the actual app, confirm the environment is wired correctly, and get a first feel for what the seeded project gives you. ## What you'll learn - How to clone and install the Veda app - How to create .env.local from the checked-in example - Which commands matter for development versus verification - What a healthy local startup looks like - Which parts of the running app are worth inspecting first ## Clone the project Veda implementation: Start by cloning the public repository and moving into it: ```bash git clone https://github.com/contentstack/kickstart-veda.git cd kickstart-veda ``` The current Veda repository is built with: - Next.js - React - TypeScript - Tailwind CSS - @contentstack/delivery-sdk - @contentstack/live-preview-utils - @timbenniks/contentstack-endpoints ## Prepare your local environment file Veda implementation: Copy the example file, then replace the placeholders with the values from the stack you seeded: ```bash cp .env.example .env.local ``` Update .env.local so it reflects your real stack values: ```bash NEXT_PUBLIC_CONTENTSTACK_API_KEY=... NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN=... NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN=... NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT=preview NEXT_PUBLIC_CONTENTSTACK_REGION=EU NEXT_PUBLIC_CONTENTSTACK_PREVIEW=true ``` If your stack uses a different environment or region, update those values to match reality. ## Install dependencies and start the app Use npm, since the project ships with package-lock.json: ```bash npm install npm run dev ``` The Veda README currently calls out Node.js 20+ as the safe baseline. If you hit engine or package issues, check your local Node version first. ## What success looks like Veda implementation: A healthy local start usually looks like this: - Next.js starts without credential-related runtime failures - the homepage renders real seeded content instead of blank sections - the /products area renders catalog data - category and product-line pages resolve from actual Contentstack entries If the app boots but content looks empty, the most likely causes are: - wrong API key - wrong delivery token - wrong environment name - region mismatch - stack was not seeded successfully ## First pages worth inspecting You do not need to click every route immediately. Start with the surfaces that teach the most. ### Homepage Veda implementation: The homepage helps you see modular blocks in action. You are not just looking at a single static page. You are looking at a content-composed page assembled from block data. ### /products This is where Veda starts to feel different from a tiny starter. The project includes product discovery and filtering logic, which shows how Contentstack content can support a catalog-like experience. ### Category and product-line routes These routes show that different content types can have different page-level rendering behavior even while sharing the same content platform and utility layer. ## A useful local verification step Production note: Once local development works, it is worth checking a production build too: ```bash npm run build ``` That matters in Veda because the build step includes a prebuild hook that runs updateLaunchConfig.mjs, which generates a launch.json file for cache priming. So a successful build is validating more than "Next.js compiles." It is also validating that your stack can be queried for route discovery during the build workflow. ## What to do if preview is not working yet Do not panic if Live Preview is not the first thing that works. Focus on this order: - published content fetch works - routes render correctly - build succeeds - preview wiring is confirmed That gives you a clean debugging sequence instead of trying to troubleshoot everything at once. ## Why this chapter matters Contentstack concept: A lot of developer confidence comes from getting one real system running end to end. Once the app is live locally and your data is showing up, the later architecture chapters stop feeling theoretical. You now know three important things: - the stack exists - the app can read from it - the repository is worth studying in detail ## Key takeaways - Use the public Veda repository as the codebase for this guide - Start from .env.example, then replace placeholders with your real stack values - npm install and npm run dev are the quickest path to a live local environment - A successful npm run build validates both compilation and the cache-priming route discovery step - Start by verifying published content before you diagnose preview behavior --- ## Understanding the Veda Content Model 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 Builder 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 Builder 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 --- ## How Veda Is Structured You now understand the platform and the content model. This chapter maps that understanding onto the codebase so the repository stops looking like "a bunch of Next.js files" and starts reading like a deliberate architecture. ## What you'll learn - How the main Veda folders divide responsibility - Why the route structure mirrors the content model - What lib/contentstack.ts and lib/pageUtils.ts are doing - Why the component renderer and preview layer matter so much - Which architectural ideas are portable beyond this specific starter ## Start with the top-level shape Veda implementation: The public Veda materials describe a structure centered around three areas: - app/ - components/ - lib/ That separation is already meaningful. flowchart LR App[app routes] --> PageUtils[lib/pageUtils.ts] PageUtils --> Contentstack[lib/contentstack.ts] Contentstack --> API[Contentstack Delivery or Preview API] PageUtils --> PageComponents[components/Pages/*] PageComponents --> Renderer[ComponentsRenderer] Renderer --> Blocks[Hero List Media RichText TwoColumn] This is the architecture at the level that matters most when you are onboarding: - routes ask for page-shaped data - utility functions normalize path and fetch logic - one integration layer talks to Contentstack - page components render the result - the block renderer turns modular content into concrete UI ### app/ This is the Next.js App Router layer. It is where route-level behavior lives. From the repo and public materials, you can see route shapes such as: - app/[[...slug]]/page.tsx for general pages - category routes - product-line and product routes under /products/... This mirrors the content model instead of forcing every page through one identical path strategy. ### components/ This layer contains reusable rendering pieces. Two especially important ideas show up here: - page-level components for major content shapes - a modular block renderer that maps Contentstack data to React components ### lib/ This is the application logic layer where Contentstack integration, data fetching, typing, filtering, and page utilities live. ## lib/contentstack.ts: the shared content boundary Veda implementation: This file is the main bridge between the frontend and Contentstack. It is responsible for things like: - initializing the Delivery SDK - resolving region-aware endpoints - enabling preview configuration - exposing focused fetchers such as getPage, getHeader, getCategory, getProduct, and getProductLine - applying editable tags in preview mode This is a strong pattern because it keeps low-level SDK setup and query concerns out of page components. Contentstack concept: A shared integration boundary is portable. Even if you never use Next.js again, the idea of centralizing stack configuration and data access still holds. ### Code example: the stack client and focused fetchers Here is a shortened excerpt from the current Veda lib/contentstack.ts: ```typescript const region = getRegionForString(process.env.NEXT_PUBLIC_CONTENTSTACK_REGION as string) const endpoints = getContentstackEndpoints(region, true) export const isPreview = process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW === "true"; export const stack = contentstack.stack({ apiKey: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY as string, deliveryToken: process.env.NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN as string, environment: process.env.NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT as string, region: region ? region : process.env.NEXT_PUBLIC_CONTENTSTACK_REGION as any, host: process.env.NEXT_PUBLIC_CONTENTSTACK_CONTENT_DELIVERY || endpoints && endpoints.contentDelivery, live_preview: { enable: process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW === "true", preview_token: process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN, host: process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW_HOST || endpoints && endpoints.preview } }); ``` What this is doing: - turns env vars into one shared SDK client - resolves the right hosts for the selected region - exposes a boolean isPreview flag the rest of the app can reuse - configures preview delivery and published delivery in one place That last point matters. Instead of every page guessing how preview works, the app has one source of truth. ## lib/pageUtils.ts: turning fetchers into a page system Veda implementation: This file is one of the clearest signals that Veda is not just a minimal starter. The public code shows it handling things like: - caching fetchers with React cache() - building paths from route parameters - centralizing metadata generation - exposing typed route-friendly wrapper functions This matters because it normalizes a lot of repeated page concerns: - derive the URL - fetch the matching content - fetch shared header content - decide whether preview mode applies - generate metadata consistently That is the difference between a demo and an application skeleton. ### Code example: path building and unified fetch flow This trimmed excerpt from lib/pageUtils.ts is worth studying: ```typescript export function buildPath(type: "page" | "category" | "product" | "productLine", params: any): string { switch (type) { case "page": return params.slug ? `/${params.slug.join("/")}` : "/"; case "category": return `/category/${params.category}`; case "product": return `/products/${params.line}/${params.slug}`; case "productLine": return `/products/${params.line}`; } } export async function fetchData(type: "page" | "category" | "product" | "productLine", params: any) { const path = buildPath(type, params); const header = await getHeaderCached(); let content; switch (type) { case "page": content = await getPageCached(path); break; case "category": content = await getCategoryCached(path); break; } return { content, header, path, isPreview, previewType: type }; } ``` Why this is useful: - route params are normalized into a stable path string - shared header data is fetched once in the same utility layer - page components receive a consistent return shape - preview mode can be passed through without route files duplicating logic The hidden benefit is architectural calm. A route file can stay focused on page behavior because path building, shared header fetching, and content-type dispatch are already standardized. ## Route types map to content types Veda implementation: Veda does not assume every entry is rendered the same way. That decision shows up in the route structure: - general pages flow through the catch-all page route - product-related pages have their own route behavior - catalog experiences can own specialized fetching and rendering logic This is a healthy pattern. It keeps your shared platform logic unified while letting important content domains have dedicated page behavior. ## ComponentsRenderer.tsx: the page builder bridge Veda implementation: The modular block renderer maps block names like hero, list, two_column, media, and rich_text to actual React components. That is one of the most educational files in the whole repo because it solves a common headless CMS problem cleanly: - Contentstack stores structured modular data - React needs concrete components - preview mode needs wrappers and editable bindings The renderer becomes the contract between editorial composition and frontend rendering. Production note: Keeping that mapping centralized makes customization much safer. If you later add a new block type, you have one obvious place to wire it into the application. ### Code example: the block-to-component map This is the core idea from the current Veda renderer: ```typescript const componentMap = { hero: HeroComponent, list: ListComponent, two_column: TwoColumnComponent, media: MediaComponent, rich_text: RichTextComponent, } as const; ``` That tiny map explains the whole page-builder approach: - Contentstack says which block type an editor added - the renderer looks up the matching React component - the app stays explicit about what is supported That is one of the cleanest architectural lessons in the repo. ### Code example: a page-level renderer This excerpt from components/Pages/Page.tsx shows how simple page rendering becomes once the utility layers are in place: ```typescript export default function Page({ page, header, }: { page: PageProps; header?: MegaMenuProps; }) { const components = page?.components || []; return ( <> {header && ( )} {components && ( )}