Global Contexts

Global contexts are React Components with global data and behaviors you want accessible to all your pages and components. They can:

• Provide data via React Contexts to consumers in code components
• Provide data to Studio pages and components via DataProvider
• Provide actions to Studio pages and components via GlobalActionsProvider

Global context implementation

A global context is like any other React Component.

For example, here’s a global context that implements authentication, providing the current user and login/logout actions:

import React, { useEffect, useMemo, useState } from "react";
import { DataProvider, GlobalActionsProvider } from "@plasmicapp/host"; // or "@plasmicapp/loader-*""

// These are functions your app should implement.
type User;
function getCurrentUser(authUrl?: string): Promise<User | null>;
function login(credential: string, authUrl?: string): Promise<User | null>;
function logout(authUrl?: string): Promise<void>;

// Users will be able to set these props in Studio.
interface AuthGlobalContextProps {
  // You might use this to override the auth URL to a test or local URL.
  authUrl?: string;
}

export const AuthGlobalContext = ({ children, authUrl }: React.PropsWithChildren<AuthGlobalContextProps>) => {
  const [user, setUser] = useState<User | null>(null);

  // Get current user on mount
  useEffect(() => {
    getCurrentUser(authUrl).then(user => setUser(user));
  }, [authUrl]);

  const actions = useMemo(() => ({
    login: (credential: string) => login(credential, authUrl).then(user => setUser(user)),
    logout: () => logout().then(() => setUser(null)),
  }), [authUrl]);

  return (
    <GlobalActionsProvider contextName="AuthGlobalContext" actions={actions}>
      <DataProvider name="auth" data={user}>
        {children}
      </DataProvider>
    </GlobalActionsProvider>
  );
}

Global context registration

You should have your app host page set up before registering your global context.

Global contexts are registered similar to code components. When you register a global context, you are giving Plasmic two pieces of critical information:

1. The actual React component function or class, so that Plasmic can instantiate and render the global context.
2. Global context metadata, like its name and its props, so that Plasmic can generate the control UI in the Project Settings left panel for Plasmic users to configure its props.

For example, here’s how to register the above global context:

import { AuthGlobalContext } from "./components/AuthGlobalContext";

export const PLASMIC = initPlasmicLoader(...);

PLASMIC.registerGlobalContext(AuthGlobalContext, {
  // name should match GlobalActionsProvider contextName
  name: "AuthGlobalContext",
  // props should match AuthGlobalContextProps
  props: { authUrl: "string" },
  // providesData should be true if the global context has a DataProvider
  providesData: true,
  // globalActions should match the global context's GlobalActionsProvider
  globalActions: {
    login: { parameters: [{ name: "credential", type: "string" }] },
    logout: { parameters: [] },
  },
});

Visit the Global Context Registration API page to learn more about all the metadata you can specify when you register your global context.

Using your global contexts in Studio

Once you have finished registering your global contexts, make sure your changes are available on your app host, and reload your Plasmic project.

Check the following:

• The global context shows in the Project Settings tab with the correct props.
• Provided data is available in a dynamic value.
• Provided actions are available in a interactions.

Evolving global contexts over time

You can continue updating the code for your global contexts, and Plasmic will always use whatever is made available on the app host page.

However, occasionally, you want to evolve the metadata for your global contexts — its name and its props. To do so, you should make the updates to your registerGlobalContext() call, deploy your update to your app host, and then reload the Plasmic project using that app host; Plasmic will then read the new metadata, and update accordingly.

There are a few caveats to be aware of as you make your updates:

Renaming global contexts

When you change the name from A to B, the next time you open a project containing A, Plasmic Studio will remove the instance of A and add a new instance of B. Note that this removes all existing arguments/values passed into that prop.

Changing props

Changing the type of a prop will prompt you to confirm removing usages of the old prop. Note that this removes all existing arguments/values passed into that prop.

Changing the type or name of a prop in a way that carries over all old values passed in for that prop is not yet supported.

Adding new global contexts and props

Since these are non-destructive changes, these will immediately take effect in the project without further user interaction.

Using Global Context in codegen

When generating the code for your project using Codegen, each project that has global contexts will have a PlasmicGlobalContextsProvider file. By default, each page will be wrapped in the GlobalContextsProvider from it’s project, but you can change this setting by changing the wrapPagesWithGlobalContexts flag in your plasmic.json file.

Prop override

You can override the props that you pass to your global contexts in both the Headless API and in Codegen.

<PlasmicRootProvider
  loader={PLASMIC}
  globalContextsProps={{
    productContextProps: { tokenId: "token-id" }
  }}
>
  <PlasmicComponent component="YourPage" />
</PlasmicRootProvider>

Have feedback on this page? Let us know on our forum.