# 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 <code>webflow extension init</code> 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:

<div id="app-settings-parameters">
  <div id="/data/reference/custom-code/custom-code/register-hosted#request.body.hostedLocation" class="scroll-mt-content-padded fern-api-property">
    <div class="fern-api-property-header">
      <span class="fern-api-property-key" data-state="closed">
        name
      </span>

      <span class="fern-api-property-meta">
        <span>string</span>

        <span class="t-danger">Required</span>
      </span>
    </div>

    <div class="prose dark:prose-invert max-w-none break-words prose-sm dark:prose-invert-sm">
      <p>Specifies the name of the Webflow App. It should be a descriptive and unique name that helps identify the app.</p>
    </div>
  </div>

  <div id="/data/reference/custom-code/custom-code/register-hosted#request.body.hostedLocation" class="scroll-mt-content-padded fern-api-property">
    <div class="fern-api-property-header">
      <span class="fern-api-property-key" data-state="closed">
        apiVersion
      </span>

      <span class="fern-api-property-meta">
        <span>string</span>

        <span>Optional</span>
      </span>
    </div>

    <div class="prose dark:prose-invert max-w-none break-words prose-sm dark:prose-invert-sm">
      <p>The version of the Designer APIs your app is using. It's highly recommended to set this value to `"2"`</p>
    </div>
  </div>

  <div id="/data/reference/custom-code/custom-code/register-hosted#request.body.hostedLocation" class="scroll-mt-content-padded fern-api-property">
    <div class="fern-api-property-header">
      <span class="fern-api-property-key" data-state="closed">
        size
      </span>

      <span class="fern-api-property-meta">
        <span>string</span>

        <span>Optional</span>
      </span>
    </div>

    <div class="prose dark:prose-invert max-w-none break-words prose-sm dark:prose-invert-sm">
      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).
    </div>
  </div>

  <div id="/data/reference/custom-code/custom-code/register-hosted#request.body.hostedLocation" class="scroll-mt-content-padded fern-api-property">
    <div class="fern-api-property-header">
      <span class="fern-api-property-key" data-state="closed">
        publicDir
      </span>

      <span class="fern-api-property-meta">
        <span>string</span>

        <span>Optional</span>
      </span>
    </div>

    <div class="prose dark:prose-invert max-w-none break-words prose-sm dark:prose-invert-sm">
      Determines the directory to build and serve the app from. If not declared, it defaults to `/public`.
    </div>
  </div>

  <div id="/data/reference/custom-code/custom-code/register-hosted#request.body.hostedLocation" class="scroll-mt-content-padded fern-api-property">
    <div class="fern-api-property-header">
      <span class="fern-api-property-key" data-state="closed">
        appIntents
      </span>

      <span class="fern-api-property-meta">
        <span>string</span>

        <span>Optional</span>
      </span>
    </div>

    <div class="prose dark:prose-invert max-w-none break-words prose-sm dark:prose-invert-sm">
      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)
    </div>
  </div>

  <div id="/data/reference/custom-code/custom-code/register-hosted#request.body.hostedLocation" class="scroll-mt-content-padded fern-api-property">
    <div class="fern-api-property-header">
      <span class="fern-api-property-key" data-state="closed">
        appConnections
      </span>

      <span class="fern-api-property-meta">
        <span>string</span>

        <span>Optional</span>
      </span>
    </div>

    <div class="prose dark:prose-invert max-w-none break-words prose-sm dark:prose-invert-sm">
      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)
    </div>
  </div>
</div>

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

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

<Note title="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.
</Note>