Working with the CMS

1. Clone the starter code.
   Run the following commands in your IDE to clone the example repository and install dependencies:
   Shell

   
   # Clone the example repository
   git clone https://github.com/Webflow-Examples/cms-examples.git
   cd webflow-example
   
   # Install dependencies
   npm install
             

2. Add Environment Variables
   Add your credentials to the .env file. If you’re using an App, input your App’s CLIENT_ID and CLIENT_SECRET. If using a Site Token, input the token as SITE_TOKEN.
3. Add Ngrok Auth Token
   Ngrok is required because Webflow Apps must run on https:// URLs, and Ngrok provides a secure tunnel for your local server.
   
   Get your Ngrok auth token from the Ngrok dashboard. Then, add your token to your environment variables.
   Shell

   
   export NGROK_AUTH_TOKEN=your-ngrok-auth-token
             

4. Review Project
   In this example, our focus will be on the backend folder. Within this folder, you'll find:
   • server.js: The main server file that sets up and runs our Express server.
   • webflowClientMiddleware.js: Contains the middleware for initializing the Webflow client.
   • routes: Includes various routes for interacting with the Webflow CMS.
   • controllers: Defines the logic for API calls.

📘

Quickstart 🚀

Want to see the demo in action? Run the following command to start your server and follow the instructions in the terminal.

npm start

👇 Keep going to dive deeper into the specifics of how to interact with the Webflow CMS API, set up middleware, and define routes and controllers.

To authenticate all of our API calls to Webflow, we'll need to initialize and authenticate the WebflowClient provided by the Webflow JavaScript SDK. To efficiently manage this for multiple requests, we’ll create middleware for our Express server, which will handle initialization of the WebflowClient and authentication in each request.

📘

Authentication

We’ve already taken care of the OAuth Handshake in authRoutes.js. To learn more about authorization and authentication for your app, read the guide.

1. Define Imports
   First, we'll import the necessary modules. The WebflowClient will be imported from the Webflow SDK, and the getToken function will be imported from our tokens.js utility. The getToken function handles retrieving an authentication token from our database.
   
   Add the following import statements at the top of your webflowClientMiddleware.js file:
webflowClientMiddleware.js

import WebflowClient from 'webflow-api';
import getToken from './tokens.js';

2. Build Middleware Function
   Next, we'll create the middleware function. This function will be an asynchronous function that retrieves the access token, initializes the Webflow client, and attaches it to the request object. It will also handle errors and send appropriate responses if something goes wrong.
   
   
   1. Retrieve Access Token
      Within the middleware function, the first step is to retrieve the access token for the user. This is done using the getToken function. If the token is not found, an error is logged, and a 401 Unauthorized response is sent.
   2. Initialize Webflow Client
      Once we have the access token, we'll initialize the Webflow client using the WebflowClient constructor and attach it to the req object. This ensures that the client is available for subsequent middleware and route handlers.
   3. Export the function
      Finally, we'll export the middleware function so it can be used in other parts of the application.

import WebflowClient from 'webflow-api';
import getToken from './tokens.js';

/ Middleware function to initialize and authenticate WebflowClient
const webflowClientMiddleware = async (req, res), next => {
  try {
    // Retrieve Access Token
    const accessToken = await getToken('user');
    if (!accessToken) {
      console.log('Access token not found for user');
      return res.status(401).send('Access token not found');
    }

    // Initialize Webflow Client
    req.webflow = new WebflowClient({ accessToken });
    // console.log('Webflow client initialized');
    
    next();
  } catch (error) {
    console.error('Error initializing Webflow client:', error);
    res.status(500).send('Failed to initialize Webflow client');
  }
};

export default webflowClientMiddleware;

Let’s review how controllers and routes are structured in the project. Routes define the endpoints for your application, while controllers contain the logic for handling requests and responses.

    export const listSites = async (req, res) => {
        // Fetch sites
        const sites = await req.webflow.sites.list();
    
        // Respond with the list of sites
        res.json({ sites });
      } catch (error) {
        console.error('Error fetching sites:', error);
        res.status(500).send('Failed to fetch sites');
      }
    };
    

import express from 'express';
import { listSites } from '../controllers/sitesController.js'; // Import the listSites controller

const router = express.Router();

router.get('/', listSites); // Define the route for listing sites and link it to the listSites controller

export default router;

In this section, we'll set up routes and controllers for managing Collections in the Webflow CMS. This includes listing Collections, getting Collection details, creating Collections with fields, and deleting Collections.

Collections and Fields

{
  "id": "6487b589d27f8112c8623bcb",
  "displayName": "test2",
  "singularName": "testing123",
  "slug": "test2",
  "createdOn": "2023-06-13T00:17:13.320Z",
  "lastUpdated": "2023-06-13T00:17:13.748Z",
  "fields": [
    {
      "id": "b24f574b7ab550df74090de0f850c81d",
      "isEditable": true,
      "isRequired": true,
      "type": "PlainText",
      "slug": "name",
      "displayName": "Name",
      "helpText": null
    },
    {
      "id": "08abacfa7f860006c7785fb6b725b9f5",
      "isEditable": true,
      "isRequired": true,
      "type": "PlainText",
      "slug": "slug",
      "displayName": "Slug",
      "helpText": null
    }
  ]
}

{
  "id": "b24f574b7ab550df74090de0f850c81d",
  "isEditable": true,
  "isRequired": true,
  "type": "PlainText",
  "slug": "name",
  "displayName": "Name",
  "helpText": null
}

1. Setup Collection Controllers

   Let's define the logic for handling the collection routes in the collectionController.js file. In this example, we’re setting up our createCollection logic to accept a preset collection with accompanying fields defined in ./utils/CollectionPresets.js. We’ll provide an example request later on in the guide.

   Create the file in your controllers folder and add the following code. We’ll export each function so they can be used in our routes.

controllers/collectionController.js

export const listCollections = async (req, res) => {

    // Fetch collections
    const collections = await req.webflow.collections.list(req.params.siteId);

    // Respond with the list of collections
    res.json({ collections });
  } catch (error) {
    console.error('Error fetching collections:', error);
    res.status(500).send('Failed to fetch collections');
  }
};

export const getCollection = async (req, res) => {
  try {

    // Fetch collection details
    const collection = await req.webflow.collections.get(req.params.collectionId);

    // Respond with the collection details
    res.json(collection);
  } catch (error) {
    console.error('Error fetching collection:', error);
    res.status(500).send('Failed to fetch collection');
  }
};

2. Setup Collection Routes

   Now that we have the controllers, let's define the routes that will use these controllers. Create a file named collectionRoutes.js in your routes folder and add the following code:

routes/collectionRoutes.js

import express from 'express';
import { 
  listCollections, 
  getCollection, 
  createCollectionWithFields, 
  deleteCollection 
} from '../controllers/collectionController.js'; // Import the controllers we just setup

const router = express.Router();

// Route to list all collections for a specific site. See listCollections controller for logic.
router.get("/:siteId", listCollections);

// Route to get details of a specific collection. See getCollection controller for logic.
router.get("/:collectionId/details", getCollection);

// Route to create a new collection with fields. See createCollectionsWithFields controller for logic.
router.post("/:siteId", createCollectionWithFields);

// Route to delete a specific collection. See deleteCollection controller for logic.
router.delete("/:collectionId", deleteCollection);

export default router;

In this section, we'll set up endpoints for managing items within a collection in the Webflow CMS. This includes fetching items, adding and updating items, and managing an item’s publish state.

Understanding Items

Items are individual entries within a collection. This section provides detailed information on how to manage these items, including creating, updating, retrieving, and deleting items. You'll also learn about the different states items can be in and how to work with various field types.

1. Setup Item Controllers

   First, let's define the logic for handling item operations in the itemsController.js file. Create the file in your controllers folder and add the following code. We’ll export each function so they can be used in our routes.

itemsController.js

// List collection items
export const listItems = async (req, res) => {
  try {
    const data = await req.webflow.collections.items.listItems(req.params.collectionId);
    res.json(data.items); // Respond with collection items
  } catch (error) {
    console.error("Error fetching collection items:", error);
    res.status(500).send("Failed to fetch collection items");
  }
};

// Create collection item
export const createItem = async (req, res) => {
  try {
    const data = await req.webflow.collections.items.createItem(req.params.collectionId, req.body);
    res.json(data); // Respond with created item
  } catch (error) {
    console.error("Error creating collection item:", error);
    res.status(500).send("Failed to create collection item");
  }
};

// Delete collection item
export const deleteItem = async (req, res) => {
  try {
    const data = await req.webflow.collections.items.deleteItem(req.params.collectionId, req.params.itemId);
    res.json(data); // Respond with deletion result
  } catch (error) {
    console.error("Error deleting item:", error);
    res.status(500).send("Failed to delete item");
  }
};

2. Setup Item Routes

   Next, define the routes that will use these controllers. Create a file named itemsRoutes.js in your routes folder and add the following code:

routes/itemsRoutes.js

import express from 'express';
import { 
  listItems, 
  createItem, 
  deleteItem 
} from '../controllers/itemsController.js'; // Import the controllers we just setup

const router = express.Router();

// Route to list all items for a specific collection. See listItems controller for logic.
router.get("/:collectionId/items", listItems);

// Route to create a new item in a specific collection. See createItem controller for logic.
router.post("/:collectionId/items", createItem);

// Route to delete a specific item from a collection. See deleteItem controller for logic.
router.delete("/:collectionId/items/:itemId", deleteItem);

export default router;

Let's set up the server to handle requests, configure middleware, define routes for interacting with the Webflow API, and tunnel through Ngrok for secure external access.

1. Import Required Modules

   Start by importing the necessary modules and middleware:

   JavaScript

   
     import express from "express";
     import cors from "cors";
     import chalk from "chalk"; // Library for styling terminal output
     import Table from "cli-table3"; // Library for styling terminal output
     import { startNgrok } from "./utils/ngrokManager.js"; // Logic for handling Ngrok
     
     // Import Webflow Client Middleware
     import webflowClientMiddleware from "./webflowClientMiddleware.js";
     
     // Import Routes
     import authRoutes from "./routes/authRoutes.js";
     import sitesRoutes from "./routes/sitesRoutes.js";
     import collectionsRoutes from "./routes/collectionRoutes.js";
     import itemRoutes from "./routes/itemRoutes.js";
     

2. Initialize Express Application

   Create an instance of the Express application and define the port:

   JavaScript

   
     const app = express();
     const PORT = process.env.PORT || 8000;
     

3. Configure Middleware

   Setup middleware for CORS, which will allow our backend to accept requests from our frontend running on a different port. Additionally, add middleware for handling JSON data sent in a request body, making it available as req.body in your request handlers.

   JavaScript

   
     app.use(
       cors({
         origin: "http://localhost:3000", // Allow only this origin to access the resources
         optionsSuccessStatus: 200, // For legacy browser support
       })
     );
     app.use(express.json());
     

4. Define Routes

   Configure the routes for authentication and accessing sites, collections, and items. Use the Webflow Client middleware for routes that need API interaction:

   JavaScript

   
     app.use("/", authRoutes);
     app.use("/api/sites", webflowClientMiddleware, sitesRoutes);
     app.use("/api/collections", webflowClientMiddleware, collectionsRoutes);
     app.use("/api/collections", webflowClientMiddleware, itemRoutes);
     

5. Start the Server with Ngrok

   Create a function to start the server and tunnel through Ngrok for external access:

   JavaScript

   
     // Start server with NGROK
     const startServer = async () => {
       try {
         // Start Ngrok
         const ngrokUrl = await startNgrok(PORT);
     
         // Create a table to output in the CLI
         const table = Table({
           head: ["Location", "URL"], // Define column headers
           colWidths: [30, 60], // Define column widths
         });
     
         // Add URL information to the table
         table.push(
           ["Development URL (Frontend)", "http://localhost:3000"],
           ["Development URL (Backend)", `http://localhost:${PORT}`]
         );
     
         // If using an App, also add the Redirect URI to the table
         if (!process.env.SITE_TOKEN) {
           table.push(["Auth Callback URL", `${ngrokUrl}/auth/callback`]);
         }
     
         // Console log the table
         console.log(table.toString());
     
         // If using an App, send a note to adjust the app's Redirect URI
         if (!process.env.SITE_TOKEN) {
           console.log(
             chalk.blue.inverse("\n\nNOTE:"),
             chalk.blue("Update your Redirect URI in your App Settings\n\n")
           );
         }
     
         // Start the server
         app.listen(PORT, () => {
           console.log(`Server is running on http://localhost:${PORT}`);
         });
       } catch (error) {
         console.error("Failed to start the server with ngrok:", error);
         process.exit(1);
       }
     };
     
     // Start the server
     startServer();
     

Now that we’ve set up the server, let’s start making requests through our frontend.

1. Start the server
   First, ensure your server is running. Use the following command to start both the frontend and backend servers, with the backend being tunneled through Ngrok:
   Shell

   npm start

2. Authenticate the App
   
   App Site Token

   1. Get the Ngrok redirect URI from the terminal.
   2. Update your app’s redirect URI in the Webflow app settings with this Ngrok redirect URI.
   3. Navigate to http://localhost:8000.
   4. You’ll be taken to a Webflow authentication screen. Add the workspaces/sites you want to authorize.
   5. After authorizing, you’ll be redirected to the frontend.

   If you’re using a Site Token, you’ll be redirected directly to the frontend.
   
   
3. Explore the CMS
   1. Choose a Site
      From the dropdown list, select one of the authorized sites you want to explore.
   2. Choose a Collection
      • Select a collection from the dropdown list to populate the item list.
      • (Optional) You can delete a collection if you wish.
   3. Create an Item
      • Fill out the form and submit it to create a new item.
      • The new item will appear in the item list.
   4. Delete an Item
      • Scroll through the item list to find the delete button.
      • Delete an item and observe the changes.
   5. Create a Collection
      1. In the modal, choose from a list of collection presets and create a collection.
      2. Return to the collection picker to see the new collection appear.
      3. (Optional) Add new items to the newly created collection.