updateTwilightContext

In plain words

Signature

function updateTwilightContext(partial: Partial<TwilightContext>): void

Try it live

import {
  getTwilightContext,
  updateTwilightContext,
} from '@salla.sa/twilight-theme-engine/tanstack';

// In an event handler or effect, never while rendering.
export function rememberCampaign() {
  const { extras } = getTwilightContext();
  // extras is replaced as a whole, so spread what is already there.
  updateTwilightContext({ extras: { ...extras, campaign: 'summer-sale' } });
}

Example

import { useEffect } from 'react';
import { useLocation } from '@salla.sa/twilight-theme-engine/providers';
import {
  getTwilightContext,
  updateTwilightContext,
} from '@salla.sa/twilight-theme-engine/tanstack';

// Remembers ?utm_campaign= for loaders that run in this browser later.
export function CampaignCapture() {
  const { search } = useLocation<{ utm_campaign?: string }>();
  const campaign = search.utm_campaign ? String(search.utm_campaign) : null;

  useEffect(() => {
    if (!campaign) return;
    const { extras } = getTwilightContext();
    updateTwilightContext({ extras: { ...extras, campaign } });
  }, [campaign]);

  return null;
}

How it behaves

• queryClient, settings, locale, routeId and i18n ignore null and undefined, so they cannot be cleared. location is merged into the current location field by field.

• authToken, scope, storeId, storeBase, versionId and requestHost accept null to clear. page, appsSnippets, appsSettings and extras are replaced by whatever you pass, undefined included. scopeId sets scope to { id } when scope itself is not given.

• In the browser it notifies subscribers, so useRouteId() and the page-detection hooks render again. On the server nothing is notified.

• On the server it writes into the current request's context, and throws [Twilight] No request context… outside one. Call it in handlers, effects, loaders or middleware, never while a component renders.

Gotchas

• The engine overwrites what it owns: every navigation writes location, routeId and settings again, and the root route writes locale, settings, i18n and authToken. A value you put in those fields lasts until the next navigation. Keep your own values in extras.

• extras is replaced, not merged: updateTwilightContext({ extras: { banner } }) removes a campaign stored before. Spread the current extras first, as the example does.

• A value written on the server stays there. Hydration copies settings, locale, i18n, auth token, location, page, route id and the app snippets and settings into the browser, nothing else (src/tanstack/router.tsx), so extras written by a middleware is undefined in the browser. Return what the browser needs from a loader.

Related

Source and docs

• Engine source: packages/theme-engine/src/twilight/context.ts