Setting Up Cloudflare Pages for Convex Preview Deployments

This article was originally published on Convex Stack.

At ClarityText we've been leveraging Cloudflare Pages to streamline the development and testing process for our application, Language Hopper. Cloudflare Pages has become an indispensable tool for us, particularly for its ability to create preview deployments for every branch pushed to our repository. This feature allows us to test changes in isolation before merging them into the main branch, ensuring a smooth and error-free deployment process.

Why We Chose Cloudflare Pages for Test Deployments

Before adopting Cloudflare Pages, we faced challenges in managing multiple environments for testing and production. Cloudflare Pages solved this problem by providing:

Preview Deployments: Every branch pushed to our repository automatically generates a unique preview URL, allowing us to test changes in a live environment without affecting the main site.

  1. Seamless Git Integration: Cloudflare Pages integrates effortlessly with GitHub, GitLab, and other Git providers, making it easy to automate builds and deployments.

  2. Edge Network Performance: By deploying on Cloudflare's global edge network, Language Hopper benefits from faster load times and improved reliability.

  3. Node.js Compatibility: With built-in support for Node.js, we can run server-side logic and APIs directly on the edge, reducing latency and improving user experience.

  4. Convenient Collaboration: Send a preview URL to anyone/everyone without Vercel's manual authorizations.

These features have made Cloudflare Pages an essential part of our development workflow.

Prerequisites

Before setting up Cloudflare Pages for your project, ensure you have the following:

  1. A Cloudflare account
  2. A Git repository (e.g., GitHub, GitLab) with your project
  3. Node.js and npm installed locally
  4. A basic understanding of Git and command-line tools

Step 1: Onboarding Process

One of the key aspects of using Cloudflare Pages effectively is ensuring that your team members have the right access and permissions to manage deployments.

Creating a Cloudflare Account

If you or your team members don't already have a Cloudflare account, follow these steps to create one:

  1. Go to the Cloudflare website
  2. Click on the Sign Up button in the top-right corner
  3. Enter your email address and create a password
  4. Verify your email address by clicking the link sent to your inbox
  5. Once verified, log in to your Cloudflare account

Inviting Team Members

After setting up your account, you'll need to invite your team members to collaborate on the project:

  1. Log in to your Cloudflare account and navigate to the Members section under your account settings
  2. Click on Invite Members
  3. Enter the email addresses of the team members you want to invite
  4. Assign the appropriate role (for team members who will be managing deployments, select the Admin role)
  5. Click Send Invite

Your team members will receive an email invitation to join your Cloudflare account. Once they accept the invitation, they'll have the necessary permissions to proceed with the deployment process.

Assigning Roles and Permissions

Cloudflare offers several roles with varying levels of access:

  • Admin: Full access to all features, including billing, account settings, and deployments
  • Super Admin: Similar to Admin but with additional permissions for managing other members
  • Billing: Access to billing information only
  • Read-Only: View-only access to account settings and deployments

For most team members involved in the deployment process, the Admin role is sufficient.

Step 2: Add the Build Script

Cloudflare Pages requires a build script to generate the static files for your site. For Next.js applications, we use the @cloudflare/next-on-pages package to ensure compatibility with Cloudflare's edge runtime. Add the following line under the "scripts" section of your package.json file:

"scripts": {
  "build": "next build",
  "pages:build": "npx @cloudflare/next-on-pages"
}

This script will build your Next.js application in a format that's optimized for Cloudflare Pages.

Step 3: Create the Configuration File

Cloudflare Pages uses a _worker.js file or a wrangler.toml configuration file to define how your application should be deployed. Create a wrangler.toml file in the root of your project and add the following configuration:

name = "your-project-name"
compatibility_flags = ["nodejs_compat_v2"]
main = "./.vercel/output/static/_worker.js"

[site]
bucket = "./.vercel/output/static"

Here's what each line does:

  • name: replace "your-project-name" with the name of your project
  • compatibility_flags: This enables Node.js compatibility
  • main: specifies the entry point for your worker
  • site.bucket: defines the directory for static assets

Step 4: Connect Your Git Repository to Cloudflare Pages

  1. Log in to your Cloudflare account and navigate to Pages
  2. Click Create a Project and select your Git provider (e.g., GitHub, GitLab)
  3. Choose the repository you want to deploy
  4. In the setup and builds configuration:
    • Add npx @cloudflare/next-on-pages@1 as the build command
    • Set .vercel/output/static as the build output directory
  5. Add any environment variables needed for build time (for both Production and Preview environments)
  6. Click Save and Deploy

This is an important detail: For those familiar with deploying a Convex deployment on Vercel, you may be aware about overriding the build command in the Vercel configuration to something like: npx convex deploy --cmd 'npm run build'. For our Language Hopper testing, we don't override the build command with this npx convex deploy command.

Step 5: Enable Node.js Compatibility

After connecting your repository, you'll need to enable Node.js compatibility for both production and preview deployments:

  1. Go to your project's settings in Cloudflare Pages
  2. Under Bindings, locate the Compatibility flags section and add nodejs_compat_v2 or nodejs_compat flag

As of September 2024, the nodejs_compat compatibility flag enables the exact same behavior as the nodejs_compat_v2 compatibility flag, as long as your compatibility date is set to September 2024 or later.

Step 6: Test Your Deployment

Once your main branch is deployed, Cloudflare Pages will automatically create a production deployment. Any new branches you push will generate preview deployments, allowing you to test changes before merging them into the main branch.

To test your deployment:

  1. Push a new branch to your repository
  2. Cloudflare Pages will automatically build and deploy the branch
  3. Visit the preview URL provided in the Cloudflare Pages dashboard to verify your changes

Troubleshooting Common Issues

While Cloudflare Pages is relatively easy to use, you may encounter some challenges during setup. Here are a few common issues and how to resolve them:

  1. Build Failures: Check the build logs in the Cloudflare Pages dashboard if your build fails. Common causes include missing dependencies or incorrect build commands.

  2. Node.js Compatibility Errors: If your application relies on Node.js APIs that aren't supported, you may need to adjust your code or use polyfills.

  3. Asset Loading Issues: Ensure your static assets are correctly configured in the wrangler.toml file. Double-check the assets directory and binding settings.

Conclusion

Setting up a website on Cloudflare Pages is straightforward, especially when using npm as your package manager. By following the steps outlined in this article, you can configure Node.js compatibility, automate builds, and leverage preview deployments to streamline your development workflow.

For us at ClarityText, Cloudflare Pages has been a game-changer, enabling us to test and deploy updates with confidence. We hope this guide helps you achieve the same level of efficiency and reliability in your projects.

Happy deploying! 🚀