umi-plugin-multistage-route

A UmiJS plugin that provides multistage route decorators to preserve parent route state using show/hide mechanisms instead of unmounting components.

Features

• 🚀 State Preservation: Maintains parent route component state when navigating to child routes
• 🎯 Performance Optimization: Avoids unnecessary component remounting
• 🔧 Flexible Configuration: Support for both boolean and object configuration
• 📦 TypeScript Support: Full TypeScript definitions included
• 🌟 UmiJS Integration: Seamless integration with UmiJS routing system

Installation

npm install umi-plugin-multistage-route

or

yarn add umi-plugin-multistage-route

Usage

Basic Configuration

Add the multistage property to parent routes in your route configuration:

// .umirc.ts or config/config.ts
export default {
  routes: [
    {
      path: '/dashboard',
      component: './pages/Dashboard',
      multistage: true, // Enable multistage routing
      routes: [
        {
          path: '/dashboard/analytics',
          component: './pages/Dashboard/Analytics',
        },
        {
          path: '/dashboard/reports',
          component: './pages/Dashboard/Reports',
        }
      ]
    }
  ]
}

Advanced Configuration

For more control over the rendering behavior:

{
  path: '/workspace',
  component: './pages/Workspace',
  multistage: {
    forceRender: true // Force render even when hidden
  },
  routes: [
    {
      path: '/workspace/projects',
      component: './pages/Workspace/Projects',
    }
  ]
}

Configuration Options

multistage: boolean

When set to true, enables basic multistage routing behavior.

multistage: { forceRender: boolean }

• forceRender: When true, forces the parent component to continue rendering even when child routes are active.

How It Works

The plugin works by:

1. Wrapping Components: Automatically wraps multistage route components with a decorator
2. State Management: Uses show/hide mechanisms instead of mount/unmount cycles
3. Route Patching: Modifies the route configuration during build time
4. Template Generation: Generates wrapper components using Mustache templates

TypeScript Support

The plugin includes full TypeScript definitions. Import the types when needed:

import { MultistageRoute } from 'umi-plugin-multistage-route';

// Use in your route configuration
const routes: MultistageRoute[] = [
  {
    path: '/example',
    component: './Example',
    multistage: true,
    routes: [
      // child routes...
    ]
  }
];

Use Cases

This plugin is particularly useful for:

• Dashboard Applications: Preserve sidebar state when navigating between dashboard sections
• Multi-step Forms: Maintain form state across different steps
• Tab Interfaces: Keep tab content loaded while switching between tabs
• Complex Layouts: Preserve expensive component state in parent layouts

Example

// Route configuration
{
  path: '/app',
  component: './layouts/AppLayout',
  multistage: true,
  routes: [
    {
      path: '/app/home',
      component: './pages/Home',
    },
    {
      path: '/app/profile',
      component: './pages/Profile',
    }
  ]
}

In this example, the AppLayout component will remain mounted and preserve its state when users navigate between /app/home and /app/profile.

Requirements

• UmiJS 4.x
• Node.js >= 14

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © [Author Name]