# 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.                    |

Early access

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?[​](#solis-or-the-embedded-sdk "Direct link to Solis or the embedded SDK?")

Prismatic's [embedded SDK](https://prismatic.io/docs/embed.md), `@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](https://prismatic.io/docs/embed/theming.md) | Your app's own components                                                                                                           |
| Configuration | [Hosted](https://prismatic.io/docs/integrations/config-wizard.md) config wizards                    | [Headless configurations](https://prismatic.io/docs/integrations/headless-configuration.md), plus hosted wizards when you need them |
| Data          | [GraphQL requests](https://prismatic.io/docs/embed/embedded-api-requests.md) 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[​](#how-it-works "Direct link to 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.

1. Your backend signs a JWT for the signed-in user, exactly as it does for the embedded SDK. See [Authenticating embedded users](https://prismatic.io/docs/get-started/embedded-marketplace/authenticate-embedded-users.md).
2. Your app passes the token and your Prismatic URL to Solis.
3. Solis returns **resources**: the marketplace, instances, configurations, and connections. Each resource is `loading`, `error`, or `success` with its data, and stays up to date as things change.
4. Your app changes things with **actions** on those resources, such as `createInstance`, `init`, `save`, and `deploy`. Each action resolves to a result, `success` or `error`, and never throws.
5. Each guarded action has a matching **permission** that says whether the user may run it, and why not.

## What you can build[​](#what-you-can-build "Direct link to 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[​](#see-it-in-action "Direct link to See it in action")

The [example embedded app](https://github.com/prismatic-io/embedded/tree/main/examples/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`](https://github.com/prismatic-io/embedded/blob/main/examples/example-embedded-app/frontend/routes/examples/headless-configuration.tsx).

## Next steps[​](#next-steps "Direct link to Next steps")

* [Build a configuration UI with Solis React](https://prismatic.io/docs/embed/headless/react.md)
* [Get started with headless configuration](https://prismatic.io/docs/get-started/build-integrations/headless-configuration.md)