Headless SDK (Solis) Overview
Solis is Prismatic's headless SDK for building rich configuration experiences. With Solis, your app presents the integration marketplace and configures integrations with its own UI components: field mappers with live previews, multi-step setup flows, inline validation, and anything else your design system supports. Nothing your customers see is an iframe: your app renders every card, form, and button, and Solis supplies the data and actions behind them.
Solis has two packages:
| Package | Use it when |
|---|---|
@prismatic-io/solis-react | Your app uses React. Hooks return live, cached resources, and update your components when data changes. |
@prismatic-io/solis-core | Your app uses another framework, or none. It's the client solis-react is built on. |
Headless or hosted?
Solis renders nothing; your app does.
The hosted embedded SDK, @prismatic-io/embedded, instead displays Prismatic's screens in iframes.
For a comparison of the two, see Choosing headless or hosted.
You can use both.
Solis includes HostedConfiguration, which opens Prismatic's config wizard for integrations that use config pages.
How it works
Solis boots a hidden Prismatic iframe in your page and talks to it over a private message channel. Your app never calls Prismatic's API directly, and the frame never renders anything.
- Your backend signs a JWT for the signed-in user, exactly as it does for the embedded SDK. See Authenticating embedded users.
- Your app passes the token and your Prismatic URL to Solis.
- Solis returns resources: the marketplace, instances, configurations, and connections.
Each resource is
loading,error, orsuccesswith its data, and stays up to date as things change. - Your app changes things with actions on those resources, such as
createInstance,init,save, anddeploy. Each action resolves to a result,successorerror, and never throws. - Each guarded action has a matching permission that says whether the user may run it, and why not.
What you can build
- A marketplace: list integrations, with search, categories, and labels, and activate one for the customer.
- A configuration experience: render your own form for a headless configuration, call the integration's server functions, then save and deploy.
- Instance management: show each instance's status, offer updates, and pause, resume, or remove instances.
- Connection management: list the customer's connections and authorize OAuth 2.0 connections.
See it in action
The example embedded app includes three pages built with solis-react:
| Page | What it shows | Code | Guide |
|---|---|---|---|
| Headless Configuration | A marketplace built with the app's own cards, your forms for headless integrations, and Prismatic's wizard for others | headless-configuration.tsx | Build a custom marketplace |
| One-Click Connect | A list of integrations that each authorize, configure, and deploy in one click | headless-one-click-list.tsx | Build a one-click connect list |
| Presentation Modes | One configuration presented as a single page or a multi-step wizard | headless-presentation-modes.tsx | Configuration Presentation Modes |