npm - @wular/pnext - Versions diffs - 0.0.4 → 0.0.7 - Mend

@wular/pnext 0.0.4 → 0.0.7

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.

Files changed (395) hide show

package/README.md +22 -16
package/bin/pnext +6 -1
package/config/lint/base.js +7 -7
package/config/ts/base.json +2 -4
package/config/ts/react.json +2 -6
package/package.json +23 -2
package/reference/compat.md +87 -22
package/reference/config.md +40 -93
package/reference/css.md +42 -33
package/reference/dev.md +26 -33
package/reference/env.md +18 -20
package/reference/getting-started.md +132 -0
package/reference/metadata.md +31 -46
package/reference/navigation.md +65 -105
package/reference/performance.md +21 -142
package/reference/rendering.md +78 -75
package/reference/routing.md +97 -107
package/reference/typegen.md +27 -29
package/src/api/cache.ts +36 -37
package/src/api/client-cache.ts +2 -2
package/src/api/client-navigation.ts +121 -114
package/src/api/dynamic.tsx +58 -55
package/src/api/link.tsx +52 -53
package/src/api/navigation.ts +59 -58
package/src/api/server.ts +152 -144
package/src/api/suspense.ts +4 -4
package/src/cli/adapters/vercel-warm.ts +126 -121
package/src/cli/adapters/vercel.ts +437 -443
package/src/cli/analyze.ts +333 -144
package/src/cli/{named-bin.ts → boot/named-bin.ts} +37 -37
package/src/cli/{boot-trace.ts → boot/trace.ts} +10 -10
package/src/cli/build.ts +976 -978
package/src/cli/create.ts +72 -64
package/src/cli/dev.ts +116 -116
package/src/cli/index.ts +94 -85
package/src/cli/migrate/package-json.ts +73 -71
package/src/cli/migrate/report.ts +32 -33
package/src/cli/migrate/{index.ts → run.ts} +48 -49
package/src/cli/migrate/scan.ts +46 -46
package/src/cli/migrate/spinner.ts +9 -9
package/src/cli/migrate/tsconfig.ts +35 -35
package/src/cli/{server-entry.ts → serve/entry.ts} +57 -57
package/src/cli/{request-pipeline.ts → serve/pipeline.ts} +386 -394
package/src/cli/{serve-ui.ts → serve/ui.ts} +47 -47
package/src/cli/start.ts +65 -66
package/src/{typegen.ts → cli/typegen.ts} +59 -59
package/src/client/build.ts +802 -768
package/src/client/chunk-fold.ts +245 -240
package/src/client/{paths.ts → chunk-name.ts} +6 -6
package/src/client/entry.ts +162 -147
package/src/client/prebuilt.ts +231 -223
package/src/client/profile.ts +29 -29
package/src/client/react-compiler.ts +20 -15
package/src/client/{compat-surface.ts → react-tier.ts} +64 -64
package/src/client/reference-stub.ts +51 -51
package/src/client/reference.ts +19 -19
package/src/{api → client}/router/events.ts +32 -17
package/src/{api → client}/router/history.ts +16 -16
package/src/{api → client}/router/hub.ts +52 -53
package/src/{api/router.ts → client/router/index.ts} +61 -60
package/src/{api → client}/router/policies.ts +24 -24
package/src/{api → client}/router/runtime.ts +2022 -1995
package/src/{api → client}/router/types.ts +98 -98
package/src/compat/actions/client-plugin.ts +42 -43
package/src/compat/actions/client-stub.ts +14 -14
package/src/compat/actions/{action-client.ts → client.ts} +194 -193
package/src/compat/actions/config.ts +63 -64
package/src/compat/actions/detect.ts +68 -68
package/src/compat/actions/discovery.ts +105 -105
package/src/compat/actions/{action-dispatch.ts → dispatch.ts} +277 -274
package/src/compat/actions/early-submit.ts +1 -1
package/src/compat/actions/endpoint.ts +198 -198
package/src/compat/actions/extensions.ts +811 -0
package/src/compat/actions/flight.ts +23 -23
package/src/compat/actions/form-state.ts +34 -34
package/src/compat/actions/hoist.ts +382 -236
package/src/compat/actions/ids.ts +7 -12
package/src/compat/actions/index.ts +8 -8
package/src/compat/actions/instances.ts +46 -46
package/src/compat/actions/origin.ts +47 -48
package/src/compat/actions/protocol.ts +22 -22
package/src/compat/actions/registry.ts +19 -19
package/src/compat/{misc/action-return.ts → actions/return.ts} +60 -57
package/src/compat/actions/rewrite.ts +125 -125
package/src/compat/actions/{action-router.ts → router.ts} +10 -10
package/src/compat/actions/serve.ts +132 -136
package/src/compat/actions/server-tag.ts +4 -4
package/src/compat/actions/{action-shared.ts → shared.ts} +34 -34
package/src/compat/actions/unrecognized-error.ts +4 -4
package/src/compat/{index.ts → aliases.ts} +112 -109
package/src/compat/bundler/bun-externals.ts +18 -18
package/src/compat/bundler/cjs-exports.ts +271 -223
package/src/compat/bundler/config.ts +116 -111
package/src/compat/bundler/externals.ts +12 -12
package/src/compat/bundler/import-meta-url.ts +19 -19
package/src/compat/bundler/modularize-imports.ts +36 -33
package/src/compat/bundler/new-url-asset.ts +22 -24
package/src/compat/bundler/optimize-package-imports.ts +111 -107
package/src/compat/bundler/polyfill.ts +28 -28
package/src/compat/bundler/react-compiler.ts +35 -29
package/src/compat/bundler/react-profiler.tsx +11 -11
package/src/compat/bundler/relay-transform.ts +48 -47
package/src/compat/bundler/require-context.ts +119 -113
package/src/compat/bundler/resolve-extensions.ts +19 -19
package/src/compat/bundler/source-cache.ts +25 -25
package/src/compat/bundler/static-imports.ts +7 -7
package/src/compat/bundler/symlink-imports.ts +46 -46
package/src/compat/bundler/tsconfig-paths.ts +13 -15
package/src/compat/bundler/wasm.ts +58 -60
package/src/compat/bundler/webpack-loaders.ts +254 -241
package/src/compat/bundler/worker.ts +101 -104
package/src/compat/cache/build-flags.ts +29 -29
package/src/compat/cache/build-prerender-errors.ts +40 -44
package/src/compat/cache/custom-handler.ts +60 -53
package/src/compat/cache/fetch-patch.ts +240 -240
package/src/compat/cache/handler.ts +27 -31
package/src/compat/cache/modern-handler.ts +148 -126
package/src/compat/cache/resume-data-cache.ts +47 -45
package/src/compat/cache/revalidate.ts +233 -232
package/src/compat/cache/runtime-error.ts +35 -35
package/src/compat/cache/use-cache-transform.ts +442 -417
package/src/compat/cache/use-cache.ts +650 -614
package/src/compat/cache-control.ts +140 -142
package/src/compat/client/base-path.ts +21 -20
package/src/compat/client/css-order.ts +18 -18
package/src/compat/client/errors/bare-boundary.ts +11 -11
package/src/compat/client/errors/control-flow.ts +23 -23
package/src/compat/client/errors/error-boundary.ts +61 -61
package/src/compat/client/errors/global-error.ts +101 -91
package/src/compat/client/errors/install.ts +71 -72
package/src/compat/client/errors/lazy.ts +23 -23
package/src/compat/client/errors/primitive-throw.ts +47 -45
package/src/compat/client/errors/soft-refresh.ts +4 -4
package/src/compat/client/link-status.ts +33 -33
package/src/compat/client/{nav-compat-runtime.ts → nav-runtime.ts} +20 -20
package/src/compat/client/{nav-compat.ts → nav.ts} +12 -13
package/src/compat/client/navigation-scroll.ts +63 -63
package/src/compat/client/optimistic-routing.ts +93 -88
package/src/compat/client/prefetch-cache.ts +23 -24
package/src/compat/client/route-announcer.ts +35 -35
package/src/compat/client/segment-cache-policy.ts +20 -20
package/src/compat/client/segment-cache.ts +309 -315
package/src/compat/client/segment-prefetch.ts +127 -132
package/src/compat/client/trailing-slash.ts +5 -4
package/src/compat/css/chunking.ts +113 -116
package/src/compat/css/inline-css.ts +21 -21
package/src/compat/css/lightningcss.ts +37 -38
package/src/compat/css/modules.ts +161 -175
package/src/compat/css/nonce.ts +7 -7
package/src/compat/css/sass-plugin.ts +18 -21
package/src/compat/css/sass.ts +150 -152
package/src/compat/css/styled-jsx-runtime.ts +27 -27
package/src/compat/css/styled-jsx.ts +21 -21
package/src/compat/edge-runtime.ts +27 -27
package/src/compat/{adapter → export}/build-complete.ts +72 -75
package/src/compat/export/client.ts +29 -31
package/src/compat/export/{index.ts → emit.ts} +111 -110
package/src/compat/export/standalone.ts +62 -54
package/src/compat/image-optimizer/cache.ts +51 -49
package/src/compat/image-optimizer/detect.ts +52 -52
package/src/compat/image-optimizer/{index.ts → optimize.ts} +189 -194
package/src/compat/image-optimizer/source.ts +77 -80
package/src/compat/lifecycle/after-scope.ts +26 -26
package/src/compat/lifecycle/after.ts +48 -45
package/src/compat/lifecycle/error-funnel.ts +98 -102
package/src/compat/lifecycle/error-serialize.ts +30 -26
package/src/compat/lifecycle/error-ui.ts +67 -32
package/src/compat/lifecycle/instrumentation-client.ts +36 -38
package/src/compat/lifecycle/instrumentation.ts +85 -85
package/src/compat/lifecycle/node-console.ts +11 -11
package/src/compat/lifecycle/testmode.ts +160 -132
package/src/compat/mdx/compile.ts +60 -57
package/src/compat/mdx/plugin.ts +11 -11
package/src/compat/mdx/{next-mdx-stub.ts → stub.ts} +5 -5
package/src/compat/{metadata-route-artifacts.ts → metadata-artifacts.ts} +195 -191
package/src/compat/metadata.ts +75 -81
package/src/compat/next/cache.ts +68 -69
package/src/compat/next/canonical-url.ts +9 -9
package/src/compat/next/client-cache.ts +19 -19
package/src/compat/next/client-navigation.ts +112 -116
package/src/compat/next/client-only.ts +1 -1
package/src/compat/next/client-script.tsx +99 -93
package/src/compat/next/client-server.ts +10 -10
package/src/compat/next/config-loader.ts +176 -173
package/src/compat/next/config.ts +7 -7
package/src/compat/next/constants.cjs +6 -6
package/src/compat/next/constants.ts +6 -6
package/src/compat/next/custom-server.ts +26 -24
package/src/compat/next/dist/client/components/app-router-headers.ts +21 -21
package/src/compat/next/dist/server/app-render/work-unit-async-storage.external.cjs +3 -4
package/src/compat/next/dist/server/web/spec-extension/revalidate.ts +1 -1
package/src/compat/next/dist/server/web/spec-extension/unstable-cache.ts +1 -1
package/src/compat/next/dist/server/web/spec-extension/unstable-no-store.ts +1 -1
package/src/compat/next/dynamic.tsx +21 -18
package/src/compat/next/error.tsx +52 -52
package/src/compat/next/font/cache.ts +74 -74
package/src/compat/next/font/google.ts +2 -2
package/src/compat/next/font/index.ts +1 -1
package/src/compat/next/font/local.ts +3 -3
package/src/compat/next/font/runtime-client.ts +17 -15
package/src/compat/next/font/runtime.ts +443 -408
package/src/compat/next/font/shared.ts +120 -108
package/src/compat/next/form.tsx +63 -63
package/src/compat/next/head.tsx +2 -2
package/src/compat/next/headers.ts +103 -95
package/src/compat/next/image/client.tsx +220 -0
package/src/compat/next/image/config.ts +56 -58
package/src/compat/next/image/optimizer.ts +40 -36
package/src/compat/next/image/patterns.ts +37 -40
package/src/compat/next/{image-props.ts → image/props.ts} +208 -202
package/src/compat/next/image/shared.ts +65 -57
package/src/compat/next/image/static-metadata.ts +98 -107
package/src/compat/next/image/validate.ts +79 -88
package/src/compat/next/image.tsx +19 -23
package/src/compat/next/index.ts +1 -1
package/src/compat/next/legacy-image.tsx +59 -60
package/src/compat/next/{link-validation-transform.ts → link-transform.ts} +95 -96
package/src/compat/next/link.tsx +158 -158
package/src/compat/next/navigation.cjs +12 -3
package/src/compat/next/navigation.ts +48 -50
package/src/compat/next/offline.ts +27 -27
package/src/compat/next/og.ts +121 -124
package/src/compat/next/preferred-region.ts +13 -14
package/src/compat/next/redirects.ts +58 -56
package/src/compat/next/resource-hints.ts +73 -76
package/src/compat/next/rewrites.ts +130 -133
package/src/compat/next/root-params.ts +45 -45
package/src/compat/next/{optimistic-route-state.ts → route-state.ts} +52 -52
package/src/compat/next/router.cjs +4 -2
package/src/compat/next/router.ts +58 -61
package/src/compat/next/script.tsx +108 -108
package/src/compat/next/server-only.ts +1 -1
package/src/compat/next/server.ts +19 -19
package/src/compat/next/svgr.ts +18 -17
package/src/compat/next/telemetry.ts +24 -24
package/src/compat/next/{image-usage.ts → usage.ts} +70 -39
package/src/compat/next/user-agent.ts +53 -49
package/src/compat/next/web-vitals.ts +22 -24
package/src/compat/otel/api.ts +41 -41
package/src/compat/otel/client-trace-metadata.ts +25 -27
package/src/compat/otel/fetch-span.ts +29 -29
package/src/compat/otel/tracer.ts +331 -331
package/src/compat/pages/api.ts +456 -0
package/src/compat/pages/client-plugin.ts +36 -36
package/src/compat/pages/router-state.ts +34 -34
package/src/compat/pages/{index.ts → router.ts} +130 -135
package/src/compat/ppr/io.ts +12 -12
package/src/compat/ppr/missing-root-params.ts +34 -38
package/src/compat/ppr/root-params-scan.ts +66 -66
package/src/compat/ppr/root-params-transform.ts +24 -26
package/src/compat/ppr/root-params.ts +30 -30
package/src/compat/ppr/segment-config-incompat.ts +6 -7
package/src/compat/protocol.ts +71 -70
package/src/compat/react/action-state.ts +47 -48
package/src/compat/react/client-lite.ts +15 -15
package/src/compat/react/client.ts +4 -4
package/src/compat/react/compiler-runtime.ts +11 -11
package/src/compat/react/dom-client.ts +44 -44
package/src/compat/react/dom-react-server.ts +10 -16
package/src/compat/react/dom-server.ts +10 -10
package/src/compat/react/dom.ts +52 -52
package/src/compat/react/hooks-extra.ts +34 -35
package/src/compat/react/parity.ts +64 -61
package/src/compat/react/preact.ts +81 -82
package/src/compat/react/react-server.ts +28 -28
package/src/compat/react/router-shim.ts +1 -1
package/src/compat/react/server-component-use.ts +8 -8
package/src/compat/react/server-inserted-html.ts +30 -31
package/src/compat/react/server.ts +53 -55
package/src/compat/react/use.ts +32 -32
package/src/compat/react/view-transition.ts +20 -20
package/src/compat/register/actions.ts +35 -824
package/src/compat/register/boot.ts +41 -41
package/src/compat/register/build-tier.ts +5 -5
package/src/compat/register/build.ts +74 -70
package/src/compat/register/bundler.ts +161 -156
package/src/compat/register/cache.ts +20 -20
package/src/compat/register/client-errors.ts +3 -3
package/src/compat/register/config.ts +6 -6
package/src/compat/register/css-extras.ts +30 -34
package/src/compat/register/edge-runtime.ts +3 -3
package/src/compat/register/errors.ts +10 -12
package/src/compat/register/export.ts +16 -16
package/src/compat/register/font.ts +11 -11
package/src/compat/register/hooks.ts +2 -2
package/src/compat/register/image.ts +40 -40
package/src/compat/register/index.ts +59 -62
package/src/compat/register/instrumentation-client.ts +10 -10
package/src/compat/register/lifecycle.ts +25 -28
package/src/compat/register/mdx.ts +10 -10
package/src/compat/register/middleware.ts +226 -16
package/src/compat/register/otel.ts +80 -88
package/src/compat/register/pages-api.ts +10 -463
package/src/compat/register/ppr.ts +16 -16
package/src/compat/register/protocol.ts +17 -18
package/src/compat/register/proxy.ts +49 -51
package/src/compat/register/render.ts +79 -76
package/src/compat/register/routing.ts +162 -159
package/src/compat/register/segment.ts +24 -1897
package/src/compat/register/static-image.ts +3 -3
package/src/compat/register/{misc.ts → taint.ts} +9 -9
package/src/compat/register/typed-routes.ts +14 -14
package/src/compat/register/{usecache.ts → use-cache.ts} +39 -39
package/src/compat/register/validation.ts +18 -18
package/src/compat/segment/loading-boundary.ts +43 -45
package/src/compat/segment/page-slot.ts +69 -69
package/src/compat/segment/serve.ts +1884 -0
package/src/compat/segment/tree.ts +113 -112
package/src/compat/segment/vary-key.ts +38 -38
package/src/compat/segment/vary-params.ts +138 -142
package/src/compat/static-params.ts +14 -12
package/src/compat/tsconfig-defaults.ts +87 -91
package/src/compat/typecheck/{index.ts → check.ts} +234 -212
package/src/compat/typecheck/worker.ts +15 -12
package/src/compat/typed-routes/{index.ts → generate.ts} +36 -36
package/src/compat/typed-routes/manifest.ts +174 -170
package/src/compat/typed-routes/typegen.ts +127 -110
package/src/compat/validation/errors.ts +16 -19
package/src/compat/validation/prerender-diagnostics.ts +521 -504
package/src/compat/validation/{index.ts → validate.ts} +647 -648
package/src/compat-bootstrap.ts +16 -16
package/src/config.ts +86 -69
package/src/css/build.ts +230 -227
package/src/css/postcss.ts +79 -80
package/src/css/worker.ts +14 -15
package/src/dev/client-actions.ts +10 -10
package/src/dev/client-chunk-store.ts +27 -27
package/src/dev/{client-key-cache.ts → restart/client-key.ts} +76 -76
package/src/dev/{restart-cache.ts → restart/enabled.ts} +1 -1
package/src/dev/{global-css-cache.ts → restart/global-css.ts} +91 -83
package/src/dev/{node-module-bundle-cache.ts → restart/node-modules.ts} +24 -24
package/src/dev/{route-bundle-key-cache.ts → restart/route-bundle-key.ts} +53 -53
package/src/dev/{route-facts-cache.ts → restart/route-facts.ts} +82 -82
package/src/dev/server.ts +804 -820
package/src/env.ts +46 -43
package/src/extensions.ts +491 -478
package/src/index.ts +8 -8
package/src/internal.ts +20 -23
package/src/{islands → render}/boundary-error.ts +3 -3
package/src/render/hooks.ts +71 -71
package/src/render/island-context.ts +14 -14
package/src/render/metadata.ts +310 -310
package/src/{ppr-postpone.ts → render/postpone.ts} +5 -5
package/src/{ppr.ts → render/ppr.ts} +244 -245
package/src/render/renderer.ts +2087 -2082
package/src/render/resource-hints.ts +16 -17
package/src/render/slots.tsx +224 -235
package/src/{islands → render}/static-children.ts +9 -12
package/src/{islands → render}/static-slots.ts +37 -37
package/src/{cache/context.ts → request/cache.ts} +20 -20
package/src/request/context.ts +107 -107
package/src/{dynamic/source.ts → resolve/dynamic.ts} +139 -139
package/src/resolve/engine.ts +90 -77
package/src/resolve/imports.ts +475 -463
package/src/resolve/scan-facts.ts +318 -296
package/src/resolve/source-text.ts +37 -37
package/src/{dynamic → resolve}/tree-shake.ts +132 -128
package/src/routing/forwarded.ts +19 -19
package/src/routing/handler.ts +84 -91
package/src/routing/href.ts +87 -70
package/src/routing/{metadata.ts → metadata-files.ts} +403 -401
package/src/{proxy.ts → routing/proxy.ts} +306 -312
package/src/routing/{request-runtime.ts → request-environment.ts} +10 -10
package/src/routing/routes.ts +827 -815
package/src/routing/slots.ts +164 -160
package/src/runtime/loader.ts +954 -0
package/src/{dev → runtime}/module-cache.ts +309 -287
package/src/{dev → runtime}/module-generations.ts +9 -9
package/src/{dev → runtime}/module-transform.ts +81 -72
package/src/{dev/imports.ts → runtime/modules.ts} +934 -847
package/src/runtime/{server.ts → vendor-build.ts} +848 -1696
package/src/runtime/vendor.ts +428 -406
package/src/styles.d.ts +9 -0
package/src/types.ts +324 -335
package/src/utils/ansi.ts +5 -5
package/src/utils/{source.ts → code.ts} +15 -12
package/src/utils/content-type.ts +3 -3
package/src/utils/decode.ts +2 -2
package/src/utils/dev-profile.ts +13 -13
package/src/utils/error-log.ts +6 -6
package/src/utils/esbuild.ts +18 -18
package/src/utils/fs-cache.ts +13 -13
package/src/utils/fs.ts +57 -49
package/src/utils/html.ts +20 -24
package/src/utils/native-require.ts +8 -8
package/src/utils/serialize.ts +139 -146
package/src/utils/verbose.ts +18 -18
package/reference/overview.md +0 -35
package/src/cli/analyze-print.ts +0 -181
package/src/compat/middleware/manifest.ts +0 -210
package/src/compat/next/image-client.tsx +0 -215
package/src/compat/next/link-usage.ts +0 -29
package/src/css/index.ts +0 -2
package/src/render/index.ts +0 -1
package/src/style-modules.d.ts +0 -9

package/reference/css.md CHANGED Viewed

@@ -1,58 +1,67 @@
 # CSS
+Global styles, per-route styles, CSS Modules, and the compat-only preprocessors.
 ## Global CSS
-Import global styles from the root layout. pnext compiles global CSS once and links it from every page as `/assets/global.css`.
+Imported from the root layout. pnext compiles it once and links it from every page as `/assets/global.css`.
+```tsx
+// app/layout.tsx
+import './globals.css'
+```
-Global CSS can use local workspace package imports, font files, image assets, and the app's PostCSS/Tailwind setup.
+Global CSS can import local workspace packages, font files, image assets, and the app's PostCSS or Tailwind setup.
-## PostCSS
+## Route and component CSS
-When the app root has a `postcss.config.{cjs,js,mjs}`, pnext runs its plugins on every emitted stylesheet, in a worker thread. Tailwind v4 (`@tailwindcss/postcss`) stays warm there, so dev rebuilds are incremental; config-file edits need a dev-server restart.
+Any page, layout, or component can import a stylesheet.
 ```tsx
-import type { ComponentChildren } from 'preact';
-import './globals.css';
-export default function Layout({ children }: { children: ComponentChildren }) {
-  return (
-    <html>
-      <body>{children}</body>
-    </html>
-  );
-}
+import './page.css'
 ```
-## Route CSS
+pnext emits CSS only for routes that import it. A route stylesheet is named from the route id, as `/assets/<route-id>.css`. When a compat build splits one into chunks, each name gains an index suffix.
-Import plain CSS from pages, layouts, or components:
+## CSS Modules
+A `.module.css` file gives scoped class names that match the server-rendered HTML.
 ```tsx
-import './page.css';
+import styles from './page.module.css'
 export default function Page() {
-  return <h1 className="title">Hello</h1>;
+  return <h1 className={styles.title}>Hello</h1>
 }
 ```
-pnext emits route CSS only for routes that import CSS. A route with CSS imports gets a linked `/assets/<route>.css` chunk.
+Under `compat.next`, a `:global(...)` wrapper leaves the enclosed selector unscoped.
-## CSS Modules
+## Tailwind and PostCSS
-Use `.module.css` for scoped classes:
+A `postcss.config.{cjs,js,mjs}` file at the app root makes pnext run its plugins on every emitted stylesheet. Tailwind v4 stays warm in development. Editing the config file requires a dev-server restart.
-```css
-.title {
-  color: rebeccapurple;
-}
-```
+## Sass
-```tsx
-import styles from './page.module.css';
+Requires `compat.next` and the optional `sass` dependency. `.scss`, `.sass`, `.module.scss`, and `.module.sass` imports compile, and `sassOptions.includePaths` from `next.config.js` is honored. If `sass` is unavailable, Sass imports produce no CSS rather than breaking a non-Sass app.
-export default function Page() {
-  return <h1 className={styles.title}>Hello</h1>;
-}
-```
+## styled-jsx
+Requires `compat.next`. Style blocks and `styled-jsx/css` are transformed to pnext's own runtime, which collects server styles and mirrors client styles into the document head. Apps do not need to install `styled-jsx`.
+## Lightning CSS
+Requires `compat.next` and the app's own `lightningcss` package.
+- `experimental.useLightningcss` transforms CSS with it.
+- `experimental.lightningCssFeatures` controls which features are included or excluded.
+CSS passes through untransformed when the package is absent or the transform fails.
+## Nonces and inline CSS
+pnext reads a CSP nonce from the request `Content-Security-Policy` header and applies it to generated styles. With `experimental.inlineCss`, production documents inline route and global CSS in nonce-bearing style tags, while development keeps stylesheet links.
+## Chunking and order
-CSS module class names are scoped in the emitted CSS and match the server-rendered HTML.
+`experimental.cssChunking` groups compatible route stylesheets into fewer files while preserving each route's stylesheet order. It splits them instead when sharing a chunk would change cascade order or make a chunk too large.

package/reference/dev.md CHANGED Viewed

@@ -1,25 +1,23 @@
-# Dev Server
+# Development
-`pnext dev` starts a Bun HTTP server for local development.
+The `pnext` CLI carries the whole flow: `dev` while you build, `analyze` to inspect what ships, `build` and `start` for production.
-## CLI
-```txt
+```sh
 pnext dev [directory] [--port 3000] [--hostname 127.0.0.1]
 pnext build [directory] [--adapter vercel] [--verbose]
 pnext start [directory] [--port 3000] [--hostname 127.0.0.1]
 pnext analyze [route] [directory] [--brotli] [--files] [--json]
 pnext typegen [directory]
+pnext create <directory> [--no-install]
+pnext migrate [directory] [--dry-run]
 ```
-`analyze` takes a route (`/users/[id]` or a concrete path like `/users/ada`) to report on that route only.
-Add `@wular/pnext` as a package dependency and put `pnext` in package scripts:
+`create` scaffolds a new app with everything set up. `migrate` converts a Next.js project in place: it rewrites `package.json` and `tsconfig.json` and creates a `pnext.config.ts` with `compat.next` enabled, without editing app source; `--dry-run` previews. To set a project up by hand, add the package and scripts:
 ```json
 {
   "devDependencies": {
-    "@wular/pnext": "^0.0.0"
+    "@wular/pnext": "latest"
   },
   "scripts": {
     "dev": "pnext dev",
@@ -30,40 +28,35 @@ Add `@wular/pnext` as a package dependency and put `pnext` in package scripts:
 }
 ```
-The package exposes a `pnext` binary. Package managers make it available inside script `PATH`.
+## Dev server
-## Processes
+`pnext dev` starts a Bun HTTP server that scans the route tree, renders matching pages on request, and serves static assets from `public/`. Client route entries are built on demand and cached in `.pnext/cache`. Browser pages reload on route-tree changes over a server-sent events stream at `/__pnext/events`; the other `/__pnext/*` endpoints are implementation details, not application routes.
-pnext processes are labelled in Activity Monitor and `ps`: `pnext dev` shows
-up as a single `pnext-dev` server process, `pnext build` as `pnext-build`, and
-esbuild's service process as `pnext-esbuild`. Tailwind and PostCSS run in a
-worker thread inside the server process, not as child processes.
+The dev server does not typecheck in the request path; run your package's lint and typecheck scripts separately. `pnext typegen` regenerates the route types on demand; see [Type Safety](./typegen.md).
-The dev server re-execs itself — same pid — when its memory passes
-`PNEXT_DEV_MAX_RSS_MB` (default 2048). The esbuild service is stopped and
-respawned past `PNEXT_DEV_MAX_ESBUILD_RSS_MB` (default 1024).
+In Activity Monitor and `ps`, the dev server runs as `pnext-dev`, builds as `pnext-build`, and the bundler service as `pnext-esbuild`. The dev server re-execs itself when its memory passes `PNEXT_DEV_MAX_RSS_MB` (default 2048), and restarts the bundler past `PNEXT_DEV_MAX_ESBUILD_RSS_MB` (default 1024).
-## Responsibilities
+## Analyze
-- Scan the route tree.
-- Render matching pages on request.
-- Serve static assets from `public/`.
-- Build client route entries on demand with esbuild.
-- Cache generated client entries in `.pnext/cache`.
-- Notify the browser of route-tree changes through `/__pnext/events`.
+`pnext analyze` reports the client JavaScript behind each route. Optionally pass a route, either a template like `/users/[id]` or a concrete path, to report on that route only. `--files` breaks the report into files, `--brotli` measures with brotli instead of gzip, and `--json` emits machine-readable output.
-## Cache
+## Build and run
-Client entry cache keys include the route id and source content hash. Cached entries are stored below `.pnext/cache/client`.
+`pnext build` makes the production build and `pnext start` serves it. Routes render on the server per request; ones that never read the request are prerendered to static HTML at build time. A `compat.next` build typechecks off-thread alongside bundling.
-## Reload Events
+Debug flags: `--experimental-build-mode compile|generate` splits the build into its two phases, `--debug-build-paths <paths>` narrows diagnostics to matching paths, and `--debug-prerender` prints prerender diagnostics.
-The dev server exposes a server-sent events stream at `/__pnext/events`. Browser pages reload when app files change.
+## Deploy
-## Typechecking
+pnext deploys anywhere Bun runs: a VPS, a container, or any host you control. Run `pnext build` on the machine or in CI, then `pnext start` serves the app on your port.
-The dev server does not typecheck in the request path. Run package lint or typecheck commands separately. `pnext build` under `compat.next` typechecks off-thread, in parallel with bundling, and reports it on its own line.
+Vercel has a dedicated adapter: `pnext build --adapter vercel` writes Build Output to `.vercel/output`. Static pages and static route-handler responses are emitted as files; everything dynamic runs in a single `_pnext` function on Vercel's Bun runtime.
-## Server Adapter
+## Environment variables
-Use `pnext build --adapter vercel` to write Vercel Build Output at `.vercel/output`. Static pages and static `GET` route-handler outputs are emitted as files. Everything dynamic — pages, route handlers, and `proxy.ts` — is served by a single `_pnext` function on Vercel's Bun runtime; the proxy's `config.matcher` patterns become routes into it.
+- `PNEXT_COMPAT=next`: Next compatibility without a config file. See [Compatibility](./compat.md).
+- `PNEXT_TYPECHECK=classic`: in-process TypeScript checker instead of the native one.
+- `PNEXT_CLIENT_METAFILE=1`: write the client esbuild metafile to the output directory.
+- `PNEXT_CLIENT_PROFILE=1`: print client-build phase timings.
+- `PNEXT_DEV_PROFILE=1`: print dev request and build timings.
+- `PNEXT_BOOT_TRACE=1`: print boot-phase timings and memory readings.

package/reference/env.md CHANGED Viewed

@@ -1,29 +1,29 @@
 # Environment Variables
-pnext loads `.env*` files from the project root, not from `src/`.
+pnext loads `.env*` files from the project root, never from `src/`. Variables are server-only unless their name marks them for the browser. Server Components, layouts, route handlers, and the proxy read them from `process.env`.
-Variables already set on `process.env` win. Missing variables are loaded in this order:
+## What reaches the browser
-1. `.env.$NODE_ENV.local`
-2. `.env.local` except when `NODE_ENV` is `test`
-3. `.env.$NODE_ENV`
-4. `.env`
-If `NODE_ENV` is not set, `pnext dev` uses `development`; other commands use `production`.
-## Browser Variables
-Browser bundles inline only:
+Browser bundles inline only these:
 - `process.env.NODE_ENV`
 - `process.env.NEXT_PUBLIC_*`
 - `process.env.PNEXT_PUBLIC_*`
-Other variables stay server-only. Server Components, layouts, route handlers, and proxy can read them through `process.env`.
+## Load order
+Variables already set on `process.env` win. Missing ones are loaded from:
-## Variable References
+1. `.env.$NODE_ENV.local`
+2. `.env.local`, except when `NODE_ENV` is `test`
+3. `.env.$NODE_ENV`
+4. `.env`
+If `NODE_ENV` is not set, the dev server uses `development` and every other command uses `production`.
-Values can reference earlier environment variables:
+## Variable references
+A value can reference an earlier variable, with or without braces, and with an optional fallback.
 ```env
 API_HOST=api.example.com
@@ -31,10 +31,8 @@ NEXT_PUBLIC_API_URL=https://$API_HOST
 PORT=${APP_PORT:-3000}
 ```
-`${VAR}` and `${VAR:-fallback}` both work. A variable already on `process.env` wins over the file's own value.
+Escape the dollar sign when it should be literal, as `\$10`.
-Escape `$` when it should be literal:
+## PNEXT_COMPAT
-```env
-PRICE=\$10
-```
+Setting it to `next` gives an app with no `pnext.config.ts` the `next/*` module surface and `next.config.js` support. When a config file is present, it forces Next compatibility on and leaves every other compat flag as written. It is read after the `.env*` files load, so a `.env` file can set it. See [Compatibility](./compat.md).

package/reference/getting-started.md ADDED Viewed

@@ -0,0 +1,132 @@
+# Getting Started
+pnext is a Preact framework for file-routed apps. It renders on the server by default and ships client JavaScript only where a component opts in.
+> pnext requires [Bun](https://bun.sh/get) - make sure it is installed first.
+<!-- tabs:start -->
+## New app
+```sh
+bunx @wular/pnext create my-app
+cd my-app
+bun dev
+```
+The app is running at `http://localhost:3000`. Edit `app/page.tsx`; the browser reloads on save.
+`app/page.tsx` is a Server Component: it can be async, load data on the server, and ships no client JavaScript. The counter it renders, `app/counter.tsx`, starts with `'use client'`, so it alone hydrates in the browser. That's the model: files name routes, the server renders by default, components opt in to the client.
+## Coming from Next.js
+Run in your Next project:
+```sh
+bunx @wular/pnext migrate
+```
+It converts the project to pnext with `compat.next` enabled, without editing app source. `--dry-run` previews.
+With `compat.next`, the `next/*` modules, `next.config.js`, server actions, metadata, and the rest of the App Router behavior work as they do in Next, validated against Next's own test suite. [Compatibility](./compat.md) covers the full surface and where it stops short.
+<!-- tabs:end -->
+## Build and deploy
+```sh
+pnext build
+pnext start
+```
+`pnext build` makes the production build and `pnext start` serves it. Routes render on the server per request; ones that never read the request are prerendered to static HTML at build time.
+That deploys anywhere Bun runs. For Vercel, build with `pnext build --adapter vercel` and it writes ready-to-deploy Build Output.
+## A quick tour
+### Your first page
+Routes live in `app/`. A `page.tsx` is a Server Component by default. It runs only on the server, so it can be async and talk to your database, filesystem, or internal services directly. None of that code reaches the browser:
+```tsx
+// app/posts/[id]/page.tsx
+import type { PageProps } from '#gen/app/posts/[id]/page'
+export default async function Page({ params }: PageProps) {
+  const { id } = await params
+  const post = await db.post.findUnique({ where: { id } })
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <p>{post.body}</p>
+    </article>
+  )
+}
+```
+This page ships **0 KB** of JavaScript. Layouts work the same way: the root `layout.tsx` owns `<html>` and `<body>` and can export `metadata`.
+### Adding interactivity
+Mark a component with `"use client"` where you need state, effects, or event handlers. Server Components render it into the page, and only that island hydrates in the browser:
+```tsx
+// app/counter.tsx
+'use client'
+import { useState } from 'preact/hooks'
+export function Counter({ initial }: { initial: number }) {
+  const [count, setCount] = useState(initial)
+  return (
+    <button onClick={() => setCount(count + 1)}>Count {count}</button>
+  )
+}
+```
+Client Components hydrate on Preact for ~7.5 KB of framework, or ~12.5 KB with [`compat.react`](./compat.md) if you want to run React components and libraries unchanged. Offscreen islands can stay out of the initial bundle entirely with `dynamic({ load: 'visible' })`.
+### Streaming
+Wrap slow server work in `<Suspense>`. The shell streams immediately and the content follows when it's ready:
+```tsx
+import { Suspense } from '@wular/pnext'
+export default function Page() {
+  return (
+    <Suspense fallback={<p>Loading comments…</p>}>
+      <Comments />
+    </Suspense>
+  )
+}
+```
+### APIs and everything else
+A `route.ts` file is an HTTP handler:
+```ts
+// app/api/users/route.ts
+export async function GET(request: NextRequest) {
+  return Response.json(await listUsers())
+}
+```
+- `proxy.ts` runs before route matching.
+- `loading.tsx`, `error.tsx`, and `not-found.tsx` define per-segment fallbacks.
+- `pnext build` makes the production build and `pnext start` serves it. Routes that never read the request are prerendered to static HTML.
+## References
+- [Routing](./routing.md)
+- [Navigation](./navigation.md)
+- [Rendering](./rendering.md)
+- [Metadata](./metadata.md)
+- [CSS](./css.md)
+- [Environment Variables](./env.md)
+- [Config](./config.md)
+- [Type Safety](./typegen.md)
+- [Compatibility](./compat.md)
+- [Development](./dev.md)
+- [Performance](./performance.md)

package/reference/metadata.md CHANGED Viewed

@@ -1,86 +1,71 @@
 # Metadata
-Core metadata takes no request input, so it resolves at build time. `pnext build` evaluates metadata objects, `metadata()`/`viewport()` functions, and metadata route code, and `pnext start` serves the prebuilt head for static routes without recomputing it per request.
+Titles, descriptions, icons, and social images for a route. Metadata takes no request input in core, so it all resolves during the build, and the server sends the prebuilt head for a static route without recomputing it.
-Use `compat.next` for Next.js request-time metadata APIs such as `generateMetadata()`, `generateViewport()`, streaming metadata, `headers()`, `cookies()`, and full `next/og` behavior.
+## metadata
-## Page and Layout Exports
-Pages and layouts can export `metadata` as an object:
+Pages and layouts export it as an object. Metadata resolves from the root layout down to the page, and nearer segments override or extend what earlier ones set.
 ```tsx
-import type { Metadata } from '@wular/pnext';
+import type { Metadata } from '@wular/pnext'
 export const metadata: Metadata = {
   title: 'About',
   description: 'About the team',
-};
+}
 ```
-They can also export `metadata()` as a no-arg build-time function:
+## Fields
+pnext follows the Next.js field shapes for `title`, `description`, `metadataBase`, `openGraph`, `twitter`, `robots`, `icons`, `manifest`, `alternates`, `verification`, `appleWebApp`, `appLinks`, and `other`. The [Next.js metadata fields reference](https://nextjs.org/docs/app/api-reference/functions/generate-metadata#metadata-fields) documents the full schema.
+## metadata()
+A no-argument function export, for values that come from somewhere else. It runs during the build.
 ```tsx
 export async function metadata() {
-  const site = await getSiteMetadata();
-  return {
-    title: site.title,
-    description: site.description,
-  };
+  const site = await getSiteMetadata()
+  return { title: site.title, description: site.description }
 }
 ```
-Metadata is resolved from root layout to page. Nearer segments override or extend earlier segments.
-pnext follows the Next.js metadata field shapes for common fields such as `title`, `description`, `metadataBase`, `openGraph`, `twitter`, `robots`, `icons`, `manifest`, `alternates`, `verification`, `appleWebApp`, `appLinks`, and `other`. Use the [Next.js metadata fields reference](https://nextjs.org/docs/app/api-reference/functions/generate-metadata#metadata-fields) for the full field schema.
+## viewport
-## Viewport
-Pages and layouts can export `viewport` as an object or a build-time function:
+Pages and layouts export it as an object or as a build-time function, the same way.
 ```tsx
-import type { Viewport } from '@wular/pnext';
+import type { Viewport } from '@wular/pnext'
 export const viewport: Viewport = {
   width: 'device-width',
   initialScale: 1,
   themeColor: '#0b0b0b',
-};
+}
 ```
-Use `compat.next` for `generateViewport()` with route props.
+## Metadata files
-## File Conventions
+Drop these into a route segment and pnext picks them up:
-Core supports static metadata files in route segments:
+- `icon`, `apple-icon`, `opengraph-image`, and `twitter-image`, as `.ico`, `.jpg`, `.jpeg`, `.png`, `.svg`, `.gif`, or `.webp`, optionally numbered as `icon2.png`.
+- `sitemap.xml`.
+- `favicon.ico`, `robots.txt`, `manifest.json`, and `manifest.webmanifest`, at the app root only.
-- `icon`, `apple-icon`, `opengraph-image`, `twitter-image` — `.ico`, `.jpg`, `.jpeg`, `.png`, `.svg`, `.gif`, or `.webp`, optionally numbered (`icon2.png`)
-- `sitemap.xml`
-- `favicon.ico`, `robots.txt`, `manifest.json`, `manifest.webmanifest` — app root only
+The build copies them into the public output. Image and sitemap files apply to their segment and its descendants, while the root-only files are global.
-Static files are copied during `pnext build` and served from the built public output. Image and sitemap files apply to their segment and its descendants; the root-only files are global.
+## Generated metadata files
-## Code Metadata Files
+Each of the above has a code variant, written in `.tsx`, `.ts`, `.jsx`, `.js`, or `.mjs`: `icon`, `apple-icon`, `opengraph-image`, `twitter-image`, and `sitemap`, plus root-only `robots` and `manifest`.
-Core also supports code variants of each, in `.tsx`, `.ts`, `.jsx`, `.js`, or `.mjs`: `icon`, `apple-icon`, `opengraph-image`, `twitter-image`, `sitemap`, plus root-only `robots` and `manifest`.
-In core, these modules run at build time. Their generated links and route outputs are stored in the build output, and `pnext start` does not recompute them during page requests.
-Code metadata route handlers can keep their metadata-route signatures, including `generateImageMetadata()` and `generateSitemaps()`, but core treats their results as build artifacts. Request-time variants that depend on `headers()`, `cookies()`, or dynamic request state belong in `compat.next`.
+These modules run at build time, and their generated links and route outputs are stored in the build output rather than recomputed per request. They can keep their metadata-route signatures, including `generateImageMetadata()` and `generateSitemaps()`, but core treats the results as build artifacts. Use `params()` to choose build-time params, as shown in [Type Safety](./typegen.md).
 ## Precedence
-File-based metadata has higher priority than page/layout metadata for images and icons. Explicit page/layout image metadata still wins when it defines its own image list.
-The request path determines which segment metadata files apply. Route groups and parallel-route slot directories do not add URL path segments, but their metadata file output names are disambiguated at build time.
-## Static Params
+File-based metadata outranks page and layout metadata for images and icons, unless the page or layout defines its own image list.
-Core dynamic routes use `params()` for build-time param selection:
+The request path decides which segment's metadata files apply. Route groups and slot directories add no URL segment, and their metadata output names are disambiguated during the build.
-```tsx
-export function params() {
-  return [{ slug: 'intro' }];
-}
-```
+## Request-time metadata
-`generateStaticParams()` is a Next compat API. In `compat.next`, pnext treats it as the fallback static params provider when a module does not export core `params()`.
+Anything that depends on the request needs `compat.next`: `generateMetadata()`, `generateViewport()`, streaming metadata, `headers()`, `cookies()`, and full `next/og` behavior. Under compat, `generateStaticParams()` also serves as the fallback static params provider for a module with no `params()` export. See [Compatibility](./compat.md).