@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 +27 -0
- package/README.md +98 -46
- 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 +21 -17
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
107
|
-
|
|
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.
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
|
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
|
-
|
|
135
|
-
|
|
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
|
|
165
|
-
config export.
|
|
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
|
-
|
|
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 --
|
|
282
|
+
devenv shell -- pnpm --filter @cyclone-ui/nextjs exec playwright test
|
|
239
283
|
```
|
|
240
284
|
|
|
241
|
-
|
|
242
|
-
`
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
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}})
|
|
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.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.
|
|
49
|
-
"@tamagui/next-theme": "3.0
|
|
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.
|
|
53
|
-
"@cyclone-ui/tokens": "0.3.
|
|
54
|
-
"@tamagui/core": "3.0
|
|
55
|
-
"@tamagui/next-plugin": "3.0
|
|
56
|
-
"@tamagui/react-native-svg": "3.0
|
|
57
|
-
"next": "^16.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.
|
|
69
|
-
"@cyclone-ui/tokens": "0.3.
|
|
70
|
-
"@
|
|
71
|
-
"@
|
|
72
|
-
"@
|
|
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.
|
|
75
|
-
"powerlines": "^0.47.
|
|
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": "
|
|
84
|
+
"gitHead": "27e2859111e0933456c04b5bcbc6da37a928beeb"
|
|
81
85
|
}
|