Designer API

Configuring your 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.

$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

FileDescription
/src/index.tsThe entry point for your extension’s logic. Write your TypeScript code here to interact with the Designer APIs.
/public/index.htmlThe main HTML file for your extension’s interface. This file should only contain the contents of the <body> tag.
/public/index.jsThe compiled JavaScript output from /src/index.ts. This file is automatically generated.
/public/styles.cssThe CSS file for styling your extension.
webflow.jsonThe 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:

namestringRequired

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

apiVersionstringOptional

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

sizestringOptional

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.

publicDirstringOptional

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

appIntentsstringOptional

Defines the element types that can create connections to your App. See the documentation on App Intents for more details.

appConnectionsstringOptional

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.

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.

If you used webflow extension init, you can run:

$npm run build

Otherwise, use the CLI command:

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