## Kickstart Next Middleware - **Published:** 2026-03-17T11:53:06.498Z - **Updated:** 2026-04-02T11:31:08.377Z - **Tags:** next, react --- This is the Next kickstart to look at when you do not want your page components talking directly to Contentstack on every fetch. Instead of querying Contentstack straight from the page layer, this variant introduces a small proxy-style API route inside the Next app. In the current repo, that "middleware" idea is implemented as a local API endpoint rather than Next.js edge middleware, which actually makes the architecture easier to study. It gives you a cleaner seam for adding custom logic later, such as request shaping, caching, auth checks, or response normalization. > This page is a practical developer guide, not a replacement for the official docs. Use it to understand the architecture choice behind this variant and how the code is actually flowing today. > > ## Watch It First If you want to see the middleware version in action first: ## What makes this variant different The architecture is the real lesson here. Instead of this flow: - page component - Contentstack SDK - Contentstack API you get this: - page component - local Next API route - Contentstack API That extra layer may seem small, but it changes the extension points of the whole app. It is the kickstart to study when you want a lightweight BFF or proxy pattern without jumping straight into a much larger backend architecture. ## What you get out of the box The current contentstack/kickstart-next-middleware repo includes: - Next.js App Router - a local API route at app/api/middleware/route.ts - client-side Live Preview support - Visual Builder editable fields - the same seeded page content model as the other Next kickstarts - a fetch path that runs through your own app before going to Contentstack The homepage still looks familiar. The difference is where the fetch logic lives. ## How this specific kickstart works ### 1. app/api/middleware/route.ts is the proxy layer This route is the heart of the example. It accepts query parameters such as the content type, page URL, live preview hash, and preview timestamp. Then it: - decides whether to call the delivery or preview hostname - builds the correct REST API URL for Contentstack - forwards the right headers and preview values - fetches the entry from Contentstack - adds editable tags before returning the entry as JSON That means your frontend code can stay simple while this route becomes the one place that knows how to talk to Contentstack. ### 2. lib/contentstack.ts fetches through your own API The browser-side getPage() helper does not call the Delivery SDK directly. It builds a URL for /api/middleware, adds the current path and preview details, and fetches the JSON entry from your own app. That is the key pattern to notice: this kickstart centralizes the Contentstack fetch mechanics behind a local endpoint. ### 3. app/page.tsx passes the site base URL into preview mode Because the preview component needs to call the local API route, the page derives the current baseUrl from request headers and passes it into the preview component. This is a small detail, but it shows the practical reality of proxy-based setups. Once you introduce an internal API layer, your fetch path needs to know where that layer lives. ### 4. components/Preview.tsx re-fetches through the proxy on entry changes The preview component initializes Live Preview and listens for changes with ContentstackLivePreview.onEntryChange(...). When content changes, it calls getPage(baseUrl, path, "page", previewTimestamp) again, which means the updated draft content still comes back through the local API route instead of bypassing it. So the middleware layer is not just for normal page loads. It is part of the preview loop too. ## What you are really learning from this project This variant is useful because it teaches a pattern that scales well: - keep Contentstack request logic behind an application boundary - centralize preview and delivery header handling - leave room for future business logic in one place - keep page components focused on rendering That makes it a strong starting point for teams that already know they want a proxy or BFF layer in front of Contentstack. ## When to choose this one Choose the middleware kickstart when: - you want your app to own the request layer instead of calling Contentstack directly from the page - you expect to add custom headers, logic, or transformations later - you want a clean place to handle preview-specific request behavior - you like the idea of hiding Contentstack request details behind your own endpoint If you do not need that extra layer yet, the base Next or SSR kickstarts are easier to reason about. ## Fastest way to try it The setup is similar to the other Next variants: - 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. The interesting part comes after that: inspect the network flow and notice that the page is reading from your Next API route, which then talks to Contentstack on its behalf. ## A good next step after the first run Once it works, add a small piece of custom logic to the proxy route before you touch the UI. That is the best way to feel why this architecture exists. Even something simple like response shaping, logging, or conditional caching makes the value obvious.