Do not index
I’ve been exploring Webflow apps at Lunch Pail Labs and in this article, I’m diving deep into a starter for Webflow hybrid apps. Drawing from Webflow's excellent hybrid app example, I slimmed it into a more generalized version for kickstarting a variety of hybrid apps.
The starter is currently spartan and incorporates some adaptable elements from Webflow’s original example, such as Webflow authentication, user login functionality, redirects, and API access. So with that said, let's dive in!
Initial setup
Ensure you have the following:
- Node.js (version 18.17+): This starter requires a newer version of Node than Webflow apps typically require due to its reliance on Next.js.
- A test-ready Webflow site.
- A Webflow app. For setup instructions, see Step 1 of this tutorial.
- Ngrok or a similar URL forwarding service for development. For setup details, consult Step 3 of this tutorial.
To get this set up:
- Clone the repository using the following command in your terminal:
git clone https://github.com/lunchpaillola/webflow-hybrid-app-starter.git- Navigate to the project directory and install dependencies
cd webflow-hybrid-app-starter
npm install- Install the necessary packages in the data-client directory
// Navigate to /data-client and install dependencies
cd data-client
npm install- Install the necessary packages in the designer-extension directory
// Navigate to /designer-extension and install dependencies
cd ../designer-extension
npm install- Copy the
.env.examplefile to.env.localin both thedata-clientanddesigner-extensiondirectories. Update the environment variables with your CLIENT_ID, CLIENT_SECRET, and backend URL.
That’s all for setup.
How does it work?
When users visit your app’s URL, they are greeted with a Webflow login modal. This allows them to authorize the integration with an app on their site. This login functionality is implemented in the
page.js file, located within the \login folder of the \data-client directory (link to page.js file)
Users proceed to the authorization step. This process is managed in the
webflow-redirect file located in the \data-client directory (link to webflow-redirect.jsx ).
After authorization, users can choose to copy their token. In a regular browsing session, the token will automatically be set, eliminating the need for manual copying. However, if users are in incognito mode, they'll have the option to copy and save their token for later use. This process is handled by
page.js in the /data-client directory (link to page.js file).
Within the Webflow editor, users can launch and use the application through Webflow's designer interface. The main code for this extension is located in
page.tsx within the /designer-extension directory. (link to page.tsx file)
The next section delves deeper into the project structure and highlights key files to customize
Project structure
This starter embodies a hybrid app structure, combining a designer extension and a data client.
The table below details the key files in the root directory.
Name | Purpose |
package.json | Holds project metadata and manages the list of dependencies and scripts. |
data-client | Contains backend logic interfacing with Webflow's API and other services. |
designer-extension | Holds the files for a browser extension to enhance the Webflow design experience. |
Data client directory
This directory serves as the backend hub, handling user authorization and interactions with Webflow's REST APIs and other external APIs.
The table below outlines the critical files within the
data-client directory. While you might need to modify several files, prioritize the ones marked with a ✎ pencil icon for app customization.File | Purpose |
✎ .env.example | Contains environment variable templates and sample values for initial setup. |
✎ /components | Holds components for the app |
✎ /app | The main area for application building, including login and API routes. |
/utils | Stores utility scripts such as webflow_helper.js for Webflow authorization. Add additional utilities here as required. |
package.json | Holds project metadata and manages the list of dependencies and scripts. |
middleware.js | Retrieves an access token from Webflow; redirects to log in if missing. |
/public | Stores logos and other public-facing assets. |
The
/app directory is where the bulk of customization happens, from altering styles to modifying functionality or adding new API routes.Name | Purpose |
✎ globals.css | Modify the data client’s styling here. |
✎ page.js | Customizes the startup view for logged-in users. |
✎ /webflow_redirect | Manages the redirection to Webflow. |
✎ /login | Customizes the startup view and branding/styling for logged-out users. |
✎ /api | Handles interactions with third-party apps and Webflow's REST APIs. |
layout.js | Sets the globally shared UI within the data client |
Designer extension directory
The designer extension serves as the user interface for the Webflow app within Webflow, establishing the link with Webflow's designer APIs.
The table below details the key files in the designer extension directory. While you might need to modify several files, prioritize the ones marked with a ✎ pencil icon for app customization.
Name | Purpose |
✎ webflow.json | Defines your extension metadata and sets the display size options: default, comfortable, and large. |
✎ /src/app | The core of the extension where components, icons, and single-page app logic are unified. |
✎ .env.example | Contains environment variable templates and sample values for the initial setup. |
package.json | Holds project metadata and manages the list of dependencies and scripts. |
/public | Stores logos and other public-facing assets. |
The
/src/app directory is where you'll build the core logic for the single-page application within the extension. Users see and interact with the page.tsx, making it the central file for the extension's user interfaceName | Purpose |
✎ page.tsx | Customizes the extension's interface and functionality. |
✎ /types | Stores any necessary types for files in the /designer-extension |
✎ /components | Hosts components useful for organizing and managing distinct screens in the page.tsx |
globals.css | Modify the designer extensions styling here. |
/icons | Contains all the icon assets for the extension. |
layout.tsx | Sets the globally shared UI within the extension |
This starter is just the beginning – it's a living project that will evolve with new utilities and app UI components for Webflow. If there's something specific you're looking to include or if you have any ideas, I'd be thrilled to hear from you! Don't hesitate to drop a line at hey@lunchpaillabs.com.
.png?table=block&id=9ba33ac6-8e12-48f6-b980-4333b612ec56&cache=v2)