Get started with extension UI

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

The Netlify SDK provides a React-based toolkit for building an extension UI. It assumes a basic working knowledge of React.

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.

Extension UI uses the following technical stack. It might be helpful to familiarize yourself with these tools and libraries:

Tech stack

Create your extension UI

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

The Netlify SDK will scaffold the basic structure needed for the extension UI, which includes the following files:
```
 ├── extension.yaml
 ├── src
 │   ├── ui
 │   │   ├── App.tsx
 │   │   ├── index.css
 │   │   ├── index.html
 │   │   ├── index.tsx
 │   │   └── surfaces
 │   │       └── TeamConfiguration.tsx
 ├── tailwind.config.ts
 └── vite.config.ts
```
When you build or run your extension, Vite (the default build tool) references the src/ui/index.html file in your extension directory. Vite then builds your single-page application to a directory, and the Netlify SDK uses your built application as the extension UI’s entrypoint.

The following sections provide detail on each file and the boilerplate code each one contains.

Extension UI files

When you use the SDK’s guided set-up flow, the SDK outputs the following boilerplate files. The files include a sample extension UI configured for the extension details page surface, which users will access under Extensions > [your extension’s details page] > Configuration in the Netlify UI.

`src/ui/index.tsx`

The src/ui/index.tsx file contains the root of the application that represents your extension UI:

import "./index.css";
import { createRoot } from "react-dom/client";
import { NetlifyExtensionUI } from "@netlify/sdk/ui/react/components";
import { App } from "./App.jsx";

const rootNodeId = "root";
let rootNode = document.getElementById(rootNodeId);
if (rootNode === null) {
  rootNode = document.createElement("div");
  rootNode.id = rootNodeId;
}
const root = createRoot(rootNode);

root.render(
  <NetlifyExtensionUI>
    <App />
  </NetlifyExtensionUI>,
);

This file contains the code that bootstraps the application and sets up plumbing between the Netlify UI and your application. You won’t need to modify this file frequently. However, you might add global setup here, such as a new stylesheet.

`src/ui/App.tsx`

The src/ui/App.tsx file contains application-specific logic for your extension UI:

import { Surfaces } from "@netlify/sdk/ui/react";
import { SurfaceRouter, SurfaceRoute } from "@netlify/sdk/ui/react/components";
import { TeamConfiguration } from "./surfaces/TeamConfiguration.jsx";

export const App = () => (
  <SurfaceRouter>
    <SurfaceRoute surface={Surfaces.TeamConfiguration}>
      <TeamConfiguration />
    <SurfaceRoute>
  </SurfaceRouter>
);

This component receives the current surface the end user is viewing and renders the appropriate component. This is also a good place to add any React providers your application might need.

`src/ui/surfaces/TeamConfiguration.tsx`

Inside the src/ui/surfaces/TeamConfiguration.tsx file, you’ll find sample UI for the extension details page surface:

import { Card, CardTitle, TeamConfigurationSurface } from "@netlify/sdk/ui/react/components";

export const TeamConfiguration = () => {
  return (
    <TeamConfigurationSurface>
      <Card>
        <CardTitle>Hello, World!</CardTitle>

        <p>This is my extension’s team configuration surface.</p>
      </Card>
    </TeamConfigurationSurface>
  );
};

You can add UI and logic to this page to collect team-specific configuration values.

`extension.yaml`

This is the extension configuration file and this is where you specify the surfaces that the extension contains. The Netlify UI will read this configuration file and use this to identify when to render your extension UI application.

In this case, you will find that the extension UI is configured for the extension details page surface:

config:
  ui:
    surfaces:
      - extension-team-configuration

Next steps

To preview your extension UI while you develop locally, you need to deploy and publish it as a private extension first. Learn more about how to develop locally.

For more information about all of the components and surfaces available, refer to the extension UI reference docs.

Got it!

Your feedback helps us improve our docs.

Get started with extension UI

Prerequisites

Create your extension UI

Extension UI files

src/ui/index.tsx

src/ui/App.tsx

src/ui/surfaces/TeamConfiguration.tsx

extension.yaml