handle-startup-state

Handle Startup State

Reads the optional initialState string returned by connectToHostApp() and restores it before first render, so the app opens directly into the right view instead of always starting from defaults.

Requires @cognite/app-sdk's connectToHostApp() handshake already wired up. If auth isn't wired up yet, run the setup-flows-auth skill first.

What initialState actually is

initialState is a single opaque string, present on the object returned by connectToHostApp():

const { api, initialState } = await connectToHostApp();

Your app never needs to know how it got there — treat it the same way regardless of source:

• A user opened a shareable URL your app previously wrote via api.syncInternalState(...) (the customAppInternalState URL param).
• A host embedded your app with a startup argument baked in (a Flows dashboard widget, or any other surface that programmatically launches your app with initial arguments).
• The app was reloaded and the current URL still has the param from an earlier syncInternalState call.

All three arrive through the same field. Design your restore logic once and it covers all of them.

Step 1 — Decide your encoding

Pick one encoding and use it consistently:

• Serialized route (a path string) — if your app's state maps cleanly onto a URL you'd otherwise navigate to.
• JSON string — if you need multiple independent fields (active tab, filters, selected IDs). This is the more common choice and the one used below.

Step 2 — Read initialState on mount, defensively

Restore before the first meaningful render. Malformed state must never crash the app — the host cannot guarantee the string is well-formed (it never parses it either), and an older app version may have written a different shape.

import { useEffect, useRef, useState } from 'react';
import { connectToHostApp, type HostAppAPI } from '@cognite/app-sdk';

interface AppState {
  activeTab: string;
  selectedAssetId?: string;
  filters: { status: string };
}

const DEFAULT_STATE: AppState = {
  activeTab: 'overview',
  filters: { status: 'all' },
};

export function parseInitialState(initialState: string | undefined): AppState {
  if (!initialState) return DEFAULT_STATE;
  try {
    const parsed = JSON.parse(initialState) as Partial<AppState>;
    return { ...DEFAULT_STATE, ...parsed };
  } catch {
    // Malformed or from an incompatible app version — fall back to defaults.
    return DEFAULT_STATE;
  }
}

export function useAppState() {
  const [api, setApi] = useState<HostAppAPI | null>(null);
  const [state, setState] = useState<AppState>(DEFAULT_STATE);
  const apiRef = useRef<HostAppAPI | null>(null);

  useEffect(() => {
    connectToHostApp()
      .then(({ api: resolvedApi, initialState }) => {
        apiRef.current = resolvedApi;
        setApi(() => resolvedApi);
        setState(parseInitialState(initialState));
      })
      .catch(() => {
        // connectToHostApp rejects when there's no Fusion parent window to
        // connect to (e.g. opening the raw Vite dev URL directly instead of
        // through Fusion). api and state simply stay at their initial
        // values (null / DEFAULT_STATE) — nothing else to do here.
      });
  }, []);

  return { api, state, setState, apiRef };
}