Solis Overview
Solis is Prismatic's custom UI 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 draws 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. |
Solis is in early access.
Prismatic publishes its packages under the preview npm tag, and their APIs may change before a stable release.
Install them with @preview, for example npm install @prismatic-io/solis-react@preview.
Solis or the embedded SDK?
Prismatic's embedded SDK, @prismatic-io/embedded, renders Prismatic's screens in iframes: the marketplace, the config wizard, the dashboard, and more.
Solis renders nothing; your app does.
| Topic | Embedded SDK (@prismatic-io/embedded) | Solis (@prismatic-io/solis-*) |
|---|---|---|
| UI | Prismatic's screens in an iframe, styled with theming | Your app's own components |
| Configuration | Hosted config wizards | Headless configurations, plus hosted wizards when you need them |
| Data | GraphQL requests you write | Typed resources and actions |
| Effort | Low | Higher: you build and maintain the UI |
Choose the embedded SDK when Prismatic's screens, themed to match your app, are enough. Choose Solis when you want a rich configuration experience that's native to your app, or when your integrations use headless configuration.
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 draws 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 a Headless Configuration page built with solis-react.
It lists the marketplace, activates the Fake CRM integration, and configures it with a two-step field mapper and a live preview.
The page's code is in headless-configuration.tsx.