The 3.2 candidate adds optional @getforma/router, @getforma/core/navigation, native navigation groups and typed Rust owner/action responses. This guide targets 3.2.0-rc.2. Consult the release record before installing it. Published 3.0 and 3.1 records remain unchanged.
Upgrade the coordinated packages#
Use the same published candidate for core, compiler, build, create-app and all three Rust crates. Add router only where an application opts into navigation. For a prerelease, pin the exact candidate throughout; do not mix candidate router with 3.1 core. A 3.1 reader cannot consume a 3.2 manifest.
Update and commit the npm and Cargo locks, rebuild the frontend/native assets, then rebuild the Rust executable. Deploy the complete result atomically and retain the previous complete artifact set for rollback. Updating the browser group independently of its manifest or server is not a supported rollout.
Choose a migration#
| Existing application | Change |
|---|---|
| Plain server links or no-JS pages | Keep them; routing is optional |
| Custom browser history and conditional rendering | Declare browser owners and use createBrowserAdapter |
| Generated HTML page swapping | Generate a hash registry and admitted content regions; attach widget cleanup to the adapter session |
| Typed Rust pages needing retained layouts | Add a native navigation group, typed shell/leaf owners and createNativeAdapter |
Read the routing guide first. Remove the old navigator's competing click, popstate and history bookkeeping. Preserve ordinary links for downloads, external URLs, unsupported markup and explicit document boundaries.
Native application responsibilities#
Enable the Rust navigation feature and bind finalized typed page handles. A non-leaf owner needs one literal outlet outside its islands. Group owners share the same CSS/font list and a closed eager executable graph. Dynamic imports, group code splitting and independent group watch builds are outside the first profile.
The sealed policy includes the effective response policy and declared action allowlist. Check middleware and proxies as well as handler code. Session/context generation comes from the server; revoke retained owners when that context changes. Enhanced actions do not supply application authentication, CSRF protection, idempotency or transactions.
Browser layout effects belong to the route owner's lifetime. Use ownership cleanup for listeners, timers, observers and workers. A retained parent survives child changes; a departed leaf releases its resources.
Starters and downloadable projects#
Choose --template native-router for a connected Rust example; create your first routed app walks through it. The minimal template remains the ordinary SSR example. Keep browser-rendered projects on the browser adapter. The dedicated website router project exercises fresh leaf props and retained shell state without changing the deliberate no-JS examples.
Scaffold from a published candidate CLI or its documented sealed-pack workflow. Source template locks are release seeds until packing fills verified registry integrity/checksums. Do not distribute a local-path dependency graph as a runnable public download.
Check before rollout#
Verify direct URLs, refresh, JavaScript-disabled navigation, retained layout state, fresh server props, leaf cleanup, Back/Forward, keyboard focus and supported motion preferences. Exercise policy/build fallback and mutation uncertainty if your application has actions. Test the complete rollback on the actual server and assets. Retain existing production behavior until your application passes its own acceptance checks.