This guide helps developers transition their Uniform-powered Next.js applications from Page Router to App Router SDK. The migration involves switching to React Server Components (RSC) and updating package dependencies.
Benefits of Migration
Server-side first rendering and access to a plethora of App Router features
Better performance with React Server Components
Simplified SDK with fewer dependencies
Built-in streaming and progressive rendering and PPR-ready functionality
Improved developer experience with modern React patterns
Step 1: Package Dependencies
Remove these packages that are specific to Page Router
Depending on your existing state, you may have some non-Page Router specific that you will likely still need, but make sure to bump their versions to the latest.
Important: The App Router SDK handles context differently:
No need for manual context manifest downloads
Context is managed through server components
Use createServerUniformContext for server-side context
Remove all references to:
@uniformdev/context
@uniformdev/context-next
@uniformdev/context-react
contextManifest.json
Uniform legacy code
Edge middleware
If you are using CDN-specific edge middleware to run edge personalization / Context, it is not necessary anymore, as it is natively supported by the SDK during Server-side rendering time.
Enhancers
If your codebase still uses Uniform enhancers, you can continue using this approach, even though it is discouraged as it adds to the SSR time if your enhancers are computationally intensive. Consider refactoring to the non-enhancer approach and using newer integrations that do not rely on this feature.
Theme Pack
If you use Component Starter Kit's theme pack, you can continue using it but the theme pack components wrapping the application may need to be updated. Newer version of Component Starter Kit is using another approach not compatible with Theme Pack (Design Extensions) and there is no upgrade path.
Other non-Uniform legacy code
Migrate any non-Uniform API routes to the new format of Next.js App Router.
Update typescript, css and dev tools to the latest versions - depending on your needs.
Migration Checklist
[ ] Update package.json dependencies
[ ] Remove uniform:manifest and uniform:publish scripts
[ ] Create uniform.server.config.js
[ ] Update next.config.js with withUniformConfig
[ ] Move pages from pages/ to app/ directory structure
[ ] Convert component registration to resolver pattern
[ ] Update all UniformText/UniformRichText components to include component and context props
[ ] Update slot rendering to new syntax
[ ] Convert preview API route to App Router format
[ ] Remove context manifest references
[ ] Test preview functionality
[ ] Test personalization features
Common Issues
Missing component/context props: App Router components require passing component and context to UniformText/UniformRichText
Slot syntax: Remember to use slot={slots.name} instead of name="name"
Component registration: Use resolver pattern instead of registerUniformComponent
Preview routes: API routes must be in separate files (GET, POST, OPTIONS)
Context manifest: Do NOT include manifest download commands - they're not needed!