## Kickstart Next GraphQL - **Published:** 2026-03-17T11:53:05.488Z - **Updated:** 2026-04-02T11:28:40.874Z - **Tags:** next, react, graphql --- This is the Next kickstart for teams that want the same lightweight Contentstack starter experience, but prefer working through GraphQL instead of the Delivery SDK query chain. It still feels like the base Next kickstart on the surface, but the data layer is different enough that it is worth treating as its own pattern. If your team likes typed queries, generated GraphQL artifacts, and an explicit schema-driven fetch layer, this is the one to study. > This page is a practical developer guide, not a replacement for the official docs. Use it to understand how the GraphQL version is wired and where it differs from the REST-based examples. > > ## Watch It First If you want a quick feel for the GraphQL version before reading the repo: ## What makes this variant different The biggest change is simple: content is fetched through GraphQL, not through stack.contentType(...).query(). That changes the way you think about the integration: - your data contract is described in a GraphQL query - preview behavior is applied through GraphQL headers and endpoint switching - generated GraphQL helpers become part of the workflow - response shaping becomes your responsibility before you add editable tags So even though the visible page looks very similar to the base kickstart, the developer ergonomics are different. ## What you get out of the box The current contentstack/kickstart-next-graphql repo includes: - Next.js App Router - graphql-request for executing queries - generated GraphQL client artifacts in gql/ - a codegen.ts configuration for pulling schema types - Live Preview support - Visual Builder editable fields - the same seeded homepage content structure as the other Next kickstarts This makes it useful both as a starter and as a small GraphQL reference project. ## How this specific kickstart works ### 1. lib/contentstack.ts switches between delivery and preview GraphQL endpoints This file does more than initialize preview support. It also decides whether the app should hit the normal GraphQL delivery endpoint or the preview GraphQL endpoint. The choice is based on whether preview mode is active and whether ContentstackLivePreview.hash is available. When preview is active, the request headers include values such as: - live_preview - preview_token - preview_timestamp That is the GraphQL version of the same preview handshake you see in the other kickstarts. ### 2. The page query is explicit and easy to inspect Instead of using SDK query builders, getPage() sends a GraphQL query for all_page(where: { url: $url }). That gives you a very clear view of the content contract: - page fields - image fields - modular blocks - nested asset connections If you are teaching a team how Contentstack content maps into a frontend through GraphQL, this is one of the nicest parts of the repo. ### 3. The repo reshapes GraphQL data for Visual Builder One subtle but important detail: the GraphQL response does not naturally match the same shape the editable-tag utility expects. So the repo maps the response back into a friendlier entry-like object, including flattening image connections and block image connections, before calling contentstack.Utils.addEditableTags(...). That is a very practical lesson. In GraphQL projects, preview support often means a little response normalization work. ### 4. codegen.ts makes the schema part of the workflow The repo includes GraphQL Code Generator configuration, which points at the Contentstack GraphQL schema using your environment variables. That means the kickstart is not just "fetch with GraphQL". It also nudges you toward a more typed, schema-aware setup that many frontend teams prefer in larger apps. ### 5. components/Preview.tsx still uses client-side live updates The current repo uses a client-side preview component that listens for changes with ContentstackLivePreview.onEntryChange(...), then re-fetches the page through GraphQL. So the main difference is the data layer, not the editor experience. You still get an approachable preview loop while learning a different way to query content. ## What you are really learning from this project This variant is useful because it teaches more than GraphQL syntax: - how to structure a page query around a URL field - how preview and GraphQL headers work together - how to normalize GraphQL responses for editable tags - how generated artifacts can improve a Contentstack frontend workflow If your team is already comfortable with GraphQL, this version often feels closer to how a real app will evolve. ## When to choose this one Choose the GraphQL kickstart when: - your team prefers schema-driven frontend development - you want more explicit control over the returned fields - you plan to use generated query artifacts and types - you want to build Contentstack pages without centering everything on the Delivery SDK query builder If you want the most direct "just connect Contentstack and go" example, the base Next kickstart is still the simpler starting point. ## Fastest way to try it The setup flow is familiar: - Seed or reuse the kickstart stack. - Create a delivery token with preview enabled. - Add the stack values to .env. - Enable Live Preview for the same environment. - Run npm install and npm run dev. If you want to go a step further after that, run the repo’s npm run codegen command so you can see how the generated GraphQL client fits into the project. ## A good next step after the first run After the homepage works, add a second GraphQL query for a new content type and keep the same response-normalization pattern for preview tags. That is where this kickstart becomes especially valuable as a working reference.