Navigation

AppShell's navigation helpers allow micro-frontend applications to trigger navigation in the main application.

Overview

This enables clients to redirect users to different pages within the shell application without direct access to the shell's router.

Navigation helpers are router-agnostic. You implement them using your preferred routing library (React Router, Next.js Router, etc.).

How It Works

1. Shell defines a navigate function and passes it to AppShellProvider

2. Client calls navigation.navigate({ path: '/some-path' })

3. Shell receives the navigation request via framebus

4. Shell executes the navigation using its router

Usage

Pass the navigation prop to AppShellProvider:

import { AppShellProvider, type ShellNavigation } from '@akinon/app-shell';
import { useNavigate } from 'react-router';

const App = () => {
  const routerNavigate = useNavigate();

  const navigation: ShellNavigation = {
    navigate: (payload) => {
      routerNavigate(payload.path);
    }
  };

  return (
    <AppShellProvider
      apps={registeredApps}
      data={sharedData}
      navigation={navigation}
      actions={shellActions}
    >
      {/* Your shell application */}
    </AppShellProvider>
  );
};

ShellNavigation Type

interface ShellNavigation {
  navigate: (payload: NavigationPayload) => void;
}

interface NavigationPayload {
  path: string;
  id?: number;
}

Property	Type	Description
path	string	The target path to navigate to
id	number	Optional. Application ID for context

Implementation Examples

React Router

import { useNavigate } from 'react-router';
import { AppShellProvider, type ShellNavigation } from '@akinon/app-shell';

const App = () => {
  const navigate = useNavigate();

  const navigation: ShellNavigation = {
    navigate: ({ path }) => {
      navigate(path);
    }
  };

  return (
    <AppShellProvider navigation={navigation} {...otherProps}>
      {children}
    </AppShellProvider>
  );
};

TanStack Router

import { useNavigate } from '@tanstack/react-router';
import { AppShellProvider, type ShellNavigation } from '@akinon/app-shell';

const App = () => {
  const navigate = useNavigate();

  const navigation: ShellNavigation = {
    navigate: ({ path }) => {
      navigate({ to: path });
    }
  };

  return (
    <AppShellProvider navigation={navigation} {...otherProps}>
      {children}
    </AppShellProvider>
  );
};

With Application ID

You can use the optional id parameter to handle navigation with application context:

const navigation: ShellNavigation = {
  navigate: ({ path, id }) => {
    if (id) {
      // Navigate to app-specific route
      navigate(`/apps/${id}${path}`);
    } else {
      navigate(path);
    }
  }
};

Using Navigation (Client Side)

Clients trigger navigation via the useAppClient hook:

// In the client application
import { useAppClient } from '@akinon/app-client';

const ClientComponent = () => {
  const { navigation } = useAppClient();

  const handleViewOrder = (orderId: string) => {
    navigation.navigate({ path: `/orders/${orderId}` });
  };

  const handleGoBack = () => {
    navigation.navigate({ path: '/dashboard' });
  };

  return (
    <div>
      <button onClick={() => handleViewOrder('123')}>
        View Order
      </button>
      <button onClick={handleGoBack}>
        Back to Dashboard
      </button>
    </div>
  );
};

For detailed information about using navigation on the client side, see the Client Application documentation.

Advanced Usage

Handling External Navigation

You may want to handle external URLs differently:

const navigation: ShellNavigation = {
  navigate: ({ path }) => {
    if (path.startsWith('http://') || path.startsWith('https://')) {
      // External URL - open in new tab
      window.open(path, '_blank');
    } else {
      // Internal path - use router
      routerNavigate(path);
    }
  }
};

Navigation with Query Parameters

Query parameters can be included in the path:

// Client
navigation.navigate({ path: '/products?category=electronics&page=2' });

// Shell handles it naturally
const navigation: ShellNavigation = {
  navigate: ({ path }) => {
    routerNavigate(path); // Includes query params
  }
};

Navigation with State

If you need to pass state data during navigation, use a combination of navigation and actions:

// Shell
const actions = {
  navigateWithState: (path: string, state: any) => {
    routerNavigate(path, { state });
  }
};

// Client
actions.actions.navigateWithState('/details', { fromPage: 'list' });

Best Practices

1. Keep Navigation Logic Simple

The navigation handler should focus on routing. Complex logic should be in actions.

// ❌ Bad - Too much logic in navigation
navigate: ({ path }) => {
  logAnalytics(path);
  saveToHistory(path);
  checkPermissions(path);
  routerNavigate(path);
}

// ✅ Good - Simple navigation, side effects in actions
navigate: ({ path }) => {
  routerNavigate(path);
}

2. Handle Unknown Paths Gracefully

Consider what happens when a client requests an invalid path:

navigate: ({ path }) => {
  const validRoutes = ['/dashboard', '/orders', '/products'];
  const isValidPrefix = validRoutes.some(route => path.startsWith(route));
  
  if (isValidPrefix) {
    routerNavigate(path);
  } else {
    routerNavigate('/404');
  }
}

3. Consider Navigation Timing

If clients navigate immediately on mount, ensure the shell is ready:

// Shell - wrap navigation in a safe check
navigate: ({ path }) => {
  if (isAppReady) {
    routerNavigate(path);
  } else {
    pendingNavigation.current = path;
  }
}

Next Steps

• Data Sharing - Share data with clients

• Actions - Define custom actions