DOCSEARCHbyAlgolia
Submit Docs

Stackflow Documentation

repository·main·Indexed 21 days ago

https://github.com/daangn/stackflow

A headless navigation library for web and hybrid applications that implements mobile-style stack navigation, including transitions and swipe-back gestures. It consists of a core state management engine (@stackflow/core) and framework integrations such as @stackflow/react, along with various extensions for browser history synchronization, lifecycle management, basic UI components (AppScreen, Modal, BottomSheet), and devtools.

Tokens
85.8K
Snippets
247
Records
337
Agent score
74%

What's inside Stackflow

  1. What is Stackflow?

    main

    Stackflow is a navigation library designed to implement Stack Navigation UX (common in iOS/Android) within JavaScript environments. It is ideal for developing hybrid apps and webviews.

    Key Features:

    • Stack Management: Manages stack screens and preserves scrolling state.
    • Transitions: Supports screen stacking effects and reverse transition effects when navigating back.
    • Gestures: Supports iOS-style swipe-to-go-back gestures.
    • Parameter Passing: Enables passing necessary parameters to screens during transitions.
    • Headless Core: The core logic (state and transitions) is decoupled from the UI, allowing you to use the state independently or inject your own UI.
    • Extensible: Provides a plugin interface to inject logic between lifecycles.
    • Framework Agnostic Core: While the current React integration is the primary focus, the separation of core logic and integration layers allows for multi-framework support.
    • SSR Support: Compatible with Server-Side Rendering via ReactDOMServer.renderToString.

  3. What is an Activity in Stackflow

    main

    In Stackflow, an Activity represents an individual screen being stacked on the display. Each activity possesses specific properties that can be accessed via the useActivity() hook.

    Activity Properties

    PropertyTypeDescription
    idstringA unique ID for each active activity instance
    namestringThe registered name of the activity
    transitionState'enter-active' | 'enter-done' | 'exit-active' | 'exit-done'The current state of the activity transition

  4. What is a Structured Activity and how to use it

    main

    A Structured Activity is a pattern in Stackflow that separates an activity into four distinct concerns: content, layout, loading state, and error handling. This separation allows for automatic code splitting, Suspense-based loading, and error boundaries without manual wiring.

    To create a structured activity, use structuredActivityComponent() instead of a standard React component when registering your activity in the stackflow() configuration.

    Render Order

    The components are rendered in the following hierarchy: Layout wraps ErrorHandler wraps Suspense(Loading) wraps Content.

    Basic Implementation

    import { structuredActivityComponent } from "@stackflow/react";

declare module "@stackflow/config" {
  interface Register {
    Article: {
      articleId: number;
      title?: string;
    };
  }
}

export const Article = structuredActivityComponent<"Article">({
  content: ArticleContent,
});
    import { structuredActivityComponent } from "@stackflow/react";

declare module "@stackflow/config" {
  interface Register {
    Article: {
      articleId: number;
      title?: string;
    };
  }
}

export const Article = structuredActivityComponent<"Article">({
  content: ArticleContent,
});

  5. What is Structured Activity?

    main

    A Structured Activity is a way to decouple a single activity into four distinct concerns: content, layout, loading state, and error handling. This approach allows for natural integration of code splitting, Suspense-based loading, and error boundaries without manual wiring.

    When using Structured Activities, the rendering order follows this nesting pattern: Layout → ErrorHandler → Suspense(Loading) → Content.

  7. Customize Stackflow UI and Lifecycle

    main

    Stackflow is designed to be headless and extensible. You are not forced to use a specific UI implementation.

    • Headless Usage: You can use the stack and transition state without any built-in UI, allowing you to build your own custom interface from scratch.
    • Lifecycle Extensions: You can inject custom logic into the navigation lifecycle using the plugin interface.

  8. Customizing Stackflow with Headless UI and Plugins

    main

    Stackflow is designed to be highly customizable through two main mechanisms:

    1. Headless Logic: You can use the stack and transition state management without any built-in UI. This allows you to build your own custom UI components from scratch while leveraging Stackflow's core navigation logic.
    2. Plugin Interface: You can inject custom extensions into the navigation lifecycle using a plugin interface, allowing you to add specialized behavior at specific stages of screen transitions.

  9. What are Navigating Steps in Stackflow

    main

    Steps allow you to maintain a virtual stack state within a single activity. Instead of switching to a completely different activity, a step works by changing the parameters of the current activity. This is useful for managing sub-states or multi-stage flows within one screen.

    If you are using @stackflow/plugin-history-sync and need to handle specific state manipulations alongside Android back button support on mobile, using the step feature is recommended over using history.pushState() directly.

  10. How Stackflow state works

    main

    Stackflow's internal state is modeled as a stack data structure combined with transition states.

    Each activity in the stack contains information about its existence (ID, name) and its current transition state. These states (like enter-active or exit-done) allow the framework and its plugins (such as @stackflow/plugin-basic-ui) to coordinate animations and UI updates as users navigate through the application.

  11. Referential stability of useFlow and useStepFlow actions

    main

    As of @stackflow/react@2.1.1, the action functions returned by useFlow and useStepFlow (such as push, replace, pop, pushStep, replaceStep, and popStep) are memoized.

    This ensures that the function references remain stable across renders, making them safe to use as dependencies in useEffect or useCallback without triggering unnecessary re-runs.

  12. Stackflow support for SSR and TypeScript

    main

    Stackflow is built with modern web development requirements in mind:

    • Server-Side Rendering (SSR): Supports ReactDOMServer.renderToString for pre-rendering navigation states.
    • TypeScript: Provides full type definitions for all functions to ensure type safety during development.
    • React Support: As of the current version, it supports React and React DOM as primary references.