Choose a setup
Developer preview
The SDK supports different setups. Answer the three questions on this page to select the setup for your app. If you do not know, use the recommended answer of each question. You can change the setup later.
| Question | Recommended answer |
|---|---|
| Which routes render Uniform content? | The [code] route |
| Who chooses the personalization variants? | The edge (edge mode) |
| How does Next.js cache the pages? | ISR, with pages rendered on their first visit |
1. Which routes render Uniform content?#
| Setup | Use it when | Refer to |
|---|---|---|
The [code] route (recommended) | Authors build the pages in Uniform, and the project map has the URLs. One route file renders all pages. | Tutorial |
| Ordinary routes | You need your own route files, for example app/blog/[slug]/page.tsx, for each page type. The page resolves the composition from its path. | Use ordinary Next.js routes |
| Hybrid pages | The pages are hard-coded in Next.js already. Uniform manages only some regions of each page, for example banners. | Hybrid pages |
With ordinary routes and hybrid pages, each project map node that has a composition must have a Next.js route. Without a route, the path gives a 404, also in Canvas preview.
2. Who chooses the personalization variants?#
| Lite mode | Edge mode (recommended) | |
|---|---|---|
| Middleware | uniformMiddleware | vercelUniformEdgeMiddleware, or uniformEdgeMiddleware on other hosts |
| What the visitor sees first | The default variants. Then the browser changes them. | The variants of the visitor |
| Extra packages | None | @vercel/functions on Vercel |
| Extra cost | None | One more request for each page load, and CPU time for the transform |
| Use it when | The site has no personalizations or tests above the fold, or the change after hydration is acceptable. | Personalizations or tests are visible on the first screen. |
Visibility rules run in the browser in the two modes. Refer to Personalization and A/B tests and Edge mode execution.
Edge mode on Vercel or on other hosts#
| Host | Middleware | Manifest | Cache expiry |
|---|---|---|---|
| Vercel | vercelUniformEdgeMiddleware() | Loaded at runtime, kept in the Vercel runtime cache | onRevalidateTags: expireVercelRuntimeCacheTags |
| Other hosts | uniformEdgeMiddleware({ manifest }) | A JSON file from the build, or createCachedManifestProvider with your cache | The next build, or your cache |
Refer to Set up edge mode on other hosts.
3. How does Next.js cache the pages?#
| Strategy | Setup | Use it when |
|---|---|---|
| ISR, rendered on the first visit (recommended) | generateStaticParams returns []. | Most sites. The build is fast, and only the first visitor of each page waits for the render. |
| ISR, with prerendered pages | generateStaticParams returns createUniformStaticParams({ paths }). | The first visit of the most important pages must be fast. |
| Cache Components | cacheComponents: true, and the resolvers from @uniformdev/next-app-router/cache. | Your app uses Cache Components already, or parts of the page are dynamic. |
In all strategies, Uniform webhooks revalidate the cached pages when authors publish. Refer to Static generation (ISR) and Caching.
warning
With Cache Components, Next.js does not accept an empty generateStaticParams. Return at least one code.
Examples#
| App | Routes | Variants | Cache |
|---|---|---|---|
| Marketing site with campaign personalization on the home page | [code] route | Edge mode | ISR, prerender the home page |
| Documentation site without personalization | [code] route | Lite mode | ISR on the first visit |
| Commerce site with product pages in Next.js and banners from Uniform | Hybrid pages | Edge mode | ISR on the first visit |
| Blog with its own route files | Ordinary routes | Lite mode | ISR on the first visit |