Creating A React App Using Keywork And ESBuild

This example repo shows how Keywork can be used to build a web app on Cloudflare Pages with your own routing.

Features

• TypeScript
• CSS imports
• Compatible with Worker Sites and Cloudflare Pages
• Server-side React rendering with streams

Structure

This project uses ESBuild to bundle your code from three separate package directories:

/packages/worker

The complete and bundled Worker code to be uploaded to Cloudflare Pages. This includes your routing logic, data fetching, React components, and server-side rendering.

Because Keywork apps automatically handle routing, ESBuild has been configured to output a _worker.js file, automatically configuring Cloudflare Pages to disable the functions directory and enable advanced mode.

This package can import from...

• NPM packages declared in /packages/worker/package.json
• @packages/shared

/packages/browser

The client-side bundle to be served statically by your Worker, and interpreted by the browser. This includes your React components, client-side hydration.

This package can import from...

• NPM packages declared in /packages/browser/package.json
• @packages/shared

/packages/shared

While this isn't a separate bundle per se, both the worker and browser bundles will import shared modules such as your React components and other shared utilities.

This package can import from...

• NPM packages declared in /packages/shared/package.json
• @packages/shared

dist

The contents of this directory will be generated by ESBuild and uploaded to Cloudflare Pages and served as your site's static content.

_worker.js

The bundled code that will be generated by ESBuild. This comprises the entirety of your deployed worker.

Getting Started

We recommend setting up the repo for local development before adding any of your own code.

Requirements

• Mac or *nix based OS
• Git
• Node v17.4 or higher (preferably via NVM)
• Yarn v1.22 or higher
• Cloudflare account

While optional, this example Keywork project is curated for VSCode with the Prettier and ESlint extensions.

Setup

You can start by forking this repo as a template, or by cloning this repo to your local machine.

git clone https://github.com/nirrius/keywork-example-react-esbuild.git

With the repo cloned to your machine, we'll need to install some dependencies using Yarn. This project is structured like a monorepo and uses Yarn Workspaces to manage the packages directory. Each package's dependencies can be installed from the root of the project with a single command:

# cd ~/your/projects/keywork-example-react-esbuild
yarn install

Local Development

Build

This project uses ESBuild to bundle our packages and static site content. And now that your dependencies are installed, we can run the build command from the root of the project:

yarn build

This command should produce a dist directory containing our static assets, and a _worker.js file:

ls ./dist
# _worker.js
#
# /static
#   /main.js
#   /main.css

Serve

Before moving on to configure Cloudflare Pages, let's first confirm that the code works locally. The yarn dev command starts our local server using a simulator called Miniflare.

yarn dev

# Serving at http://localhost:8788/

Deploy With Cloudflare Pages

Now that we've confirmed the project runs locally, we'll setup Cloudflare Pages so that a build is published each time we commit to this repo.

The Cloudflare Pages documentation offers an in-depth approach, but the following steps should get you started:

1. Create a new project

Sign into the Cloudflare Pages Dashboard and press the "Create a new project" button and "Connect To Git".

2. Configure your project

After authenticating your Github account, grant Cloudflare access to your forked keywork-example-react-esbuild. Select Install & Authorize and Begin setup. You can then customize your deployment on the Set up builds and deployments page.

Build settings

• Framework preset: (None)
• Build command: yarn build
• Build output directory: dist
• Root directory: (Leave this path value empty)
• Environment Variables:
  • NODE_VERSION: 17.4.0

3. Deploy

After you have finished setting your build configuration, select Save and Deploy. Much like the steps we performed earlier, Cloudflare Pages will follow a similar flow of cloning your repo, installing the dependencies, and building your project. However, once the build is complete, your app will be deployed to Cloudflare's global network.

When your project finishes deploying, you will then receive a unique URL to view your deployed site!

While we're done setting up your Pages deployment, additional configuration is further detailed in Cloudflare's documentation

Further reading

• Keywork Documentation
• Cloudflare Pages Documentation
• Cloudflare Workers Documentation