{title}
+ ) +} +``` + +Should now be + +```jsx +type HeroParamters = { + title: ComponentParameter{title.value}
+ ) +} +``` + +This change was made to keep the full parameter intact and hopefully be able to use this data to implement conditional values. + +### UniformSlot + +The slot definition type used to look like this: + +```jsx +export type SlotDefinition = { + name: string; + items: PropsWithChildren['children'][]; +}; +``` + +Now it looks like this: + +```jsx +export type SlotDefinition = { + name: string; + items: ({ + _id: string; + [CANVAS_PERSONALIZATION_PARAM]: VariantMatchCriteria | undefined; + component: ReactNode; + } | null)[]; +}; +``` + +Slots can be rendered with a single prop: + +```jsx +This is a page.
+ );
+};
+
+```
+
+### Adapter Components
+
+An adapter layer also exists to easy the transition from V1 to V2, use the built in `createAdapterResolveComponentFunction` function and pass the component mappings for your site.
+
+```jsx
+import { createAdapterResolveComponentFunction } from '@uniformdev/next-app-router/compat';
+
+import * as mappings from './mappings';
+
+export const resolveComponent = createAdapterResolveComponentFunction({ mappings });
+
+```
+
+Adjust your mappings to use `ResolveComponentResultWithType` and adding `mode: 'adapted'` to each definition that you are adapting.
+
+```tsx
+import type {
+ ComponentProps,
+ ResolveComponentResultWithType,
+} from '@uniformdev/next-app-router/compat';
+
+type PageComponentParameters = {
+ text: string;
+};
+
+const PageComponent = ({ text }: ComponentProps{text}
;
+};
+
+export const pageMapping: ResolveComponentResultWithType = {
+ type: 'page',
+ component: PageComponent,
+ mode: 'adapted',
+};
+```
+
+Use `UniformText` and `UniformSlot` components from the same `compat` export.
+
+### Clients
+
+- `getDefaultRouteClient` is now `getRouteClient`
diff --git a/rules/optional-personal-preference/solution-architecture.mdc b/rules/optional-personal-preference/solution-architecture.mdc
index d35d08d..b832273 100644
--- a/rules/optional-personal-preference/solution-architecture.mdc
+++ b/rules/optional-personal-preference/solution-architecture.mdc
@@ -9,7 +9,6 @@ alwaysApply: false
- Always generate clean code and remove unused code, so the linter and typescript checks pass automatically. IMPORTANT: do not ever run build of the application as a part of the validation as this breaks developer server and is causing issues.
- Always use `pnpm` to install packages if you see `pnpm-lock.yaml` in the root folder, otherwise use `npm`. Never use `yarn`.
-
- You are a senior React engineer, follow best practices of React at all times.
- Use TailwindCSS best practices when building CSS. Don't re-invent the wheel.
- You are a senior engineer, do not try to impress me with over-delivery.
diff --git a/rules/uniform-next-app-router.mdc b/rules/uniform-next-app-router.mdc
index 5ee5bb2..3630c72 100644
--- a/rules/uniform-next-app-router.mdc
+++ b/rules/uniform-next-app-router.mdc
@@ -3,332 +3,595 @@ description: Rules for Uniform SDK for Next.js App Router
globs:
alwaysApply: true
---
+# Uniform React Next.js App Router SDK Developer Reference
-# Uniform React Next App Router Developer Reference
-
-This document details how to use Uniform with React.js with Next App Router.
+This document details how to use Uniform SDK with React.js and Next.js App Router.
@uniform.mdc describes general Uniform principles and practices.
@uniform-sdk.mdc describes framework-agnostic developer principles.
-### Required npm packages
+## Required npm packages (version 20.58.0 or later)
+
+```json
+{
+ "@uniformdev/next-app-router": "20.58.0",
+ "@uniformdev/context": "20.58.0",
+}
+```
+
+## File Structure
+
+Required file structure:
-The following npm packages must be installed to wire Uniform to Next App Router:
+```
+app/
+├── api/
+│ └── preview/
+│ └── route.ts # Preview handler
+├── layout.tsx # Root layout
+├── uniform/
+│ └── [code]/
+│ └── page.tsx # Main composition route
+└── playground/
+ └── [code]/
+ └── page.tsx # Playground route
+middleware.ts # Required for edge personalization
+uniform.server.config.ts # Server configuration
+next.config.ts # Next.js config with withUniformConfig
+```
-@uniformdev/canvas-next-rsc
-@uniformdev/canvas
+## Server Configuration
-### Uniform server config
+### uniform.server.config.ts is optional now:
-A file names `uniform.server.config.js` should exist in the root of the Next.js project with the following content:
+```ts
+import { UniformServerConfig } from "@uniformdev/next-app-router/config";
-```js
-/** @type {import('@uniformdev/canvas-next-rsc/config').UniformServerConfig} */
-module.exports = {
+const config: UniformServerConfig = {
defaultConsent: true,
- evaluation: {
- personalization: "hybrid",
+ playgroundPath: "/playground"
+};
+
+export default config;
+```
+
+Full configuration options:
+
+```ts
+const config: UniformServerConfig = {
+ // Default storage consent for new visitors
+ defaultConsent: true,
+
+ // Path to playground page
+ playgroundPath: "/playground",
+
+ // ETag support for caching
+ eTags: {
+ generateETags: true,
+ cacheControl: "no-cache, must-revalidate",
},
- experimental: {
- quirkSerialization: true,
+
+ // Context options
+ context: {
+ disableDevTools: false,
},
+
+ // Quirk and middleware options
+ quirkSerialization: true,
+ middlewareRuntimeCache: true,
+ disableSwrMiddlewareCache: false,
};
```
-### Enable Uniform server config
+### next.config.ts
+
+```ts
+import { withUniformConfig } from "@uniformdev/next-app-router/config";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+ // your Next.js config options
+};
+
+export default withUniformConfig(nextConfig);
+```
+
+## Middleware (Required)
+
+Middleware in `middleware.ts` at project root is required.
+
+**IMPORTANT for Next.js 16:** To support Uniform preview in Canvas:
+1. The middleware file **MUST** be named `middleware.ts` (not `proxy.ts` or other names)
+2. **MUST** export the runtime value:
+
+```ts
+export const runtime = 'experimental-edge';
+```
+
+### Basic middleware
+
+```ts
+import { uniformMiddleware } from "@uniformdev/next-app-router/middleware";
+
+export default uniformMiddleware();
+
+// Required for Next.js 16 preview support
+export const runtime = 'experimental-edge';
+```
+
+### Middleware with locale handling
+
+```ts
+import { uniformMiddleware } from "@uniformdev/next-app-router/middleware";
+
+const defaultLocale = "en";
+const locales = ["en"];
-To make the configuration available in Next.js, modify the next.config.js file in the root of the project and add in `withUniformConfig`:
+export default uniformMiddleware({
+ rewriteRequestPath: async ({ url }) => ({
+ path: formatPath(url.pathname, defaultLocale),
+ }),
+});
-```js
-const { withUniformConfig } = require("@uniformdev/canvas-next-rsc/config");
+const formatPath = (path: string, locale?: string | null): string => {
+ if (!locale) return path;
+ if (isLocaleInPath(path)) return path;
+ return `/${locale}${path}`;
+};
-/** @type {import('next').NextConfig} */
-const nextConfig = {
- reactStrictMode: true,
+const isLocaleInPath = (path: string): boolean => {
+ const [firstSegment] = path.split("/").filter(Boolean);
+ return firstSegment
+ ? (locales as string[]).some((locale) => locale === firstSegment)
+ : false;
};
-module.exports = withUniformConfig(nextConfig);
+// Required for Next.js 16 preview support
+export const runtime = 'experimental-edge';
```
-### Fetching and rendering the composition
+### Full middleware options
+
+```ts
+import { uniformMiddleware } from "@uniformdev/next-app-router/middleware";
+
+export default uniformMiddleware({
+ // Rewrite request path before route resolution
+ rewriteRequestPath: async ({ url, request }) => ({
+ path: url.pathname,
+ keys: { locale: "en" }, // Custom keys passed to composition
+ }),
+
+ // Rewrite destination after evaluation
+ rewriteDestinationPath: async ({ code, pageState, source }) => {
+ return `/uniform/${code}`;
+ },
+
+ // Paths that should precompute personalizations
+ pathPatternsWithVariations: ["/products/*"],
+
+ // Content release
+ release: { id: "release-123" },
+
+ // Custom quirks to inject
+ quirks: { customQuirk: "value" },
+
+ // Override default consent
+ defaultConsent: true,
+});
+
+// Required for Next.js 16 preview support
+export const runtime = 'experimental-edge';
+```
+
+## Main Composition Route
-In your dynamic route file (`app/[[...path]]/page.{tsx|jsx}`), it is necessary to fetch the Uniform composition instance for the current route.
+`app/uniform/[code]/page.tsx`:
```tsx
import {
+ resolveRouteFromCode,
UniformComposition,
- PageParameters,
- retrieveRoute,
-} from "@uniformdev/canvas-next-rsc";
-import { resolveComponent } from "@/uniform/resolve";
+ UniformPageParameters,
+ createUniformStaticParams,
+} from "@uniformdev/next-app-router";
+import { resolveComponent } from "@/components/resolveComponent";
+
+// Enable ISR (Incremental Static Regeneration)
+export const generateStaticParams = async () => {
+ return createUniformStaticParams({
+ // paths: ["/"],
+ // Important: for localized sites, you need to add the locales to the paths
+ paths: ["/en"],
+ });
+};
-export default async function Page(props: PageParameters) {
- const route = await retrieveRoute(props);
+export default async function UniformPage(props: UniformPageParameters) {
+ const { code } = await props.params;
return (
- <>
- Not Found: {type}
;
};
```
-#### Accessing parameters
+## Component Props and Parameters
+
+**CRITICAL:**
+1. Parameter types must be wrapped with `ComponentParameter{title?.value}
; }; -type HeaderSlots = "logo" | "navigation"; +``` -type HeaderProps = ComponentProps
+ {child}
+
+ )}
+Current country: {quirks?.country ?? "Unknown"}
;
};
+```
-type HeaderProps = ComponentPropsTech interest score: {scores?.tech ?? 0}
;
};
```
-Note: asset parameters are rendered directly from props, there is no `UniformAsset` component.
+### Custom Client Context Component
+
+For advanced configuration with plugins:
+
+```tsx
+"use client";
-##### Asset parameters/fields
+import { ContextPlugin, enableContextDevTools } from "@uniformdev/context";
+import { useRouter } from "next/navigation";
+import {
+ createClientUniformContext,
+ useInitUniformContext,
+ ClientContextComponent,
+} from "@uniformdev/canvas-next-rsc-client-v2";
+
+export const CustomUniformClientContext: ClientContextComponent = ({
+ manifest,
+ disableDevTools,
+ defaultConsent,
+ experimentalQuirkSerialization,
+ compositionMetadata,
+}) => {
+ const router = useRouter();
+
+ useInitUniformContext(() => {
+ const plugins: ContextPlugin[] = [];
+
+ if (!disableDevTools) {
+ plugins.push(
+ enableContextDevTools({
+ onAfterMessageReceived: () => {
+ router.refresh();
+ },
+ })
+ );
+ }
+
+ return createClientUniformContext({
+ manifest,
+ plugins,
+ defaultConsent,
+ experimental_quirksEnabled: experimentalQuirkSerialization,
+ });
+ }, compositionMetadata);
+
+ return null;
+};
+```
-1. CRITICAL: Always use `flattenValues` from `@uniformdev/canvas` for handling asset parameters, not custom utility functions.
-2. CRITICAL: Destructure asset parameters directly from component props (e.g., `{ logos, component, context }`) rather than accessing through `component?.parameters?.parameterName`.
-3. Use `flattenValues(assetParam)` directly - it handles both single and multiple assets automatically.
+Pass to UniformContext:
+
+```tsx
+