Navigation.createRouter
luastra/navigationNavigation.createRouter(options: any): EntryStack
Creates an entry-based navigation stack whose entries carry a route name, parameters, query values, and optional state. Mutations return structured results rather than relying on unchecked table shapes.
Before you use it
Add luastra/navigation to this module's dependencies in luastra.json, then import it with require("luastra/navigation"). No host capability is required for in-memory navigation. Browser URL/history synchronization additionally needs luastra/host and navigation.history.
How it fits
The operation updates or creates application-owned navigation state synchronously. Keep stacks and compilers outside app.render, inspect every result.success field, then render from the accepted current entry.
When to use it
Use Navigation.createRouter when each history entry needs typed route data that can later be compiled to or restored from a location. Prefer Navigation.create for a simpler name-only stack.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| options | any | Route compiler, initial typed entry, and optional entry-stack settings. |
| options.compiler | RouteCompiler | Compiler previously returned by Navigation.compile. |
| options.initial | RouteEntry | Initial typed entry that the compiler can generate successfully. |
| options.maximumDepth | integer (1..32)? | Optional history-depth bound; defaults to 32. |
Returns
EntryStack — a stateful typed-route stack with canonical location and snapshot operations.
What happens next
A validated compiler, stack, decision, or result record; host history changes only when the application requests them separately.
Failures and fixes
Invalid definitions, unknown routes, malformed parameters, excessive history depth, or incompatible snapshots return bounded errors or fail construction. Navigation result records use success:boolean with optional fields, so verify the field you need after checking success.
Availability
Public-source alpha API in 0.5.0-alpha; URL integration is a separate host capability.
Focused example
local Navigation = require("luastra/navigation")
local router = Navigation.createRouter {
compiler = compiler,
initial = {
name = "home",
params = {},
query = {},
},
}Continue with a complete recipe
This checked recipe uses Navigation.createRouter inside complete authored files with the required manifest, test, and run steps.
Open add typed navigation recipe