Data Sharing

AppShell's data sharing feature allows you to share your main application's data with micro-frontend applications.

Overview

It provides a flexible API to share data effectively, ensuring that each component within your ecosystem can access application data easily.

Data shared with micro-applications is read-only. Clients cannot modify the shared data directly.

How It Works

Data sharing is facilitated through a combination of React context and the framebus library for cross-origin communication. This setup ensures that micro-frontends running in isolated iframes can receive shared data seamlessly.

Flow

1. Initialization - AppShellProvider initializes with the shared data

2. Client Connection - When a client iframe loads, it sends a SET_CONFIG event

3. Data Distribution - Shell responds with SET_DATA containing the shared data

4. Updates - When shared data changes, shell broadcasts updates to all connected clients

Usage

Pass the data prop to AppShellProvider:

import { AppShellProvider, type ApplicationData } from '@akinon/app-shell';

const App = () => {
  const data: ApplicationData = {
    user: {
      id: 1,
      name: 'Jane Doe',
      email: '[email protected]'
    },
    theme: 'dark',
    locale: 'en'
  };

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

ApplicationData Type

interface ApplicationData {
  searchParams?: Record<string, string>;
  [key: string]: any;
}

The ApplicationData type is flexible, allowing you to share any serializable data. The optional searchParams field is commonly used for URL query parameters.

Example Data Structure

const sharedData: ApplicationData = {
  // User information
  user: {
    id: 123,
    name: 'John Doe',
    role: 'admin'
  },
  
  // Application settings
  settings: {
    theme: 'dark',
    language: 'tr',
    timezone: 'Europe/Istanbul'
  },
  
  // URL parameters
  searchParams: {
    page: '1',
    limit: '20'
  }
};

Dynamic Data Updates

When shared data changes, update the data prop and the changes will be propagated to all connected clients:

import { useState } from 'react';
import { AppShellProvider } from '@akinon/app-shell';

const App = () => {
  const [sharedData, setSharedData] = useState<ApplicationData>({
    user: null,
    theme: 'light'
  });

  const handleLogin = (user: User) => {
    setSharedData(prev => ({
      ...prev,
      user
    }));
  };

  const toggleTheme = () => {
    setSharedData(prev => ({
      ...prev,
      theme: prev.theme === 'light' ? 'dark' : 'light'
    }));
  };

  return (
    <AppShellProvider
      apps={registeredApps}
      data={sharedData}
      navigation={navigationConfig}
      actions={shellActions}
    >
      <button onClick={toggleTheme}>Toggle Theme</button>
      {/* Rest of your application */}
    </AppShellProvider>
  );
};

Accessing Shared Data (Client Side)

Clients access shared data via the useAppClient hook:

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

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

  return (
    <div>
      <p>Welcome, {data.user?.name}</p>
      <p>Theme: {data.theme}</p>
    </div>
  );
};

For detailed information about accessing data on the client side, see the Client Application documentation.

Best Practices

1. Share Only Necessary Data

Avoid sharing the entire application state. Share only the data that micro-applications need for their functionality.

// ❌ Bad - Sharing entire Redux store
const data = {
  ...entireReduxStore
};

// ✅ Good - Selective data sharing
const data = {
  user: store.getState().auth.user,
  locale: store.getState().settings.locale
};

2. Avoid Data Duplication

Clients should not copy shared data into their own state. Always reference the shared data from useAppClient.

// ❌ Bad - Duplicating data in client state
const ClientComponent = () => {
  const { data } = useAppClient();
  const [user, setUser] = useState(data.user); // Don't do this!
  
  return <div>{user.name}</div>;
};

// ✅ Good - Direct reference to shared data
const ClientComponent = () => {
  const { data } = useAppClient();
  
  return <div>{data.user?.name}</div>;
};

3. Use Serializable Data Only

Only serializable data can be shared via postMessage. Functions, class instances, and circular references cannot be shared.

// ❌ Bad - Non-serializable data
const data = {
  user: userInstance,           // Class instance
  formatDate: (d) => d.toISOString(), // Function
  element: document.getElementById('app') // DOM element
};

// ✅ Good - Serializable data only
const data = {
  user: {
    id: userInstance.id,
    name: userInstance.name
  },
  dateFormat: 'ISO',
  elementId: 'app'
};

See MDN Structured Clone Algorithm for the full list of supported types.

4. Keep Data Flat When Possible

Deeply nested data structures can be harder to work with and may impact performance during serialization.

// Consider flattening when appropriate
const data = {
  userId: 123,
  userName: 'John Doe',
  userRole: 'admin',
  // Instead of: user: { id, name, role }
};

Next Steps

• Actions - Define custom actions for clients

• Navigation - Configure navigation helpers