Developing locally with Next.js App Router SDK

When developing locally with the Uniform SDK, there are a few behaviors to be aware of that can affect your workflow. This page covers the most common friction points and how to work around them.

By default, Next.js aggressively caches data fetched during rendering in the .next directory. This means that content you update in Uniform may not appear in your local app until the cache is cleared. If you change content in Uniform and don't see updates reflected locally, the fastest fix is:

  1. Stop the dev server.
  2. Delete the .next folder.
  3. Restart the dev server.
rm -rf .next && npm run dev

This is a blunt approach. The sections below describe better ways to avoid this problem during active development.

Working with draft content#

You do not need to publish content to see updates in your local development environment. The SDK can pull draft (unpublished) content directly, which is much faster for iterating on content changes.

To activate draft mode, the easiest method is to open your local app from the Uniform preview panel:

  1. Open a composition in Canvas.
  2. Click the preview panel.
  3. From the menu in the preview panel, choose Open in new window.
open-new-tab
Open new windo

This opens your local app with the preview query parameters, which activates Next.js Draft Mode. While draft mode is active:

  • The SDK fetches draft content instead of published content.
  • Next.js data caching is bypassed (no stale content from .next).
  • You see content changes immediately without restarting the dev server.

note

Make sure your UNIFORM_PREVIEW_SECRET environment variable is set in .env.local and matches the secret configured in your Uniform project's preview URL. Without it, the preview handler will reject the request.

For a more permanent solution during development, you can disable all Uniform SDK caching in your uniform.server.config.ts. This tells the SDK to bypass the cache for every data fetch -- compositions, project map, and personalization manifest are always pulled fresh from the Uniform API.

// uniform.server.config.ts import { UniformServerConfig } from "@uniformdev/next-app-router/config"; const config: UniformServerConfig = { // Bypass all caches -- always fetch fresh data canvasCache: { bypassCache: true, }, projectMapCache: { bypassCache: true, }, manifestCache: { bypassCache: true, }, }; export default config;

warning

Do not deploy this configuration to production. Bypassing all caches causes every page render to make fresh API calls to Uniform, which significantly increases response times and API usage. This is acceptable for local development but will degrade performance in production.

A safe pattern is to use an environment variable to conditionally enable bypass:

const isDev = process.env.NODE_ENV === "development"; const config: UniformServerConfig = { defaultConsent: true, canvasCache: { bypassCache: isDev, }, projectMapCache: { bypassCache: isDev, }, manifestCache: { bypassCache: isDev, }, };

This way, cache bypass is active only when running npm run dev and never in production builds.

ApproachHowWhen to use
Delete .next and restartrm -rf .next && npm run devQuick one-off fix when content looks stale
Draft mode via previewOpen app from Uniform preview panelIterating on content changes without publishing
bypassCache in server configSet bypassCache: true for all cachesOngoing development where you always want fresh data
Conditional bypass via NODE_ENVWrap bypassCache in process.env.NODE_ENV === "development"Safest option -- no risk of accidentally deploying with caching disabled
Last modified
Next
ISR (Incremental Static Regeneration)