@cyclone-ui/nextjs 0.0.15 → 0.0.16
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 +8 -0
- package/README.md +94 -45
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +11 -1
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.mts +11 -1
- package/dist/index.mjs +1 -1
- package/dist/index.mjs.map +1 -1
- package/instant-nav.rig.md +94 -0
- package/package.json +9 -7
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
# Changelog for Cyclone UI - Nextjs
|
|
4
4
|
|
|
5
|
+
## [0.0.15](https://github.com/storm-software/cyclone-ui/releases/tag/nextjs%400.0.15) (11/03/2026)
|
|
6
|
+
|
|
7
|
+
### Updated Dependencies
|
|
8
|
+
|
|
9
|
+
- Updated **state** to **v0.0.45**
|
|
10
|
+
- Updated **theme-builder** to **v0.0.33**
|
|
11
|
+
- Updated **tokens** to **v0.3.32**
|
|
12
|
+
|
|
5
13
|
## [0.0.14](https://github.com/storm-software/cyclone-ui/releases/tag/nextjs%400.0.14) (11/03/2026)
|
|
6
14
|
|
|
7
15
|
### Bug Fixes
|
package/README.md
CHANGED
|
@@ -38,19 +38,23 @@ Wrap the Next.js config:
|
|
|
38
38
|
|
|
39
39
|
```ts
|
|
40
40
|
// next.config.ts
|
|
41
|
-
import { withCycloneUI } from "@cyclone-ui/nextjs"
|
|
41
|
+
import { withCycloneUI } from "@cyclone-ui/nextjs"
|
|
42
42
|
|
|
43
43
|
export default withCycloneUI({
|
|
44
44
|
reactStrictMode: true
|
|
45
|
-
})
|
|
45
|
+
})
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
+
The wrapper also accepts a promised config or a sync/async Next.js config
|
|
49
|
+
function. Phase functions remain lazy and receive the original phase and context;
|
|
50
|
+
existing `cacheComponents` and `partialPrefetching` values are preserved.
|
|
51
|
+
|
|
48
52
|
Render the provider in the root layout. The provider sets a class on `<html>`
|
|
49
53
|
before React hydrates, so add `suppressHydrationWarning` there:
|
|
50
54
|
|
|
51
55
|
```tsx
|
|
52
56
|
// app/layout.tsx
|
|
53
|
-
import { CycloneUIProvider } from "@cyclone-ui/nextjs/provider"
|
|
57
|
+
import { CycloneUIProvider } from "@cyclone-ui/nextjs/provider"
|
|
54
58
|
|
|
55
59
|
export default function RootLayout({
|
|
56
60
|
children
|
|
@@ -63,19 +67,43 @@ export default function RootLayout({
|
|
|
63
67
|
<CycloneUIProvider>{children}</CycloneUIProvider>
|
|
64
68
|
</body>
|
|
65
69
|
</html>
|
|
66
|
-
)
|
|
70
|
+
)
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The layout remains a Server Component. The client provider accepts server-rendered
|
|
75
|
+
children without moving those child modules into the client bundle. Props that
|
|
76
|
+
cross this boundary must be serializable by React. The default config is already
|
|
77
|
+
imported inside the provider; if passing a custom Tamagui `config` or an ordinary
|
|
78
|
+
callback such as `onChangeTheme`, define them inside an application-owned client
|
|
79
|
+
wrapper:
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
// app/providers.tsx
|
|
83
|
+
"use client"
|
|
84
|
+
|
|
85
|
+
import { CycloneUIProvider } from "@cyclone-ui/nextjs/provider"
|
|
86
|
+
import type { PropsWithChildren } from "react"
|
|
87
|
+
import { config } from "@/tamagui.config" // Use your config's actual export.
|
|
88
|
+
|
|
89
|
+
export function AppProviders({ children }: PropsWithChildren) {
|
|
90
|
+
return <CycloneUIProvider config={config}>{children}</CycloneUIProvider>
|
|
67
91
|
}
|
|
68
92
|
```
|
|
69
93
|
|
|
94
|
+
Render `<AppProviders>{children}</AppProviders>` from the server layout. The
|
|
95
|
+
build-time `tokens` option below also replaces the provider's config import, so
|
|
96
|
+
it needs no `config` prop.
|
|
97
|
+
|
|
70
98
|
Read or change the theme with `useThemeSetting`:
|
|
71
99
|
|
|
72
100
|
```tsx
|
|
73
|
-
"use client"
|
|
101
|
+
"use client"
|
|
74
102
|
|
|
75
|
-
import { useThemeSetting } from "@cyclone-ui/nextjs/provider"
|
|
103
|
+
import { useThemeSetting } from "@cyclone-ui/nextjs/provider"
|
|
76
104
|
|
|
77
105
|
export function ThemeToggle() {
|
|
78
|
-
const theme = useThemeSetting()
|
|
106
|
+
const theme = useThemeSetting()
|
|
79
107
|
|
|
80
108
|
return <button onClick={theme.toggle}>Change theme</button>
|
|
81
109
|
}
|
|
@@ -91,21 +119,24 @@ System preference changes apply when the selected setting is `system`.
|
|
|
91
119
|
|
|
92
120
|
### Cache Components and static shells
|
|
93
121
|
|
|
94
|
-
|
|
122
|
+
Cache Components in Next.js 16 includes Partial Prerendering (PPR): a prerendered
|
|
123
|
+
shell with dynamic content streamed through Suspense. Partial Prefetching is a
|
|
124
|
+
separate navigation feature introduced in Next.js 16.3 and requires Cache
|
|
125
|
+
Components. Check your installed Next.js version before adding flags. For
|
|
126
|
+
Next.js 16.3+ when adopting both features:
|
|
95
127
|
|
|
96
128
|
```ts
|
|
97
|
-
import { withCycloneUI } from "@cyclone-ui/nextjs"
|
|
129
|
+
import { withCycloneUI } from "@cyclone-ui/nextjs"
|
|
98
130
|
|
|
99
131
|
export default withCycloneUI({
|
|
100
132
|
cacheComponents: true,
|
|
101
133
|
partialPrefetching: true
|
|
102
|
-
})
|
|
134
|
+
})
|
|
103
135
|
```
|
|
104
136
|
|
|
105
|
-
`withCycloneUI` preserves these options; it does not enable them globally
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
Shell; it does not make request-dependent content static.
|
|
137
|
+
`withCycloneUI` preserves these options; it does not enable them globally or
|
|
138
|
+
choose a caching policy. On Next.js 16.0–16.2, omit `partialPrefetching`. Do not
|
|
139
|
+
combine `cacheComponents` with the older `experimental.ppr` flag.
|
|
109
140
|
|
|
110
141
|
Keep the root layout synchronous and render `CycloneUIProvider` directly around
|
|
111
142
|
its children, as above. The provider does not read `cookies()` or `headers()`
|
|
@@ -117,22 +148,38 @@ Do not read a theme cookie in the root layout just to populate `mode`. `mode` is
|
|
|
117
148
|
an SSR/hydration fallback, not the user's persisted preference. `modeCookie` is
|
|
118
149
|
an optional client-written mirror of the resolved light/dark mode; it does not
|
|
119
150
|
require a server cookie read or preserve the distinction between system and an
|
|
120
|
-
explicit choice.
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
151
|
+
explicit choice. Put request reads such as `cookies()`, `headers()`, and
|
|
152
|
+
`searchParams` inside the component that needs them, under a local `<Suspense>`
|
|
153
|
+
boundary with a useful fallback. Do not put those reads inside `"use cache"` or
|
|
154
|
+
move the whole provider behind that boundary. Server Components, including
|
|
155
|
+
cached ones, can be passed as children through the client provider.
|
|
156
|
+
|
|
157
|
+
Static JSX needs no `"use cache"`. Cache reusable application data or server UI
|
|
158
|
+
according to its freshness and invalidation policy; keep uncached live work
|
|
159
|
+
behind local Suspense. Do not add the directive to client providers or client
|
|
160
|
+
primitives as a general optimization.
|
|
124
161
|
|
|
125
162
|
Use semantic theme tokens and relative sub-themes such as `base` in the shell.
|
|
126
163
|
Avoid choosing server markup or literal colors from a browser theme preference.
|
|
127
164
|
Theme-dependent text from `useThemeSetting().current`, `resolvedTheme`,
|
|
128
|
-
`useRootTheme`, or `useThemeMode` must wait until that component mounts. These
|
|
129
|
-
between the server and the first browser render. The constant-label toggle
|
|
165
|
+
`useRootTheme`, or `useThemeMode` must wait until that component mounts. These
|
|
166
|
+
values can differ between the server and the first browser render. The constant-label toggle
|
|
130
167
|
above needs no mount guard. If showing a current-mode label, guard only that
|
|
131
168
|
label/control, keeping the rest of the shell rendered. `suppressHydrationWarning`
|
|
132
169
|
on `<html>` does not suppress mismatches in descendants.
|
|
133
170
|
|
|
134
|
-
|
|
135
|
-
|
|
171
|
+
With Partial Prefetching enabled, default links prefetch a reusable route App
|
|
172
|
+
Shell rather than all of a destination's content. Use `prefetch={true}` on
|
|
173
|
+
selected application links to also resolve cached URL-specific content depending
|
|
174
|
+
on `params`, `searchParams`, or the full URL. It no longer includes uncached
|
|
175
|
+
dynamic content from the legacy full prefetch; that content streams after
|
|
176
|
+
navigation. Audit existing `prefetch={true}` links before enabling the flag, and
|
|
177
|
+
verify concrete URL navigations in production. Avoid imposing full prefetching
|
|
178
|
+
on every shared link primitive.
|
|
179
|
+
|
|
180
|
+
See [Next.js caching](https://nextjs.org/docs/app/getting-started/caching),
|
|
181
|
+
[adopting Partial Prefetching](https://nextjs.org/docs/app/guides/adopting-partial-prefetching),
|
|
182
|
+
and [optimizing prefetching](https://nextjs.org/docs/app/guides/optimizing-prefetching).
|
|
136
183
|
|
|
137
184
|
### Custom design tokens
|
|
138
185
|
|
|
@@ -142,7 +189,7 @@ globs relative to the working directory:
|
|
|
142
189
|
|
|
143
190
|
```ts
|
|
144
191
|
// next.config.ts
|
|
145
|
-
import { withCycloneUI } from "@cyclone-ui/nextjs"
|
|
192
|
+
import { withCycloneUI } from "@cyclone-ui/nextjs"
|
|
146
193
|
|
|
147
194
|
export default withCycloneUI(
|
|
148
195
|
{ reactStrictMode: true },
|
|
@@ -153,7 +200,7 @@ export default withCycloneUI(
|
|
|
153
200
|
"tokens/dark.tokens.json"
|
|
154
201
|
]
|
|
155
202
|
}
|
|
156
|
-
)
|
|
203
|
+
)
|
|
157
204
|
```
|
|
158
205
|
|
|
159
206
|
Files with a theme name (`light.tokens.json`, `dark.tokens.json`, …) become
|
|
@@ -161,8 +208,10 @@ the `light` and `dark` themes. The tokens go through the same preprocessor and
|
|
|
161
208
|
generator as `@cyclone-ui/tokens`, and a `razorwind.config.ts` in the project
|
|
162
209
|
still applies (for example its fonts).
|
|
163
210
|
|
|
164
|
-
With `tokens
|
|
165
|
-
config export.
|
|
211
|
+
With `tokens` and an object config, `withCycloneUI` returns a promise, which
|
|
212
|
+
Next.js accepts as the config export. For a phase function, token generation runs
|
|
213
|
+
when Next.js resolves that function. Compose object-only third-party wrappers
|
|
214
|
+
before the token build. The config is written to `.cyclone-ui/tamagui.config.ts`
|
|
166
215
|
(add `.cyclone-ui` to `.gitignore`) and replaces `@cyclone-ui/tokens/tamagui`
|
|
167
216
|
everywhere, so `CycloneUIProvider` and the Webpack compiler use it. With
|
|
168
217
|
pnpm, Webpack builds also need `@tamagui/web` and `motion` installed in the
|
|
@@ -177,7 +226,7 @@ project root.
|
|
|
177
226
|
|
|
178
227
|
| Prop | Default | Description |
|
|
179
228
|
| ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
180
|
-
| `config` | The config from `@cyclone-ui/tokens/tamagui` | The Tamagui config
|
|
229
|
+
| `config` | The config from `@cyclone-ui/tokens/tamagui` | The Tamagui config; import custom configs inside a client wrapper |
|
|
181
230
|
| `disableInjectCSS` | `false` | Skip runtime theme CSS when the app imports CSS generated by the Tamagui compiler |
|
|
182
231
|
| `skipNextHead` | `true` | Render the theme script inline. Set `false` in the Pages Router to use `next/script` |
|
|
183
232
|
| `mode` | `"light"` | The fallback mode shared by the server and initial client render |
|
|
@@ -197,7 +246,7 @@ export default withCycloneUI(nextConfig, {
|
|
|
197
246
|
? "./public/tamagui.generated.css"
|
|
198
247
|
: null,
|
|
199
248
|
disableExtraction: process.env.NODE_ENV === "development"
|
|
200
|
-
})
|
|
249
|
+
})
|
|
201
250
|
```
|
|
202
251
|
|
|
203
252
|
The defaults are `config: "@cyclone-ui/tokens/tamagui"`,
|
|
@@ -220,26 +269,26 @@ it with the Tamagui CLI (`@tamagui/cli`) before `next build`:
|
|
|
220
269
|
## Development
|
|
221
270
|
|
|
222
271
|
```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
|
|
272
|
+
devenv shell -- pnpm nx run nextjs:build
|
|
233
273
|
```
|
|
234
274
|
|
|
235
|
-
|
|
275
|
+
The production integration rig exercises the source provider with Cache
|
|
276
|
+
Components and Partial Prefetching. From the workspace root, run:
|
|
236
277
|
|
|
237
278
|
```bash
|
|
238
|
-
devenv shell --
|
|
279
|
+
devenv shell -- pnpm --filter @cyclone-ui/nextjs exec playwright test
|
|
239
280
|
```
|
|
240
281
|
|
|
241
|
-
|
|
242
|
-
`
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
282
|
+
The Playwright config builds and starts the fixture automatically, setting
|
|
283
|
+
`EXPOSE_TESTING_API=1` for both build and start so the raw Next.js config can
|
|
284
|
+
enable the test API. Use Node 22.18+ for the fixture config's TypeScript imports.
|
|
285
|
+
`CHROMIUM_PATH` selects an existing Chromium executable; otherwise Playwright
|
|
286
|
+
uses its installed browser. See [instant-nav.rig.md](./instant-nav.rig.md) for
|
|
287
|
+
the rig and its assertions.
|
|
288
|
+
|
|
289
|
+
The checks hold request content back to inspect the immediate shell on initial
|
|
290
|
+
load and client navigation, then verify the streamed content arrives. They also
|
|
291
|
+
run `test/theme.browser.mjs` against the production server to cover shell CSS
|
|
292
|
+
before hydration, persisted preferences, forced themes, system changes, cookies,
|
|
293
|
+
and delayed hydration. The theme checks use a mount-safe diagnostic label because
|
|
294
|
+
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}})
|
|
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
|
package/dist/index.d.cts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;KA4BY,uBAAuB,QAAQ;;;;;;;;;;;;;;;EAezC,SAAS
|
|
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}})
|
|
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
|
package/dist/index.mjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.mjs","names":["extend","nextConfig","configPath","relative","createRequire","join","context","result","withTamagui","options","config","
|
|
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.
|
|
3
|
+
"version": "0.0.16",
|
|
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,12 +45,12 @@
|
|
|
45
45
|
"module": "./dist/index.mjs",
|
|
46
46
|
"types": "./dist/index.d.cts",
|
|
47
47
|
"dependencies": {
|
|
48
|
-
"@cyclone-ui/theme-builder": "0.0.
|
|
48
|
+
"@cyclone-ui/theme-builder": "0.0.34",
|
|
49
49
|
"@tamagui/next-theme": "3.0.13"
|
|
50
50
|
},
|
|
51
51
|
"peerDependencies": {
|
|
52
|
-
"@cyclone-ui/state": "0.0.
|
|
53
|
-
"@cyclone-ui/tokens": "0.3.
|
|
52
|
+
"@cyclone-ui/state": "0.0.46",
|
|
53
|
+
"@cyclone-ui/tokens": "0.3.33",
|
|
54
54
|
"@tamagui/core": "3.0.13",
|
|
55
55
|
"@tamagui/next-plugin": "3.0.13",
|
|
56
56
|
"@tamagui/react-native-svg": "3.0.13",
|
|
@@ -65,8 +65,10 @@
|
|
|
65
65
|
"react-native": { "optional": true }
|
|
66
66
|
},
|
|
67
67
|
"devDependencies": {
|
|
68
|
-
"@cyclone-ui/state": "0.0.
|
|
69
|
-
"@cyclone-ui/tokens": "0.3.
|
|
68
|
+
"@cyclone-ui/state": "0.0.46",
|
|
69
|
+
"@cyclone-ui/tokens": "0.3.33",
|
|
70
|
+
"@next/playwright": "16.4.4",
|
|
71
|
+
"@playwright/test": "1.64.1",
|
|
70
72
|
"@powerlines/plugin-tsdown": "^0.1.619",
|
|
71
73
|
"@tamagui/core": "3.0.13",
|
|
72
74
|
"@tamagui/next-plugin": "3.0.13",
|
|
@@ -77,5 +79,5 @@
|
|
|
77
79
|
"react-native-web": "0.19.12"
|
|
78
80
|
},
|
|
79
81
|
"publishConfig": { "access": "public" },
|
|
80
|
-
"gitHead": "
|
|
82
|
+
"gitHead": "b8f9ad1a52c5ca88a43e0cf52b88d9751cb58303"
|
|
81
83
|
}
|