This guide will walk you through the setup of a basic Designer Extension that will replace the text of an element with "Lorem Ipsum." By the end of this guide, you'll have completed the following steps:

• Install the Webflow CLI
• Initialize a Designer Extension starter project
• Run an Designer Extension in the Webflow Designer
• Update Elements on a page
• Modify Designer Extension with the Designer APIs

Prerequisites

To successfully follow along with this guide, please ensure your system meets the following requirements and you have the following resources:

• Node.js 16.20 or later
• A Webflow site for development and testing
• A registered Webflow App that's installed to your test site. If you haven't set up an App yet, please follow our guide on creating an App.

Step 1: Install the Webflow CLI

To build your Designer Extension locally, you’ll first need to download Webflow’s developer tools from NPM.

Open your terminal, and navigate to the folder where you’d like to create your App. Once you’re in your preferred folder, type the following command to download the CLI.

npm i @webflow/webflow-cli -g

Step 2: Initialize and configure your project

Webflow provides a basic HTML and CSS scaffold to get you started with building your extension. It's designed to be easy to understand and modify, so you can quickly start building your own Designer Extension from this foundation.

Initialization

We strongly recommend using the init command to create the correct folder structure and initial files for an Designer Extension, which provides an example app that updates any selected text on a page with "Lorem Ipsum."

Decide a name for your App, then run the following command:

webflow extension init <your_app_name>

The structure of your new project folder should resemble the example below. The public directory contains all the files to serve your designer extension. Additionally, src/index.ts allows you to use TypeScript, which will automatically compile in the public/index.js file to serve in the browser.

To learn more about the structure of a Designer Extension, refer to the documentation.

my_example_extension/
├── node_modules/
├── public/
│   ├── index.html
│   ├── index.js
│   └── styles.css
├── src/
│   └── index.ts
├── package-lock.json
├── package.json
├── webflow.json
├── README.md
└── tsconfig.json

Configure App Settings

To adjust your App settings, find and update your webflow.json file with the following information. This will update your App Settings to use the latest version of the Designer APIs, and set your extension size. Read more about managing your App settings in this guide.

{  
  "name": "my-amazing-extension",
  "size": "default",
  "apiVersion": "2"
}

Step 3. Run your App

Let’s take our App for a whirl in our browser. To do that, we can spin up a local server and access our development App on a Webflow site.

1. Make sure you’re in the folder with your Designer Extension code, and run the following command.

npm run dev

2. Confirm that your extension is running on the default port 1337, or whichever port you've selected.
3. To see the App running (locally) in Webflow:
   1. Ensure your app in installed to your test site
   2. Open your test site in the Webflow designer,
   3. Click on the apps icon in the left panel.
   4. Locate and click on your App to open its detail pane
   5. Click on “Launch development app”

Step 4: Update an element on a page

The starter App modifies the text of a selected element, and replaces the text with "Lorem Ipsum...". To see this in action select an element on the page, and click the "Lorem Ipsum" button.

Wow! Your app just updated the Webflow canvas. 🎊

Step 5: Review and modify index.ts

Let's explore how to interact with the Webflow APIs in index.ts.

Review index.ts

You'll see that index.ts contains an event handler, to handle the submission of a form with the id of "lorem" in index.html. The function prevents the default behavior of a form submission, which would reload the page, and instead looks for the selected element.

If a selected element is found, and the element's properties allow it to have text content, the function will add or replace any existing text with "Lorem ipsum..."

document.getElementById("lorem").onsubmit = async (event) => {
  
  // Prevent the default form submission behavior, which would reload the page
  event.preventDefault()
  
  // Get the currently selected element in the Designer
  const el = await webflow.getSelectedElement()
  
  // Check if an element was returned, and the element can contain text content
  if (el && el.textContent) {
    
    // If we found the element and it has the ability to update the text content,
    // replace it with some placeholder text
    el.setTextContent(
      "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do " +
      "eiusmod tempor incididunt ut labore et dolore magna aliqua."
    )
  }
}

Modify index.ts

Currently, there isn't any logic to handle a scenario where an element isn't selected, or an element doesn't have text content. Let's change that.

After the if statement, let's add an else clause to notify a user that they should choose an element. Using webflow.notify() will create a small notification in the top right corner of the Designer, alerting a user.

} else {

    await webflow.notify({type: 'Error', message: "Please select an element that contains text."})

  }

Save the changes to your index.ts, and try selecting a non-text element to see the notification.

🎊 Voila! You've created and tailored an app to run in Webflow. 🎊