@cyclone-ui/nextjs 0.0.15 → 0.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,33 @@
2
2
 
3
3
  # Changelog for Cyclone UI - Nextjs
4
4
 
5
+ ## [0.0.16](https://github.com/storm-software/cyclone-ui/releases/tag/nextjs%400.0.16) (11/03/2026)
6
+
7
+ ### Bug Fixes
8
+
9
+ - **nextjs:** Added missing items to `tsconfig.json` file ([cedb01651](https://github.com/storm-software/cyclone-ui/commit/cedb01651))
10
+ - **monorepo:** Update workspace component to better support nextjs SSR ([dff5b74cd](https://github.com/storm-software/cyclone-ui/commit/dff5b74cd))
11
+
12
+ ### Updated Dependencies
13
+
14
+ - Updated **bar-chart** to **v0.0.16**
15
+ - Updated **calendar** to **v0.0.33**
16
+ - Updated **chart** to **v0.0.16**
17
+ - Updated **composed-chart** to **v0.0.16**
18
+ - Updated **footer** to **v0.0.46**
19
+ - Updated **page** to **v0.0.42**
20
+ - Updated **state** to **v0.0.46**
21
+ - Updated **theme-builder** to **v0.0.34**
22
+ - Updated **tokens** to **v0.3.33**
23
+
24
+ ## [0.0.15](https://github.com/storm-software/cyclone-ui/releases/tag/nextjs%400.0.15) (11/03/2026)
25
+
26
+ ### Updated Dependencies
27
+
28
+ - Updated **state** to **v0.0.45**
29
+ - Updated **theme-builder** to **v0.0.33**
30
+ - Updated **tokens** to **v0.3.32**
31
+
5
32
  ## [0.0.14](https://github.com/storm-software/cyclone-ui/releases/tag/nextjs%400.0.14) (11/03/2026)
6
33
 
7
34
  ### Bug Fixes
package/README.md CHANGED
@@ -1,4 +1,7 @@
1
- # @cyclone-ui/nextjs
1
+ <!-- START header -->
2
+ <!-- END header -->
3
+
4
+ # Cyclone UI - NextJS
2
5
 
3
6
  Set up [Tamagui](https://tamagui.dev) and Cyclone UI components in a Next.js
4
7
  application. The package has two entry points:
@@ -38,19 +41,23 @@ Wrap the Next.js config:
38
41
 
39
42
  ```ts
40
43
  // next.config.ts
41
- import { withCycloneUI } from "@cyclone-ui/nextjs";
44
+ import { withCycloneUI } from "@cyclone-ui/nextjs"
42
45
 
43
46
  export default withCycloneUI({
44
47
  reactStrictMode: true
45
- });
48
+ })
46
49
  ```
47
50
 
51
+ The wrapper also accepts a promised config or a sync/async Next.js config
52
+ function. Phase functions remain lazy and receive the original phase and context;
53
+ existing `cacheComponents` and `partialPrefetching` values are preserved.
54
+
48
55
  Render the provider in the root layout. The provider sets a class on `<html>`
49
56
  before React hydrates, so add `suppressHydrationWarning` there:
50
57
 
51
58
  ```tsx
52
59
  // app/layout.tsx
53
- import { CycloneUIProvider } from "@cyclone-ui/nextjs/provider";
60
+ import { CycloneUIProvider } from "@cyclone-ui/nextjs/provider"
54
61
 
55
62
  export default function RootLayout({
56
63
  children
@@ -63,19 +70,43 @@ export default function RootLayout({
63
70
  <CycloneUIProvider>{children}</CycloneUIProvider>
64
71
  </body>
65
72
  </html>
66
- );
73
+ )
74
+ }
75
+ ```
76
+
77
+ The layout remains a Server Component. The client provider accepts server-rendered
78
+ children without moving those child modules into the client bundle. Props that
79
+ cross this boundary must be serializable by React. The default config is already
80
+ imported inside the provider; if passing a custom Tamagui `config` or an ordinary
81
+ callback such as `onChangeTheme`, define them inside an application-owned client
82
+ wrapper:
83
+
84
+ ```tsx
85
+ // app/providers.tsx
86
+ "use client"
87
+
88
+ import { CycloneUIProvider } from "@cyclone-ui/nextjs/provider"
89
+ import type { PropsWithChildren } from "react"
90
+ import { config } from "@/tamagui.config" // Use your config's actual export.
91
+
92
+ export function AppProviders({ children }: PropsWithChildren) {
93
+ return <CycloneUIProvider config={config}>{children}</CycloneUIProvider>
67
94
  }
68
95
  ```
69
96
 
97
+ Render `<AppProviders>{children}</AppProviders>` from the server layout. The
98
+ build-time `tokens` option below also replaces the provider's config import, so
99
+ it needs no `config` prop.
100
+
70
101
  Read or change the theme with `useThemeSetting`:
71
102
 
72
103
  ```tsx
73
- "use client";
104
+ "use client"
74
105
 
75
- import { useThemeSetting } from "@cyclone-ui/nextjs/provider";
106
+ import { useThemeSetting } from "@cyclone-ui/nextjs/provider"
76
107
 
77
108
  export function ThemeToggle() {
78
- const theme = useThemeSetting();
109
+ const theme = useThemeSetting()
79
110
 
80
111
  return <button onClick={theme.toggle}>Change theme</button>
81
112
  }
@@ -91,21 +122,24 @@ System preference changes apply when the selected setting is `system`.
91
122
 
92
123
  ### Cache Components and static shells
93
124
 
94
- Enable the caching options explicitly in the consuming App Router app:
125
+ Cache Components in Next.js 16 includes Partial Prerendering (PPR): a prerendered
126
+ shell with dynamic content streamed through Suspense. Partial Prefetching is a
127
+ separate navigation feature introduced in Next.js 16.3 and requires Cache
128
+ Components. Check your installed Next.js version before adding flags. For
129
+ Next.js 16.3+ when adopting both features:
95
130
 
96
131
  ```ts
97
- import { withCycloneUI } from "@cyclone-ui/nextjs";
132
+ import { withCycloneUI } from "@cyclone-ui/nextjs"
98
133
 
99
134
  export default withCycloneUI({
100
135
  cacheComponents: true,
101
136
  partialPrefetching: true
102
- });
137
+ })
103
138
  ```
104
139
 
105
- `withCycloneUI` preserves these options; it does not enable them globally.
106
- `partialPrefetching` requires `cacheComponents` and a Next.js version that
107
- supports the option. It changes Link prefetch behavior to fetch the static App
108
- Shell; it does not make request-dependent content static.
140
+ `withCycloneUI` preserves these options; it does not enable them globally or
141
+ choose a caching policy. On Next.js 16.0–16.2, omit `partialPrefetching`. Do not
142
+ combine `cacheComponents` with the older `experimental.ppr` flag.
109
143
 
110
144
  Keep the root layout synchronous and render `CycloneUIProvider` directly around
111
145
  its children, as above. The provider does not read `cookies()` or `headers()`
@@ -117,22 +151,38 @@ Do not read a theme cookie in the root layout just to populate `mode`. `mode` is
117
151
  an SSR/hydration fallback, not the user's persisted preference. `modeCookie` is
118
152
  an optional client-written mirror of the resolved light/dark mode; it does not
119
153
  require a server cookie read or preserve the distinction between system and an
120
- explicit choice. If a server component needs request cookies, put that component
121
- under a local `<Suspense>` boundary. Do not put cookie reads inside `"use cache"`
122
- or move the whole provider behind that boundary. Cached Server Components can
123
- be passed as children through the client provider.
154
+ explicit choice. Put request reads such as `cookies()`, `headers()`, and
155
+ `searchParams` inside the component that needs them, under a local `<Suspense>`
156
+ boundary with a useful fallback. Do not put those reads inside `"use cache"` or
157
+ move the whole provider behind that boundary. Server Components, including
158
+ cached ones, can be passed as children through the client provider.
159
+
160
+ Static JSX needs no `"use cache"`. Cache reusable application data or server UI
161
+ according to its freshness and invalidation policy; keep uncached live work
162
+ behind local Suspense. Do not add the directive to client providers or client
163
+ primitives as a general optimization.
124
164
 
125
165
  Use semantic theme tokens and relative sub-themes such as `base` in the shell.
126
166
  Avoid choosing server markup or literal colors from a browser theme preference.
127
167
  Theme-dependent text from `useThemeSetting().current`, `resolvedTheme`,
128
- `useRootTheme`, or `useThemeMode` must wait until that component mounts. These values can differ
129
- between the server and the first browser render. The constant-label toggle
168
+ `useRootTheme`, or `useThemeMode` must wait until that component mounts. These
169
+ values can differ between the server and the first browser render. The constant-label toggle
130
170
  above needs no mount guard. If showing a current-mode label, guard only that
131
171
  label/control, keeping the rest of the shell rendered. `suppressHydrationWarning`
132
172
  on `<html>` does not suppress mismatches in descendants.
133
173
 
134
- See [Next.js caching](https://nextjs.org/docs/app/getting-started/caching) and
135
- [partialPrefetching](https://nextjs.org/docs/app/api-reference/config/next-config-js/partialPrefetching).
174
+ With Partial Prefetching enabled, default links prefetch a reusable route App
175
+ Shell rather than all of a destination's content. Use `prefetch={true}` on
176
+ selected application links to also resolve cached URL-specific content depending
177
+ on `params`, `searchParams`, or the full URL. It no longer includes uncached
178
+ dynamic content from the legacy full prefetch; that content streams after
179
+ navigation. Audit existing `prefetch={true}` links before enabling the flag, and
180
+ verify concrete URL navigations in production. Avoid imposing full prefetching
181
+ on every shared link primitive.
182
+
183
+ See [Next.js caching](https://nextjs.org/docs/app/getting-started/caching),
184
+ [adopting Partial Prefetching](https://nextjs.org/docs/app/guides/adopting-partial-prefetching),
185
+ and [optimizing prefetching](https://nextjs.org/docs/app/guides/optimizing-prefetching).
136
186
 
137
187
  ### Custom design tokens
138
188
 
@@ -142,7 +192,7 @@ globs relative to the working directory:
142
192
 
143
193
  ```ts
144
194
  // next.config.ts
145
- import { withCycloneUI } from "@cyclone-ui/nextjs";
195
+ import { withCycloneUI } from "@cyclone-ui/nextjs"
146
196
 
147
197
  export default withCycloneUI(
148
198
  { reactStrictMode: true },
@@ -153,7 +203,7 @@ export default withCycloneUI(
153
203
  "tokens/dark.tokens.json"
154
204
  ]
155
205
  }
156
- );
206
+ )
157
207
  ```
158
208
 
159
209
  Files with a theme name (`light.tokens.json`, `dark.tokens.json`, …) become
@@ -161,8 +211,10 @@ the `light` and `dark` themes. The tokens go through the same preprocessor and
161
211
  generator as `@cyclone-ui/tokens`, and a `razorwind.config.ts` in the project
162
212
  still applies (for example its fonts).
163
213
 
164
- With `tokens`, `withCycloneUI` returns a promise, which Next.js accepts as the
165
- config export. The config is written to `.cyclone-ui/tamagui.config.ts`
214
+ With `tokens` and an object config, `withCycloneUI` returns a promise, which
215
+ Next.js accepts as the config export. For a phase function, token generation runs
216
+ when Next.js resolves that function. Compose object-only third-party wrappers
217
+ before the token build. The config is written to `.cyclone-ui/tamagui.config.ts`
166
218
  (add `.cyclone-ui` to `.gitignore`) and replaces `@cyclone-ui/tokens/tamagui`
167
219
  everywhere, so `CycloneUIProvider` and the Webpack compiler use it. With
168
220
  pnpm, Webpack builds also need `@tamagui/web` and `motion` installed in the
@@ -177,7 +229,7 @@ project root.
177
229
 
178
230
  | Prop | Default | Description |
179
231
  | ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------ |
180
- | `config` | The config from `@cyclone-ui/tokens/tamagui` | The Tamagui config |
232
+ | `config` | The config from `@cyclone-ui/tokens/tamagui` | The Tamagui config; import custom configs inside a client wrapper |
181
233
  | `disableInjectCSS` | `false` | Skip runtime theme CSS when the app imports CSS generated by the Tamagui compiler |
182
234
  | `skipNextHead` | `true` | Render the theme script inline. Set `false` in the Pages Router to use `next/script` |
183
235
  | `mode` | `"light"` | The fallback mode shared by the server and initial client render |
@@ -197,7 +249,7 @@ export default withCycloneUI(nextConfig, {
197
249
  ? "./public/tamagui.generated.css"
198
250
  : null,
199
251
  disableExtraction: process.env.NODE_ENV === "development"
200
- });
252
+ })
201
253
  ```
202
254
 
203
255
  The defaults are `config: "@cyclone-ui/tokens/tamagui"`,
@@ -220,26 +272,26 @@ it with the Tamagui CLI (`@tamagui/cli`) before `next build`:
220
272
  ## Development
221
273
 
222
274
  ```bash
223
- pnpm nx run nextjs:build
224
- ```
225
-
226
- The production integration fixture exercises the source provider with Cache
227
- Components and Partial Prefetching. From the workspace root (Node 22.18+ for
228
- TypeScript imports in the fixture config), build and start it:
229
-
230
- ```bash
231
- devenv shell -- env NODE_ENV=production node packages/nextjs/node_modules/next/dist/bin/next build packages/nextjs/test/fixture
232
- devenv shell -- env NODE_ENV=production node packages/nextjs/node_modules/next/dist/bin/next start packages/nextjs/test/fixture -p 3197
275
+ devenv shell -- pnpm nx run nextjs:build
233
276
  ```
234
277
 
235
- In another terminal, run the browser checks with Playwright Chromium installed:
278
+ The production integration rig exercises the source provider with Cache
279
+ Components and Partial Prefetching. From the workspace root, run:
236
280
 
237
281
  ```bash
238
- devenv shell -- node packages/nextjs/test/theme.browser.mjs
282
+ devenv shell -- pnpm --filter @cyclone-ui/nextjs exec playwright test
239
283
  ```
240
284
 
241
- `CHROMIUM_PATH` selects an existing Chromium executable; `TEST_URL` overrides
242
- `http://localhost:3197`. The checks cover shell CSS before hydration, persisted
243
- preferences, forced themes, system changes, cookies, streamed content, and client
244
- navigation. They use a mount-safe diagnostic label because a shared shell cannot
245
- know the browser's stored preference.
285
+ The Playwright config builds and starts the fixture automatically, setting
286
+ `EXPOSE_TESTING_API=1` for both build and start so the raw Next.js config can
287
+ enable the test API. Use Node 22.18+ for the fixture config's TypeScript imports.
288
+ `CHROMIUM_PATH` selects an existing Chromium executable; otherwise Playwright
289
+ uses its installed browser. See [instant-nav.rig.md](./instant-nav.rig.md) for
290
+ the rig and its assertions.
291
+
292
+ The checks hold request content back to inspect the immediate shell on initial
293
+ load and client navigation, then verify the streamed content arrives. They also
294
+ run `test/theme.browser.mjs` against the production server to cover shell CSS
295
+ before hydration, persisted preferences, forced themes, system changes, cookies,
296
+ and delayed hydration. The theme checks use a mount-safe diagnostic label because
297
+ a shared shell cannot know the browser's stored preference.
package/dist/index.cjs CHANGED
@@ -1 +1 @@
1
- Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("node:module"),t=require("node:path");const n=(n,r,i)=>({...n,env:{TAMAGUI_TARGET:`web`,...n.env},turbopack:{...n.turbopack,resolveAlias:{"react-native":`react-native-web`,"react-native-svg":`@tamagui/react-native-svg`,...i&&{"@cyclone-ui/tokens/tamagui":`./${(0,t.relative)(process.cwd(),i)}`},...n.turbopack?.resolveAlias}},webpack:(a,o)=>{let{withTamagui:s}=(0,e.createRequire)((0,t.join)(o.dir,`package.json`))(`@tamagui/next-plugin`),c=s({config:i??`@cyclone-ui/tokens/tamagui`,components:[`@tamagui/core`],appDir:!0,...r})(n).webpack(a,o);return i&&(c.resolve.alias[`@cyclone-ui/tokens/tamagui$`]=i),c}});function r(e={},{tokens:t,...r}={}){return t?import(`@cyclone-ui/theme-builder`).then(async({buildTamaguiConfig:e})=>e({tokens:t})).then(t=>n(e,r,t)):n(e,r)}exports.withCycloneUI=r;
1
+ Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("node:module"),t=require("node:path");const n=(n,r,i)=>({...n,env:{TAMAGUI_TARGET:`web`,...n.env},turbopack:{...n.turbopack,resolveAlias:{"react-native":`react-native-web`,"react-native-svg":`@tamagui/react-native-svg`,...i&&{"@cyclone-ui/tokens/tamagui":`./${(0,t.relative)(process.cwd(),i)}`},...n.turbopack?.resolveAlias}},webpack:(a,o)=>{let{withTamagui:s}=(0,e.createRequire)((0,t.join)(o.dir,`package.json`))(`@tamagui/next-plugin`),c=s({config:i??`@cyclone-ui/tokens/tamagui`,components:[`@tamagui/core`],appDir:!0,...r})(n).webpack(a,o);return i&&(c.resolve.alias[`@cyclone-ui/tokens/tamagui$`]=i),c}}),r=(e,{tokens:t,...i})=>e instanceof Promise?e.then(e=>r(e,{tokens:t,...i})):t?import(`@cyclone-ui/theme-builder`).then(async({buildTamaguiConfig:e})=>e({tokens:t})).then(t=>n(e,i,t)):n(e,i);function i(e={},t={}){return typeof e==`function`?(n,i)=>r(e(n,i),t):r(e,t)}exports.withCycloneUI=i;
package/dist/index.d.cts CHANGED
@@ -22,6 +22,9 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
22
22
  */
23
23
  tokens?: BuildTamaguiConfigOptions["tokens"];
24
24
  };
25
+ type NextConfigFunction<Result extends NextConfig | Promise<NextConfig> = NextConfig | Promise<NextConfig>> = (phase: string, context: {
26
+ defaultConfig: NextConfig;
27
+ }) => Result;
25
28
  /**
26
29
  * Wrap a Next.js config with the setup Tamagui and Cyclone UI components need.
27
30
  *
@@ -34,6 +37,8 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
34
37
  *
35
38
  * With `tokens`, the Tamagui config is built from them first, so this returns
36
39
  * a promise, which Next.js accepts as the config export.
40
+ * Phase functions receive Next.js's original phase and default config and
41
+ * remain lazy; async functions and promised configs are resolved before setup.
37
42
  *
38
43
  * Turbopack builds don't run the Tamagui compiler. To optimize them, use the
39
44
  * Tamagui CLI: `tamagui build --target web ./src -- next build`.
@@ -54,7 +59,7 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
54
59
  * export default withCycloneUI({}, { tokens: "tokens/**\/*.json" });
55
60
  * ```
56
61
  *
57
- * @param nextConfig - The Next.js config to extend.
62
+ * @param nextConfig - The Next.js config, promise, or phase function to extend.
58
63
  * @param options - The design `tokens`, plus options forwarded to
59
64
  * `@tamagui/next-plugin` (Webpack only).
60
65
  * @returns The extended Next.js config.
@@ -63,5 +68,10 @@ declare function withCycloneUI(nextConfig?: NextConfig, options?: WithCycloneUIO
63
68
  tokens?: undefined;
64
69
  }): NextConfig;
65
70
  declare function withCycloneUI(nextConfig: NextConfig | undefined, options: WithCycloneUIOptions): NextConfig | Promise<NextConfig>;
71
+ declare function withCycloneUI(nextConfig: Promise<NextConfig>, options?: WithCycloneUIOptions): Promise<NextConfig>;
72
+ declare function withCycloneUI<Result extends NextConfig | Promise<NextConfig>>(nextConfig: NextConfigFunction<Result>, options?: WithCycloneUIOptions & {
73
+ tokens?: undefined;
74
+ }): NextConfigFunction<Result extends Promise<NextConfig> ? Promise<NextConfig> : NextConfig>;
75
+ declare function withCycloneUI(nextConfig: NextConfigFunction, options: WithCycloneUIOptions): NextConfigFunction;
66
76
  export { WithCycloneUIOptions, withCycloneUI };
67
77
  //# sourceMappingURL=index.d.cts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;KA4BY,uBAAuB,QAAQ;;;;;;;;;;;;;;;EAezC,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkFK,cACd,aAAa,YACb,UAAU;EAAyB;IAClC;iBACa,cACd,YAAY,wBACZ,SAAS,uBACR,aAAa,QAAQ"}
1
+ {"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;KA4BY,uBAAuB,QAAQ;;;;;;;;;;;;;;;EAezC,SAAS;;KAGN,mBACH,eAAe,aAAa,QAAQ,cAClC,aAAa,QAAQ,gBACpB,eAAe;EAAW,eAAe;MAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoG/C,cACd,aAAa,YACb,UAAU;EAAyB;IAClC;iBACa,cACd,YAAY,wBACZ,SAAS,uBACR,aAAa,QAAQ;iBACR,cACd,YAAY,QAAQ,aACpB,UAAU,uBACT,QAAQ;iBACK,cAAc,eAAe,aAAa,QAAQ,aAChE,YAAY,mBAAmB,SAC/B,UAAU;EAAyB;IAClC,mBACD,eAAe,QAAQ,cAAc,QAAQ,cAAc;iBAE7C,cACd,YAAY,oBACZ,SAAS,uBACR"}
package/dist/index.d.mts CHANGED
@@ -22,6 +22,9 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
22
22
  */
23
23
  tokens?: BuildTamaguiConfigOptions["tokens"];
24
24
  };
25
+ type NextConfigFunction<Result extends NextConfig | Promise<NextConfig> = NextConfig | Promise<NextConfig>> = (phase: string, context: {
26
+ defaultConfig: NextConfig;
27
+ }) => Result;
25
28
  /**
26
29
  * Wrap a Next.js config with the setup Tamagui and Cyclone UI components need.
27
30
  *
@@ -34,6 +37,8 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
34
37
  *
35
38
  * With `tokens`, the Tamagui config is built from them first, so this returns
36
39
  * a promise, which Next.js accepts as the config export.
40
+ * Phase functions receive Next.js's original phase and default config and
41
+ * remain lazy; async functions and promised configs are resolved before setup.
37
42
  *
38
43
  * Turbopack builds don't run the Tamagui compiler. To optimize them, use the
39
44
  * Tamagui CLI: `tamagui build --target web ./src -- next build`.
@@ -54,7 +59,7 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
54
59
  * export default withCycloneUI({}, { tokens: "tokens/**\/*.json" });
55
60
  * ```
56
61
  *
57
- * @param nextConfig - The Next.js config to extend.
62
+ * @param nextConfig - The Next.js config, promise, or phase function to extend.
58
63
  * @param options - The design `tokens`, plus options forwarded to
59
64
  * `@tamagui/next-plugin` (Webpack only).
60
65
  * @returns The extended Next.js config.
@@ -63,5 +68,10 @@ declare function withCycloneUI(nextConfig?: NextConfig, options?: WithCycloneUIO
63
68
  tokens?: undefined;
64
69
  }): NextConfig;
65
70
  declare function withCycloneUI(nextConfig: NextConfig | undefined, options: WithCycloneUIOptions): NextConfig | Promise<NextConfig>;
71
+ declare function withCycloneUI(nextConfig: Promise<NextConfig>, options?: WithCycloneUIOptions): Promise<NextConfig>;
72
+ declare function withCycloneUI<Result extends NextConfig | Promise<NextConfig>>(nextConfig: NextConfigFunction<Result>, options?: WithCycloneUIOptions & {
73
+ tokens?: undefined;
74
+ }): NextConfigFunction<Result extends Promise<NextConfig> ? Promise<NextConfig> : NextConfig>;
75
+ declare function withCycloneUI(nextConfig: NextConfigFunction, options: WithCycloneUIOptions): NextConfigFunction;
66
76
  export { WithCycloneUIOptions, withCycloneUI };
67
77
  //# sourceMappingURL=index.d.mts.map
package/dist/index.mjs CHANGED
@@ -1,2 +1,2 @@
1
- import{createRequire as e}from"node:module";import{join as t,relative as n}from"node:path";const r=(r,i,a)=>({...r,env:{TAMAGUI_TARGET:`web`,...r.env},turbopack:{...r.turbopack,resolveAlias:{"react-native":`react-native-web`,"react-native-svg":`@tamagui/react-native-svg`,...a&&{"@cyclone-ui/tokens/tamagui":`./${n(process.cwd(),a)}`},...r.turbopack?.resolveAlias}},webpack:(n,o)=>{let{withTamagui:s}=e(t(o.dir,`package.json`))(`@tamagui/next-plugin`),c=s({config:a??`@cyclone-ui/tokens/tamagui`,components:[`@tamagui/core`],appDir:!0,...i})(r).webpack(n,o);return a&&(c.resolve.alias[`@cyclone-ui/tokens/tamagui$`]=a),c}});function i(e={},{tokens:t,...n}={}){return t?import(`@cyclone-ui/theme-builder`).then(async({buildTamaguiConfig:e})=>e({tokens:t})).then(t=>r(e,n,t)):r(e,n)}export{i as withCycloneUI};
1
+ import{createRequire as e}from"node:module";import{join as t,relative as n}from"node:path";const r=(r,i,a)=>({...r,env:{TAMAGUI_TARGET:`web`,...r.env},turbopack:{...r.turbopack,resolveAlias:{"react-native":`react-native-web`,"react-native-svg":`@tamagui/react-native-svg`,...a&&{"@cyclone-ui/tokens/tamagui":`./${n(process.cwd(),a)}`},...r.turbopack?.resolveAlias}},webpack:(n,o)=>{let{withTamagui:s}=e(t(o.dir,`package.json`))(`@tamagui/next-plugin`),c=s({config:a??`@cyclone-ui/tokens/tamagui`,components:[`@tamagui/core`],appDir:!0,...i})(r).webpack(n,o);return a&&(c.resolve.alias[`@cyclone-ui/tokens/tamagui$`]=a),c}}),i=(e,{tokens:t,...n})=>e instanceof Promise?e.then(e=>i(e,{tokens:t,...n})):t?import(`@cyclone-ui/theme-builder`).then(async({buildTamaguiConfig:e})=>e({tokens:t})).then(t=>r(e,n,t)):r(e,n);function a(e={},t={}){return typeof e==`function`?(n,r)=>i(e(n,r),t):i(e,t)}export{a as withCycloneUI};
2
2
  //# sourceMappingURL=index.mjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.mjs","names":["extend","nextConfig","configPath","relative","createRequire","join","context","result","withTamagui","options","config","withCycloneUI","tokens","buildTamaguiConfig"],"sources":[],"mappings":""}
1
+ {"version":3,"file":"index.mjs","names":["extend","nextConfig","configPath","relative","createRequire","join","context","result","withTamagui","options","config","resolveConfig","tokens","buildTamaguiConfig","withCycloneUI","phase"],"sources":[],"mappings":""}
@@ -0,0 +1,94 @@
1
+ # Production navigation verification
2
+
3
+ This package is a framework integration and component library. The public fixture
4
+ under `test/fixture` provides representative routes; it has no authentication,
5
+ external services, mutable data, or application-specific cache policy.
6
+
7
+ ## Run
8
+
9
+ From the repository root:
10
+
11
+ ```sh
12
+ devenv shell -- pnpm --filter @cyclone-ui/nextjs exec playwright test
13
+ ```
14
+
15
+ Install the Playwright Chromium browser first, or set `CHROMIUM_PATH` to an
16
+ available executable. If the development environment's automatic package install
17
+ tries to reinstall already verified dependencies, disable only that hook:
18
+
19
+ ```sh
20
+ devenv -O languages.javascript.pnpm.install.enable:bool false shell -- pnpm --filter @cyclone-ui/nextjs exec playwright test
21
+ ```
22
+
23
+ The Playwright web server runs `test/production-server.mjs`, builds the local
24
+ fixture with Next.js 16.4.4, and serves the new artifact on port 3197. A listener
25
+ already using that port is an error; `reuseExistingServer` is disabled. Playwright
26
+ owns the server process group and cleanup. Builds and tests are awaited. There is
27
+ no remote artifact or separate deployment liveness check.
28
+
29
+ The runner enables `EXPOSE_TESTING_API=1` for **both build and start**. The fixture
30
+ config gates `experimental.exposeTestingApiInProductionBuild` on that variable.
31
+ This version reloads the config at startup, so omitting it from the server process
32
+ disables the document lock despite its presence in the build artifact. Never
33
+ enable this API for a user-facing production deployment.
34
+
35
+ ## Contracts
36
+
37
+ - Initial `/`: the heading, provider/theme script, styles and request-content
38
+ fallback are available; request content waits for the lock to release.
39
+ - `/` → “Second page” → `/second`: the destination shell and fallback are
40
+ visible while fresh request content waits. Scope assertions to the destination
41
+ because React may retain hidden content from the source route.
42
+ - Initial `/composition`: flat Page and Footer slots are rendered from a Server
43
+ Component; a neutral chart formatter executes in a cached Server Component.
44
+ Their visible shell renders before fresh content. Theme changes hydrate cleanly.
45
+ A separate normal-streaming check preserves typed input and focus when fresh
46
+ content arrives; the testing API's hard-load release refreshes the route, so
47
+ that artificial refresh is not used to measure client state preservation.
48
+ - Initial `/calendar-probe`: the surrounding shell prerenders with the calendar's
49
+ sized loading fallback in its static HTML. The current-date calendar resolves
50
+ and becomes interactive after hydration, without blocking the page shell.
51
+ - Initial `/charts-probe`: loading and loaded BarChart and ComposedChart variants
52
+ build and hydrate without render-time clock errors or random SVG mismatches.
53
+ Loaded variants exercise the normal bar-grow animation path.
54
+ - `/` → “Default prefetch” → `/search?q=default`: the shared search shell is
55
+ prefetched; URL-dependent results and fresh content wait for navigation.
56
+ - `/` → “Prefetch results” → `/search?q=prefetched`: `prefetch={true}` includes
57
+ the cached URL-dependent results; fresh content still waits. This is a fixture
58
+ policy, not a default imposed on Cyclone links or consuming applications.
59
+ - The existing theme regression script verifies persisted light/dark preferences,
60
+ forced themes, system changes, cookies, delayed hydration, navigation, and
61
+ first-paint CSS with hydration bundles blocked.
62
+
63
+ The fixtures use immutable inline data with the framework's default cache profile;
64
+ there are no writers to invalidate. Reusable production data must use a lifetime
65
+ and invalidation policy selected by its owning application.
66
+
67
+ ## Trust and iteration
68
+
69
+ Use `instant()` from `@next/playwright` on the same release as `next`. Every locked
70
+ test with deferred content asserts that it is absent during the lock and present
71
+ after release. A missing testing API therefore fails the test. Tests have no
72
+ retries, timing budgets or manual prefetch warming.
73
+
74
+ Confirm the same direct load or link reaches its completed destination without
75
+ the lock when authoring a new contract, then remove that temporary scaffold.
76
+ Rebuild after any source or config change. Compare the locked result with only
77
+ the relevant export/boundary/prefetch change removed, then reapply and run the
78
+ complete suite. Do not manufacture failures by disabling unrelated prefetching.
79
+
80
+ Test context: public; no authentication, feature flags, account roles, localization
81
+ or seeded database. Browser contexts are fresh per test and default to a light
82
+ system preference. The theme script explicitly seeds saved dark mode. Known drift:
83
+ none for these fixture contracts. These tests verify source integration, not a
84
+ published package installed by the Cyclone CLI or every consuming application's
85
+ routes. Inspect package builds separately for preserved client directives.
86
+
87
+ Verified differentials: Calendar's original render-time current-date read and
88
+ the original chart mount timestamps fail production prerendering. Restoring
89
+ their boundaries and effect-based timestamps allows the fixture to build. Removing
90
+ only `prefetch={true}` from “Prefetch results” leaves the shared search shell
91
+ available, but the cached URL results assertion fails under the lock. Restoring
92
+ that link policy restores the passing contract. Unlocked checks for both search
93
+ links and the composition route reached their completed UI before the temporary
94
+ baseline tests were removed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cyclone-ui/nextjs",
3
- "version": "0.0.15",
3
+ "version": "0.0.17",
4
4
  "type": "module",
5
5
  "description": "A Next.js config wrapper and root provider that set up Tamagui and Cyclone UI components in Next.js applications.",
6
6
  "repository": {
@@ -45,16 +45,16 @@
45
45
  "module": "./dist/index.mjs",
46
46
  "types": "./dist/index.d.cts",
47
47
  "dependencies": {
48
- "@cyclone-ui/theme-builder": "0.0.33",
49
- "@tamagui/next-theme": "3.0.13"
48
+ "@cyclone-ui/theme-builder": "0.0.35",
49
+ "@tamagui/next-theme": "3.2.0"
50
50
  },
51
51
  "peerDependencies": {
52
- "@cyclone-ui/state": "0.0.45",
53
- "@cyclone-ui/tokens": "0.3.32",
54
- "@tamagui/core": "3.0.13",
55
- "@tamagui/next-plugin": "3.0.13",
56
- "@tamagui/react-native-svg": "3.0.13",
57
- "next": "^16.4.4",
52
+ "@cyclone-ui/state": "0.0.47",
53
+ "@cyclone-ui/tokens": "0.3.34",
54
+ "@tamagui/core": "3.2.0",
55
+ "@tamagui/next-plugin": "3.2.0",
56
+ "@tamagui/react-native-svg": "3.2.0",
57
+ "next": "^16.4.5",
58
58
  "react": "^19.3.1",
59
59
  "react-native": "^0.87.1",
60
60
  "react-native-web": "0.19.12"
@@ -65,17 +65,21 @@
65
65
  "react-native": { "optional": true }
66
66
  },
67
67
  "devDependencies": {
68
- "@cyclone-ui/state": "0.0.45",
69
- "@cyclone-ui/tokens": "0.3.32",
70
- "@powerlines/plugin-tsdown": "^0.1.619",
71
- "@tamagui/core": "3.0.13",
72
- "@tamagui/next-plugin": "3.0.13",
68
+ "@cyclone-ui/state": "0.0.47",
69
+ "@cyclone-ui/tokens": "0.3.34",
70
+ "@next/playwright": "16.4.4",
71
+ "@playwright/test": "1.64.1",
72
+ "@powerlines/plugin-tsdown": "^0.1.620",
73
+ "@tamagui/core": "3.2.0",
74
+ "@tamagui/next-plugin": "3.2.0",
75
+ "@tamagui/react-native-svg": "3.2.0",
73
76
  "@types/react": "^19.3.0",
74
- "next": "^16.4.4",
75
- "powerlines": "^0.47.218",
77
+ "next": "^16.4.5",
78
+ "powerlines": "^0.47.219",
76
79
  "react": "^19.3.1",
80
+ "react-native": "^0.87.1",
77
81
  "react-native-web": "0.19.12"
78
82
  },
79
83
  "publishConfig": { "access": "public" },
80
- "gitHead": "2aea79c16eef482fc6e86a38189c8e404596803c"
84
+ "gitHead": "27e2859111e0933456c04b5bcbc6da37a928beeb"
81
85
  }