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-sync

Once the installation is complete, declare routes in stackflow.config.ts and register the plugin in stackflow().

stackflow.config.ts

import { defineConfig } from "@stackflow/config";
 
export const config = defineConfig({
  activities: [
    {
      name: "MyActivity",
      route: "/my-activity",
    },
    {
      name: "Article",
      route: "/articles/:articleId",
    },
  ],
  transitionDuration: 350,
});

stackflow.ts

import { stackflow } from "@stackflow/react";
import { basicRendererPlugin } from "@stackflow/plugin-renderer-basic";
import { basicUIPlugin } from "@stackflow/plugin-basic-ui";
import { historySyncPlugin } from "@stackflow/plugin-history-sync";
import { config } from "./stackflow.config";
import MyActivity from "./MyActivity";
import Article from "./Article";
 
const { Stack, useFlow } = stackflow({
  config,
  components: {
    MyActivity,
    Article,
  },
  plugins: [
    basicRendererPlugin(),
    basicUIPlugin({
      theme: "cupertino",
    }),
    historySyncPlugin({
      config,
      fallbackActivity: () => "MyActivity",
    }),
  ],
});

The historySyncPlugin accepts two options: config and fallbackActivity.

Option	Type	Description
config	`object`	The config object created with `defineConfig()`. Routes are read from the `route` field of each activity definition.
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: "/..." } }} />

Writing Your Own Plugin Resolving Circular Reference in useFlow