contentstack · cs-raj · Apr 10, 2026 · Apr 10, 2026
@@ -0,0 +1,5 @@
+# Cursor (optional)
+
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
+
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.
@@ -0,0 +1,47 @@
+# Contentstack Kickstart: Next.js GraphQL – Agent guide
+
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
+
+## What this repo is
+
+| Field | Detail |
+| --- | --- |
+| **Name:** | https://github.com/contentstack/kickstart-next-graphql |
+| **Purpose:** | Minimal Next.js app that connects to Contentstack over GraphQL with Live Preview enabled. |
+| **Out of scope (if any):** | Not an npm library—this is a sample / kickstart application, not a packaged SDK. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| --- | --- |
+| Language | TypeScript 5, React 19, Node.js (compatible with Next.js 16; no `engines` field in package.json) |
+| Build | Next.js 16 (`next build`); [`package.json`](package.json), [`tsconfig.json`](tsconfig.json) |
+| Tests | No automated test runner or `*.test`/`*spec*` files in this repo today |
+| Lint / coverage | ESLint via `next lint`; [`.eslintrc.json`](.eslintrc.json) (`next/core-web-vitals`, `next/typescript`). No coverage tool configured |
+| Other | Tailwind CSS 4; GraphQL Code Generator → `gql/`; Contentstack Delivery SDK, Live Preview, `graphql-request` |
+
+## Commands (quick reference)
+
+| Command Type | Command |
+| --- | --- |
+| Build | `npm run build` |
+| Dev server | `npm run dev` |
+| Production start | `npm run start` (after build) |
+| Lint | `npm run lint` |
+| GraphQL codegen | `npm run codegen` (needs `.env` for schema fetch—see [`skills/contentstack-kickstart/SKILL.md`](skills/contentstack-kickstart/SKILL.md)) |
+
+**CI:** This repository runs security and policy workflows on PRs, not `build`/`lint` gates. See [.github/workflows/policy-scan.yml](.github/workflows/policy-scan.yml), [.github/workflows/sca-scan.yml](.github/workflows/sca-scan.yml), and [.github/workflows/issues-jira.yml](.github/workflows/issues-jira.yml).
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Dev workflow | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Local setup, npm scripts, when to run codegen, CI overview |
+| Contentstack kickstart | [`skills/contentstack-kickstart/SKILL.md`](skills/contentstack-kickstart/SKILL.md) | SDK, GraphQL, codegen, env vars, `lib/contentstack.ts`, `gql/` |
+| Framework (Next.js) | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | App Router layout, server vs client components, Tailwind, `@/*` paths |
+| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Lint, build, manual checks; no unit/E2E suite in repo |
+| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist and integration safety |
+
+## Using Cursor (optional)
+
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.
@@ -1,6 +1,6 @@
 {
   "name": "kickstart-next-graphql",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "private": false,
   "repository": {
     "type": "git",
@@ -19,16 +19,16 @@
   },
   "dependencies": {
     "@contentstack/delivery-sdk": "^5.1.2",
-    "@contentstack/live-preview-utils": "^4.3.0",
+    "@contentstack/live-preview-utils": "^4.4.0",
     "@graphql-codegen/cli": "^6.2.1",
     "@graphql-codegen/client-preset": "^5.2.4",
     "@graphql-codegen/typescript": "^5.0.9",
     "@timbenniks/contentstack-endpoints": "^2.1.0",
     "graphql-request": "^7.4.0",
-    "isomorphic-dompurify": "^3.6.0",
-    "next": "^16.2.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4"
+    "isomorphic-dompurify": "^3.8.0",
+    "next": "^16.2.3",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3",

@@ -0,0 +1,3 @@
+# Skills – Contentstack Kickstart: Next.js GraphQL
+
+Each topic is a folder under `skills/` with a single **`SKILL.md`** inside (YAML frontmatter: `name`, `description`). For the overview and links to every skill, read [AGENTS.md](../AGENTS.md) first.
@@ -0,0 +1,24 @@
+---
+name: code-review
+description: PR checklist for this kickstart—secrets, generated code, preview paths, and verification.
+---
+
+# Code review – Contentstack Kickstart: Next.js GraphQL
+
+## When to use
+
+- Reviewing a pull request or self-review before requesting review
+
+## Instructions
+
+### Checklist
+
+- **Secrets:** No tokens, keys, or private URLs committed; `.env` stays local (confirm `.gitignore` coverage if adding new secret files).
+- **Generated GraphQL:** If operations changed, `gql/` should be updated via `npm run codegen`, not hand-edited arbitrarily.
+- **Preview vs production:** Changes to [app/page.tsx](../../app/page.tsx) or [components/Preview.tsx](../../components/Preview.tsx) should keep preview and non-preview paths coherent.
+- **Integration:** Stack config, regions, and hosts in [lib/contentstack.ts](../../lib/contentstack.ts) should remain understandable; avoid breaking EU vs default GraphQL host logic in [codegen.ts](../../codegen.ts) without good reason.
+- **Accessibility / UX:** If UI changes, quick pass for obvious regressions (focus, contrast, loading states) when the PR touches components.
+
+### Verification
+
+- Author should run lint, build, and manual smoke steps before requesting review.
@@ -0,0 +1,48 @@
+---
+name: contentstack-kickstart
+description: Contentstack Delivery SDK, GraphQL, Live Preview, codegen, env, and data layer in this kickstart.
+---
+
+# Contentstack kickstart – Contentstack Kickstart: Next.js GraphQL
+
+## When to use
+
+- Changing how the app talks to Contentstack (REST SDK, GraphQL, Live Preview)
+- Adding or changing GraphQL operations or regenerating `gql/` types
+- Debugging env, tokens, regions, or preview vs delivery behavior
+
+## Instructions
+
+### Main entry points
+
+- [lib/contentstack.ts](../../lib/contentstack.ts) — `contentstack.stack(...)` (Delivery SDK), `initLivePreview()`, `getPage()`; uses `graphql-request` and typed documents from `gql/`
+- [codegen.ts](../../codegen.ts) — GraphQL Code Generator config: introspects Contentstack GraphQL schema (EU vs default host from region); `documents` globs are the `**/*.ts` / `**/*.tsx` entries in that file (do not point operations at generated `gql/` output)
+- [gql/](../../gql/) — generated client preset output; files are marked `eslint-disable` at top—treat as build artifacts
+
+### Environment variables
+
+Use the names documented in [README.md](../../README.md), including at least:
+
+- `NEXT_PUBLIC_CONTENTSTACK_API_KEY`
+- `NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN`
+- `NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN`
+- `NEXT_PUBLIC_CONTENTSTACK_REGION`
+- `NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT`
+- `NEXT_PUBLIC_CONTENTSTACK_PREVIEW`
+
+Optional overrides used for internal/host testing appear in `lib/contentstack.ts` (e.g. content delivery / preview hosts); most kickstarts only need the public vars above.
+
+### GraphQL codegen policy
+
+- Run `npm run codegen` after you change operations in app or lib code that codegen scans.
+- Do not manually edit `gql/*.ts` except through regeneration (conflicts and drift otherwise).
+
+### Live Preview
+
+- Preview mode branches in [app/page.tsx](../../app/page.tsx): server-rendered static path vs client [components/Preview.tsx](../../components/Preview.tsx) with `useSearchParams` and Live Preview utils.
+- `initLivePreview()` is called from the preview client path; stack config enables `live_preview` when `NEXT_PUBLIC_CONTENTSTACK_PREVIEW` is `"true"`.
+
+### Integration boundaries
+
+- **In scope:** This repo’s wiring of `@contentstack/delivery-sdk`, `@contentstack/live-preview-utils`, `graphql-request`, and `@timbenniks/contentstack-endpoints` for region URLs.
+- **Out of scope:** Building a generic reusable SDK—this is an application kickstart.
@@ -0,0 +1,51 @@
+---
+name: dev-workflow
+description: Local setup, npm scripts, codegen prerequisites, and CI.
+---
+
+# Dev workflow – Contentstack Kickstart: Next.js GraphQL
+
+## When to use
+
+- Setting up the repo from scratch or onboarding someone new
+- You need the canonical list of npm scripts or to know when to run GraphQL codegen
+- You want to know what GitHub Actions run on pull requests
+
+## Instructions
+
+### Prerequisites
+
+- Node.js and npm suitable for Next.js 16 (see root `package.json` dependencies).
+- A Contentstack stack and tokens; product-specific steps and env variable names are in [README.md](../../README.md).
+
+### Setup
+
+- `npm install` from the repository root.
+- Copy or create `.env` using the variables documented in [README.md](../../README.md) (same names `codegen.ts` reads via `dotenv`).
+
+### npm scripts (canonical list)
+
+| Script | Command | Notes |
+| --- | --- | --- |
+| `dev` | `next dev` | Local development at default Next port |
+| `build` | `next build` | Production build |
+| `start` | `next start` | Run production server after `build` |
+| `lint` | `next lint` | ESLint via Next |
+| `codegen` | `graphql-codegen --config codegen.ts` | Fetches schema from Contentstack GraphQL using env (`apiKey`, `environment`, `region`, delivery token). Run after schema or document changes affecting types |
+
+### Codegen and env
+
+- `codegen.ts` loads `.env` and builds the schema URL from `NEXT_PUBLIC_CONTENTSTACK_*` values. Without valid env, codegen fails.
+- Generated output goes to `gql/`; regenerate with `npm run codegen` instead of hand-editing.
+
+### Branches and pull requests
+
+- There is no `CONTRIBUTING.md` in this repo; follow your team or GitHub organization’s usual PR practices.
+
+### CI on pull requests
+
+- [.github/workflows/policy-scan.yml](../../.github/workflows/policy-scan.yml) — security policy checks (e.g. `SECURITY.md`, license) for public repos
+- [.github/workflows/sca-scan.yml](../../.github/workflows/sca-scan.yml) — supply-chain / dependency scanning
+- [.github/workflows/issues-jira.yml](../../.github/workflows/issues-jira.yml) — issue integration
+
+These workflows do **not** run `npm run build` or `npm run lint`; run those locally before merging when possible.
@@ -0,0 +1,43 @@
+---
+name: framework
+description: Next.js 16 App Router, server vs client components, layout, and Tailwind in this repo.
+---
+
+# Framework (Next.js) – Contentstack Kickstart: Next.js GraphQL
+
+## When to use
+
+- Adding routes, layouts, or moving UI between server and client components
+- Deciding where `Suspense` belongs (e.g. preview + `useSearchParams`)
+- Styling with Tailwind or using the `@/*` import alias
+
+## Instructions
+
+### App Router layout
+
+- [app/layout.tsx](../../app/layout.tsx) — root layout for the application
+- [app/page.tsx](../../app/page.tsx) — home route: async **server** component; chooses preview client branch vs static `getPage("/")` path
+
+### Server vs client components
+
+- Default components under `app/` are **server** components unless marked with `"use client"`.
+- [components/Preview.tsx](../../components/Preview.tsx) is a **client** component (`"use client"`) because it uses `useSearchParams`, React hooks, and Live Preview behavior on the client.
+- [components/Page.tsx](../../components/Page.tsx) — presentational rendering of fetched page data; keep imports consistent with how it is used (from server or client parents).
+
+### Suspense
+
+- When rendering `Preview`, the home page wraps it in `<Suspense>` because `useSearchParams()` in a client subtree expects a boundary in the App Router pattern used here.
+
+### Project structure
+
+- `app/` — routes and layouts
+- `components/` — React UI pieces shared by routes
+- `lib/` — non-UI modules (Contentstack integration, types)
+
+### TypeScript and imports
+
+- [tsconfig.json](../../tsconfig.json) uses `strict: true` and `"paths": { "@/*": ["./*"] }` — import from the repo root with `@/...` (e.g. `@/lib/contentstack`).
+
+### Styling
+
+- Tailwind CSS 4 with `@tailwindcss/postcss` (see `package.json`); PostCSS config is part of the standard Next + Tailwind setup for this project.
@@ -0,0 +1,29 @@
+---
+name: testing
+description: Verifying changes in this repo without a dedicated unit or E2E test suite.
+---
+
+# Testing – Contentstack Kickstart: Next.js GraphQL
+
+## When to use
+
+- Before opening a PR or after touching data fetching, codegen, or routing
+- You need a repeatable smoke path but there is no `npm test` in this project
+
+## Instructions
+
+### Automated checks available today
+
+- **Lint:** `npm run lint`
+- **Typecheck + bundle sanity:** `npm run build` catches many TypeScript and Next.js issues.
+
+There is **no** Jest, Vitest, Playwright, or Cypress setup in `package.json` and no `*.test.*` / `*.spec.*` sources—do not assume a test runner exists.
+
+### GraphQL types
+
+- After changing GraphQL operations, run `npm run codegen` (requires `.env`) and confirm `npm run build` still passes.
+
+### Manual and preview checks
+
+- `npm run dev`, open the app in the browser, exercise the home route and Live Preview flows documented in [README.md](../../README.md).
+- Never commit real API keys, delivery tokens, or preview tokens; use local `.env` only.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Skills – Contentstack Kickstart: Next.js GraphQL

		Each topic is a folder under `skills/` with a single `SKILL.md` inside (YAML frontmatter: `name`, `description`). For the overview and links to every skill, read [AGENTS.md](../AGENTS.md) first.