diff --git a/README.md b/README.md
index a3ce71b..311f33b 100644
--- a/README.md
+++ b/README.md
@@ -1,98 +1,764 @@
-# Contentstack Kickstart for Veda: The Revival Collection
+# Contentstack Kickstart: Veda - The Revival Collection ๐
-An upscale unisex jewelry line featuring four distinct sets inspired by early 2000s pop culture, each reinterpreted with modern, understated luxury. Every piece is crafted in combinations of silver, gold, and diamonds, blending youthful nostalgia with refined elegance. Designed to be worn by anyone (cis, trans, or nonbinary), these accessories celebrate the spirit of the 2000s in a contemporary, inclusive aesthetic.
+
+
+
+
+**A production-ready Next.js 15 e-commerce template powered by Contentstack**
+
+> ๐ฏ **Built for Contentstack Explorer Accounts**: This kickstart is specifically designed to work seamlessly with free Contentstack Explorer accounts, providing all the features you need to build stunning content-driven websites without any limitations.
[](https://community.contentstack.com)
+[](https://nextjs.org/)
+[](https://www.typescriptlang.org/)
+[](https://tailwindcss.com/)
-## How to get started
+[Live Demo](https://kickstart-veda.eu-contentstackapps.com/) โข [Documentation](#documentation) โข [Getting Started](#getting-started)
-Before you can run this code, you will need a Contentstack "Stack" to connect to.
-Follow the following steps to seed a Stack that this codebase understands.
+
-### Install the CLI
+---
-```bash
-npm install -g @contentstack/cli
+## ๐ About This Project
-# or
+**Veda: The Revival Collection** is a fully-functional headless content template showcasing an upscale unisex jewelry line with four distinct product sets inspired by early 2000s pop culture. This kickstart demonstrates how to build a modern, production-ready Next.js application with Contentstack as the headless CMS.
-npx @contentstack/cli
+> โ ๏ธ **Important Note**: This is a **content template**, not a complete e-commerce system. It includes product displays, categories, and rich content pages, but does not include shopping cart functionality, checkout processes, or payment integration. It's designed to showcase how to structure and display product content using Contentstack.
+
+### What Makes This Special
+
+- โจ **Complete Content Structure**: Products, product lines, categories, and dynamic pages (template only - no cart/checkout)
+- ๐จ **Visual Builder Support**: Full integration with Contentstack's Visual Builder
+- ๐ **Live Preview**: Real-time content updates with Contentstack Live Preview
+- ๐ฏ **Type-Safe**: Comprehensive TypeScript types for all content models
+- โก **Performance Optimized**: Next.js App Router with streaming SSR and ISR
+- ๐งฉ **Component-Driven**: Modular, reusable components with CSLP (Content Stack Live Preview) support
+- ๐ฑ **Responsive Design**: Mobile-first approach with Tailwind CSS 4.x
+- ๐ผ๏ธ **Image Optimization**: Contentstack's built-in image delivery system for responsive images
+- ๐ **Explorer-Ready**: Optimized for Contentstack Explorer (free) accounts
+
+---
+
+## ๐๏ธ Architecture Overview
+
+This project follows a clean, scalable architecture designed for maintainability and developer experience:
+
+```
+kickstart-veda/
+โโโ app/ # Next.js 15 App Router
+โ โโโ [[...slug]]/ # Catch-all dynamic pages
+โ โโโ category/[category]/ # Category pages
+โ โโโ products/
+โ โ โโโ [line]/[slug]/ # Individual product pages
+โ โ โโโ [line]/ # Product line pages
+โ โโโ layout.tsx # Root layout with metadata
+โ โโโ globals.css # Global styles
+โโโ components/
+โ โโโ Atoms/ # Atomic components (Cta, Title, MediaItem)
+โ โโโ Cards/ # Card components for listings
+โ โโโ Pages/ # Page-level components
+โ โ โโโ Page.tsx # Generic page renderer
+โ โ โโโ Product.tsx # Product detail page
+โ โ โโโ ProductLine.tsx # Product line page
+โ โ โโโ Category.tsx # Category page
+โ โ โโโ Preview.tsx # Live preview wrapper
+โ โโโ ComponentsRenderer.tsx # Dynamic component mapper
+โ โโโ Hero.tsx # Hero banner component
+โ โโโ List.tsx # List/Grid component
+โ โโโ TwoColumn.tsx # Two-column layout
+โ โโโ Media.tsx # Media component
+โ โโโ RichText.tsx # Rich text renderer
+โ โโโ MegaMenu.tsx # Navigation menu
+โ โโโ Footer.tsx # Footer component
+โโโ lib/
+ โโโ contentstack.ts # Contentstack SDK configuration
+ โโโ types.ts # TypeScript type definitions
+ โโโ pageUtils.ts # Page data fetching utilities
+ โโโ filterSearch.ts # Search & filter utilities
```
-#### Using the CLI for the first time?
+---
+
+## ๐ Getting Started
-It might ask you to set your default region.
-You can get all regions and their codes [here](https://www.contentstack.com/docs/developers/cli/configure-regions-in-the-cli) or run `csdx config:get:region`.
+### Prerequisites
-> Beware, Free Contentstack developer accounts are bound to the EU region. We still use the CDN the API is lightning fast.
+- Node.js 20+ and npm
+- A Contentstack account ([Sign up for free](https://community.contentstack.com/))
+- Basic knowledge of Next.js and React
-Set your region like so:
+### Step 1: Install the Contentstack CLI
+
+The CLI helps you seed your stack with the content model and sample data:
```bash
-csdx config:set:region EU
+npm install -g @contentstack/cli
+
+# or use npx without global install
+npx @contentstack/cli
```
-### Log in via the CLI
+#### First-time CLI setup?
+
+Set your region (Free Explorer accounts use the EU region):
```bash
-csdx auth:login
+# Check available regions
+csdx config:get:region
+
+# Set your region
+csdx config:set:region EU
```
-### Get your organization UID
+> ๐ **Note**: Despite using the EU region, Contentstack's CDN ensures lightning-fast API responses globally.
+
+### Step 2: Authenticate
-In your Contentstack Organization dashboard find `Org admin` and copy your Organization ID (Example: `blt481c598b0d8352d9`).
+```bash
+csdx auth:login
+```
-### Create a new stack
+### Step 3: Create Your Stack
-Make sure to replace `` with your actual Organization ID and run the below.
+Find your Organization ID in your Contentstack dashboard under `Org admin` (e.g., `blt481c598b0d8352d9`), then run:
```bash
csdx cm:stacks:seed --repo "contentstack/kickstart-veda-seed" --org "" -n "Veda: The Revival Collection"
```
-## Create a new delivery token.
+This command will:
-Go to `Settings > Tokens` and create a delivery token. Select the `development` scope and turn on `Create preview token`
+- Create a new stack in your organization
+- Set up all content types (Page, Product, Product Line, Category, Header)
+- Import sample content and assets
+- Configure taxonomies and relationships
-## Fill out your .env file.
+### Step 4: Create a Delivery Token
-Now that you have a delivery token, you can fill out the .env file in your codebase.
+1. Navigate to `Settings > Tokens` in your Contentstack dashboard
+2. Click **+ Add token**
+3. Name it (e.g., "Development Token")
+4. Select the `development` scope
+5. Enable **Create preview token**
+6. Save and copy both tokens
-> You can find the API key, Delivery Token and Preview Token in Settings > Tokens > Your token.
+### Step 5: Configure Environment Variables
-```
-NEXT_PUBLIC_CONTENTSTACK_API_KEY=
-NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN=
-NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN=
+Create a `.env.local` file in the project root:
+
+```bash
+# Required: Your stack credentials
+NEXT_PUBLIC_CONTENTSTACK_API_KEY=blt...
+NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN=cs...
+NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN=cs...
NEXT_PUBLIC_CONTENTSTACK_REGION=EU
-NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT=preview
+NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT=development
+
+# Enable Live Preview
NEXT_PUBLIC_CONTENTSTACK_PREVIEW=true
+
+# Optional: Custom endpoints (usually not needed)
+# NEXT_PUBLIC_CONTENTSTACK_CONTENT_DELIVERY=
+# NEXT_PUBLIC_CONTENTSTACK_PREVIEW_HOST=
+# NEXT_PUBLIC_CONTENTSTACK_CONTENT_APPLICATION=
+# NEXT_PUBLIC_CONTENTSTACK_IMAGE_HOSTNAME=
```
-## Turn on Live Preview
+> ๐ก **Tip**: You can find all these values under `Settings > Tokens > [Your Token]`
+
+### Step 6: Enable Live Preview
-Go to Settings > Live Preview. Click enable and select the `development` environment in the drop down. Hit save.
+1. Go to `Settings > Live Preview` in your Contentstack dashboard
+2. Click **Enable**
+3. Select the `development` environment
+4. Set the preview URL: `http://localhost:3000` (or your deployment URL for production)
+5. Save the configuration
-## Install the dependencies
+### Step 7: Install Dependencies & Run
```bash
npm install
+npm run dev
+```
+
+Your site will be available at [http://localhost:3000](http://localhost:3000) ๐
+
+### Step 8: Experience Live Preview
+
+1. Open your Contentstack dashboard
+2. Navigate to `Entries > Page` (or any content type)
+3. Select an entry
+4. Click the **Live Preview** icon in the sidebar
+5. Edit content and see changes in real-time!
+
+You can also use the **Visual Builder** to drag and drop components visually.
+
+---
+
+## ๐ Understanding Live Preview
+
+Contentstack Live Preview is a powerful feature that bridges your CMS and your application, enabling real-time content editing without page refreshes. Here's how it works:
+
+### How Live Preview Works
+
+1. **SDK Integration**: The `@contentstack/live-preview-utils` package establishes a communication channel between the Contentstack UI and your application.
+
+2. **CSLP (Content Stack Live Preview) Tags**: Every editable field receives a unique `data-cslp` attribute that identifies it to the Live Preview system.
+
+```typescript
+// lib/contentstack.ts
+export function initLivePreview() {
+ ContentstackLivePreview.init({
+ ssr: false,
+ enable: process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW === "true",
+ mode: "builder", // Enables Visual Builder
+ stackSdk: stack.config as IStackSdk,
+ stackDetails: {
+ apiKey: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY as string,
+ environment: process.env.NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT as string,
+ },
+ clientUrlParams: {
+ host:
+ process.env.NEXT_PUBLIC_CONTENTSTACK_CONTENT_APPLICATION ||
+ endpoints.application,
+ },
+ editButton: {
+ enable: true,
+ exclude: ["outsideLivePreviewPortal"],
+ },
+ });
+}
+```
+
+3. **Editable Tags**: When fetching content, editable tags are automatically added in preview mode:
+
+```typescript
+if (isPreview) {
+ contentstack.Utils.addEditableTags(entry, "page", true);
+}
+```
+
+4. **Real-time Updates**: When you edit a field in Contentstack, the Live Preview system:
+ - Detects the change via the `data-cslp` attribute
+ - Fetches the updated content from the Preview API
+ - Updates only the changed field in your browser (no full page reload)
+
+### Visual Builder
+
+The Visual Builder mode (`mode: "builder"`) enables drag-and-drop functionality:
+
+- **Add Components**: Click the "+" button to add new modular blocks
+- **Reorder Components**: Drag components to rearrange them
+- **Delete Components**: Remove unwanted sections
+- **Edit In-Place**: Click any text or image to edit directly
+
+All changes are reflected instantly in the preview pane while you work.
+
+---
+
+## ๐งฉ Key Features & Implementation
+
+### 1. Dynamic Component Rendering
+
+The `ComponentsRenderer` dynamically maps Contentstack components to React components:
+
+```tsx
+// components/ComponentsRenderer.tsx
+const componentMap = {
+ hero: HeroComponent,
+ list: ListComponent,
+ two_column: TwoColumnComponent,
+ media: MediaComponent,
+ rich_text: RichTextComponent,
+} as const;
+
+export const ComponentsRenderer: React.FC = ({
+ components,
+ cslp,
+ cslpWrapper,
+}) => {
+ const mappedComponents = mapComponentsToKV(components);
+
+ const renderComponent = (component: any, index: number) => {
+ const Component = componentMap[component.name];
+ const element = ;
+
+ // Wrap with CSLP attributes for Live Preview editing
+ return isPreview && cslp?.[`${cslpWrapper}__${index}`] ? (
+
+ {element}
+
+ ) : (
+ element
+ );
+ };
+
+ return <>{mappedComponents.map(renderComponent)};
+};
```
-### Run your app
+This approach allows content editors to add, remove, and reorder components without code changes.
+
+### 2. Contentstack SDK Configuration
+
+The SDK is configured with region-specific endpoints and Live Preview support:
+
+```typescript
+// lib/contentstack.ts
+const region = getRegionForString(process.env.NEXT_PUBLIC_CONTENTSTACK_REGION);
+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,
+ host: endpoints?.contentDelivery,
+
+ live_preview: {
+ enable: process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW === "true",
+ preview_token: process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN,
+ host: endpoints?.preview,
+ },
+});
+```
+
+### 3. Type-Safe Content Fetching
+
+All content types have TypeScript interfaces and cached fetch functions:
+
+```typescript
+// lib/contentstack.ts
+export async function getPage(url: string): Promise {
+ const result = await stack
+ .contentType("page")
+ .entry()
+ .addParams({ include_all: true, include_all_depth: 2 })
+ .query()
+ .where("url", QueryOperation.EQUALS, url)
+ .find();
+
+ if (result.entries) {
+ const entry = result.entries[0];
+
+ // Add editable tags for Live Preview
+ if (isPreview) {
+ contentstack.Utils.addEditableTags(entry, "page", true);
+ }
+
+ return entry;
+ }
+
+ throw new Error(`Page not found for url: ${url}`);
+}
+
+// Cached version for performance
+export const getPageCached = cache(getPage);
+```
+
+### 4. Unified Routing & Data Fetching
+
+The `pageUtils.ts` file provides unified utilities for all content types:
+
+```typescript
+// lib/pageUtils.ts
+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 fetchPageData(params: { slug?: string[] }) {
+ const path = buildPath("page", params);
+ const header = await getHeaderCached();
+ const content = await getPageCached(path);
+
+ return {
+ content,
+ header,
+ path,
+ isPreview,
+ previewType: "page" as const,
+ };
+}
+```
+
+### 5. Hero Component with CSLP Support
+
+Components receive CSLP attributes via the `$` prop for Live Preview integration:
+
+```tsx
+// components/Hero.tsx
+export default function Hero({
+ description,
+ design,
+ image,
+ title,
+ video,
+ ctas,
+ $, // CSLP attributes for live editing
+}: HeroProps) {
+ return (
+
+ {image?.url && (
+
+ )}
+
+
+
+ {description}
+
+