> This page is for Designer API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.webflow.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.webflow.com/_mcp/server.

# Configuring your Designer Extension

> A comprehensive guide to setting up and configuring your Webflow Designer Extension.

This guide provides an overview of how to configure your Webflow Designer Extension. You'll understand the project structure, and how to customize its behavior with `webflow.json`.

## Initializing your project

We strongly recommend starting your project with the `webflow extension init` command. This will create a project foundation tailored for Designer Extensions and ensure all necessary dependencies and configurations are installed correctly.

```bash
webflow extension init <your-project-name>
```

The CLI also supports templates for specific libraries and languages like React and TypeScript. You can view available templates by running `webflow extension list`.

## Understanding the project structure

After running the `init` command, your project will have a specific file structure. The `public` folder contains all the files needed to serve your Designer Extension.

### Key files

| File                 | Description                                                                                                        |
| :------------------- | :----------------------------------------------------------------------------------------------------------------- |
| `/src/index.ts`      | The entry point for your extension's logic. Write your TypeScript code here to interact with the Designer APIs.    |
| `/public/index.html` | The main HTML file for your extension's interface. This file should only contain the contents of the `<body>` tag. |
| `/public/index.js`   | The compiled JavaScript output from `/src/index.ts`. This file is automatically generated.                         |
| `/public/styles.css` | The CSS file for styling your extension.                                                                           |
| `webflow.json`       | The manifest file used to configure your extension's settings and behavior.                                        |

### Referencing assets

When linking to CSS and JavaScript files in `index.html`, always use relative paths (e.g., `./styles.css`) instead of absolute paths (e.g., `/styles.css`). This ensures your assets are loaded correctly.

## App settings (`webflow.json`)

The `webflow.json` file is the manifest that controls your app's behavior. Here are the available properties:

name stringRequired

Specifies the name of the Webflow App. It should be a descriptive and unique name that helps identify the app.

apiVersion stringOptional

The version of the Designer APIs your app is using. It's highly recommended to set this value to `"2"`

size stringOptional

Defines the size of the Designer Extension window. Available sizes include:

* `default`: 240px by 360px
* `comfortable`: 320px by 460px
* `large`: 800px by 600px

If a size is not declared, the window defaults to `default`. You can also dynamically change the size using the `webflow.setExtensionSize()` [API](/designer/reference/resize-extension).

publicDir stringOptional

Determines the directory to build and serve the app from. If not declared, it defaults to `/public`.

appIntents stringOptional

Defines the element types that can create connections to your App. [See the documentation on App Intents for more details.](/designer/reference/app-intents-and-connections)

appConnections stringOptional

An array of unique identifiers for establishing connections between your app and elements on the canvas. [See the documentation on App Connections for more details.](/designer/reference/app-intents-and-connections)

featureFlags objectOptional

An object of boolean flags that opt the app into additional Designer Extension behaviors. Supported keys:

* `expandedAppModes`: Set to `true` to keep the app open when the user switches Designer modes. See [App Modes](/designer/reference/app-modes) for details.

**`webflow.json example`**

```json title="webflow.json example"
{
  "name": "My Webflow App",
  "apiVersion": "2",
  "size": "comfortable",
  "publicDir": "dist",
  "appIntents": {
    "image": ["manage"],
    "form": ["manage"]
  },
  "appConnections": [
    "myAppImageConnection",
    "myAppFormConnection"
  ],
  "featureFlags": {
    "expandedAppModes": true
  }
}
```

## Building and running locally

The scaffold for your extension includes a TypeScript file at `src/index.ts`. Use this file to interact with the Designer APIs.

When you're ready to test, run the `npm run build` command. This transpiles your TypeScript into JavaScript, outputting the result to `/public/index.js`. Do not modify `/public/index.js` directly, as it will be overwritten.

To run your extension locally, use the `webflow extension serve` command. This will allow you to interact with your extension within the Webflow Designer.

## Bundling for production

When you're ready to publish, you need to bundle your extension. This process compiles your code and creates a `bundle.zip` file. You can read more about how to bundle your extension in our [guide on publishing your extension](/apps/docs/publishing-your-app).

If you used `webflow extension init`, you can run:

```bash
npm run build
```

Otherwise, use the CLI command:

```bash
webflow extension bundle
```

> **Working with Frameworks**
>
> For frameworks like Next.js that generate browser-ready files, build with the framework first, then run `webflow extension bundle` on the output directory.