Get started with the Integration UI

This page will help you get started with creating an integration that uses the Integration UI. It describes how to generate the boilerplate code for the Integration UI, what the required files and basic scaffolding are, and how to preview your UI with the Netlify SDK utility tools.

Prerequisites

Windows users should run the Netlify SDK through WSL 2

Support for using the Netlify SDK on Windows is currently only available through WSL 2.

Create your Integration UI

To get started, run the following command to create a new integration:
```
npm create @netlify/sdk@latest
```
Then, follow the prompts to add the Integration UI boilerplate.

The Netlify SDK will scaffold the basic structure needed for the Integration UI which includes the following required file:
```
├── src
| ├── ui
│ │ └── index.ts
```
The src/ui/index.ts file in your integration directory exports an integrationUI that the Netlify SDK utility tools detect and build.
src/ui/index.ts
```
import { NetlifyIntegrationUI } from "@netlify/sdk";

const integrationUI = new NetlifyIntegrationUI("ABC Integration");

export { integrationUI };
```
Inside the src/ui/index.ts file, add a surface with integrationUI.addSurface and a route with surface.addRoute.
src/ui/index.ts
```
import { NetlifyIntegrationUI } from "@netlify/sdk";

const integrationUI = new NetlifyIntegrationUI("ABC Integration");
const surface = integrationUI.addSurface("integrations-settings");
const route = surface.addRoute("/");

export { integrationUI };
```
Currently we support only one surface: integrations-settings.

We support multiple routes on this surface. However, to get started, we recommend setting up just one route of /.

Develop your integration UI

Add elements to include different types of context and interactions in your integration’s UI.
Make the UI reactive if interactions with one element should affect other elements.
Call API Handlers from your integration’s UI to interact with the Integration API or Netlify API. This is how you can make changes to a user’s site, team, or integration configuration based on user actions in your integration’s UI.
Add more routes and navigate between integration routes if you want your integration’s UI to have multiple pages.

Develop locally

To develop your UI locally, use the Netlify SDK utility tools to run a local server. This will allow you to test your UI in action as you make changes to it.

To start the local server, run the following Netlify SDK utility tools command:
- pnpm
- yarn
- npm
pnpm run preview
yarn preview
npm run preview
This provides you with a URL to access the local development server: https://app.netlify.com/ui/preview/your-integration?server=http://localhost:8899.

If you have linked your integration to a site, your URL will look like this: https://app.netlify.com/ui/preview/your-integration?token=A_UNIQUE_TOKEN.

Please note, if you are using Safari as your web browser, you will need to link your integration to a site to preview your UI.
Visit the provided URL and select a context to test your integration in.
Select Open Preview to check out your UI in action.
As you make changes to your integration UI code, select Refresh preview to check your updates.

Next steps

Learn how to publish your integration when you’re ready to share it with users.