Skip to main content

Installing the Headless SDK

This guide shows how to add Solis, Prismatic's headless SDK, to your frontend and connect it to Prismatic as a signed-in customer user. After it connects, you can read the marketplace, instances, and connections and render them with your own components.

Before you begin​

  • Your backend must sign a JWT for each signed-in user, as described in Authenticating embedded users. Solis uses the same token as the hosted embedded SDK.
  • Solis runs in the browser. It doesn't support server-side rendering: during a server render, the React hooks stay loading.

Install the package​

Solis has two packages. Install the one that matches your frontend:

PackageUse it when
@prismatic-io/solis-reactYour app uses React 18 or 19. It includes @prismatic-io/solis-core, so you don't install both.
@prismatic-io/solis-coreYour app uses another framework, or none.
npm install @prismatic-io/solis-react@latest

Connect to Prismatic​

Solis connects to Prismatic through a hidden iframe that it adds to your page. The iframe never renders anything, and your app never calls Prismatic's API directly. You pass Solis two things:

  • Your Prismatic URL: https://app.prismatic.io, the URL of your deployment region (like https://app.eu-west-1.prismatic.io), or your custom white-label domain.
  • The user's JWT: The token your backend signed for the signed-in user.

Wrap the part of your app that uses Prismatic in PrismaticProvider:

Integrations.tsx
import { PrismaticProvider } from "@prismatic-io/solis-react";

export function Integrations({ token }: { token: string }) {
  return (
    <PrismaticProvider
      prismaticUrl="https://app.prismatic.io"
      auth={{ token }}
      onError={(error) => console.error("Prismatic session failed", error)}
    >
      <IntegrationsPage />
    </PrismaticProvider>
  );
}

Hooks inside the provider share one session and one cache. Until the provider receives a token, the session stays loading.

Refresh the token​

Embedded user JWTs expire, so your app needs to fetch new ones while the user is signed in. When it does, pass the new token to Solis. Solis applies it to the live session, so loaded data stays in place. If the new token belongs to a different user, Solis drops the previous user's data.

Pass the new token to PrismaticProvider through the auth prop.

Verify the connection​

Confirm that Solis connected and accepted the token by reading the signed-in user:

IntegrationsPage.tsx
import { useAuthenticatedUser, usePrismatic } from "@prismatic-io/solis-react";

function IntegrationsPage() {
  const session = usePrismatic();
  const user = useAuthenticatedUser();

  if (session.status === "error") {
    return <p>Could not connect: {session.error.message}</p>;
  }
  if (user.status === "loading") return <p>Connecting…</p>;
  if (user.status === "error") return <p>{user.error.message}</p>;

  return <p>Connected to Prismatic as {user.data.email}</p>;
}

If the session doesn't connect, check that the Prismatic URL matches the region or domain where your organization lives, and that your backend signs the token as described in Authenticating embedded users.

Next steps​