Synchronizing with History
Stackflow's navigation logic does not rely on browser history by default. This is to support environments like React Native and NativeScript where the History API is not available. Therefore, to use browser history for navigation, you need to synchronize the stack state with the browser history. This functionality is provided by @stackflow/plugin-history-sync.
Install @stackflow/plugin-history-sync using the following command.
npm install @stackflow/plugin-history-syncOnce the installation is complete, register the plugin in the plugins field of the stackflow() function as follows.
import { stackflow } from "@stackflow/react";
import { basicRendererPlugin } from "@stackflow/plugin-renderer-basic";
import { historySyncPlugin } from "@stackflow/plugin-history-sync";
import MyActivity from "./MyActivity";
import Article from "./Article";
const { Stack, useFlow } = stackflow({
transitionDuration: 350,
activities: {
MyActivity,
Article,
},
plugins: [
basicRendererPlugin(),
basicUIPlugin({
theme: "cupertino",
}),
historySyncPlugin({
routes: {
MyActivity: "/my-activity",
Article: "/articles/:articleId",
},
fallbackActivity: () => "MyActivity",
}),
],
// The initialActivity option no longer works because it is overridden by the historySyncPlugin.
// initialActivity: () => "MyActivity",
});The historySyncPlugin accepts two options: routes and fallbackActivity.
| Option | Type | Description |
|---|---|---|
| routes | object | Connects activities with URL templates. You can represent activity parameters as Path Parameters. If an activity's parameter is not in the URL template, it will automatically be represented as a Query Parameter. |
| fallbackActivity | function | Determines which activity to navigate to if there is no matching URL when first entering. Typically, you create a 404 page and assign it here. |
Warning - When mapping activity parameters to path parameters, ensure that the parameter values are URL-safe. If special characters that are not URL-safe are used, query parameters may appear duplicated.
In a server-side rendering environment, the window.location value is not available, so the initial activity cannot be determined. To set the initial activity, add the path value to the req.path field in the initialContext of the Stack as follows:
<Stack initialContext={{ req: { path: "/..." } }} />