Today, we are thrilled to release a beta of Cloudflare Pages support for build caching! With build caching, we are offering a supercharged Pages experience by helping you cache parts of your project to save time on subsequent builds.

For developers, time is not just money – it’s innovation and progress. When every second counts in crunch time before a new launch, the “need for speed” becomes critical. With Cloudflare Pages’ built-in continuous integration and continuous deployment (CI/CD), developers count on us to drive fast. We’ve already taken great strides in making sure we’re enabling quick development iterations for our users by making solid improvements on the stability and efficiency of our build infrastructure. But we always knew there was more to our build story.

Build times can feel like a developer's equivalent of a time-out, a forced pause in the creative process—the inevitable pit stop in a high-speed formula race.

Long build times not only breaks the flow of individual developers, but it can also create a ripple effect across the team. It can slow down iterations and push back deployments. In the fast-paced world of CI/CD, these delays can drastically impact productivity and the delivery of products.

We want to empower developers to win the race, miles ahead of competition.

At its core, build caching is a mechanism that stores artifacts of a build, allowing subsequent builds to reuse these artifacts rather than recomputing them from scratch. By leveraging the cached results, build times can be significantly reduced, leading to a more efficient build process.

Previously, when you initiated a build, the Pages CI system would generate every step of the build process, even if most parts of the codebase remain unchanged between builds. This is the equivalent to changing out every single part of the car during a pit stop, irrespective of if anything needs replacing.

Build caching refines this process. Now, the Pages build system will detect if cached artifacts can be leveraged, restore the artifacts, then focus on only computing the modified sections of the code. In essence, build caching acts like an experienced pit crew, smartly skipping unnecessary steps and focusing only on what's essential to get you back in the race faster.

It boils down to two components: dependencies and build output.

The Pages build system supports dependency caching for select package managers and build output caching for select frameworks. Check out our documentation for more information on what’s currently supported and what’s coming up.

Let’s take a closer look at what exactly we are caching.

Dependencies: upon initiating a build, the Pages CI system checks for cached artifacts from previous builds. If it identifies a cache hit for dependencies, it restores from cache to speed up dependency installation.

Build output: if a cache hit for build output is identified, Pages will only build the changed assets. This approach enables the long awaited incremental builds for supported JavaScript frameworks.

Build caching is now in beta, and ready for you to test drive!

In this release, the feature will support the node-based package managers npm, yarn, pnpm, as well as Bun. We’ve also ensured compatibility with the most popular frameworks that provide native incremental building support: Gatsby.js, Next.js and Astro – and more to come!

For you as a Pages user, interacting with build caching will be seamless. If you are working with an existing project, simply navigate to your project’s settings to toggle on Build Cache.

When you push a code change and initiate a build using Pages CI, build caching will kick-start and do its magic in the background.

Have questions? Join us on our Discord Server. We will be hosting an “Ask Us Anything” session on October 2nd where you can chat live with members of our team! Your feedback on this beta is invaluable to us, so after testing out build caching, don't hesitate to share your experiences! Happy building!

With Pages, we are constantly looking for ways to improve the developer experience. One of the areas we are keen to focus on is removing any barriers to entry for our users regardless of their use case or existing set up. Pages is an all-in-one solution with an automated Continuous Integration (CI) pipeline to help you build and deploy your site with one commit to your projects’ repositories hosted on GitHub or GitLab.

However, we realize that this excluded repositories that used a source control provider that Pages didn’t yet support and required varying build complexities. Even though Pages continues to build first-class integrations – for example, we added GitLab support in November 2021 – there are numerous providers to choose from, some of which use `git` alternatives like SVN or Mercurial for their version control systems. It’s also common for larger companies to self-host their project repositories, guarded by a mix of custom authentication and/or proxy protocols.

Pages needed a solution that worked regardless of the repository’s source location and accommodate build project’s complexity. Today, we’re thrilled to announce that Pages now supports direct uploads to give you more power to build and iterate how you want and with the tools you want.

Direct uploads enable you to push your build artifacts directly to Pages, side-stepping the automatic, done-for-you CI pipeline that Pages provides for GitHub and GitLab repositories. This means that connecting a Pages project to a git repository is optional. In fact, using git or any version control system is optional!

Today, you can bring your assets directly to Pages by dragging and dropping them into our dashboard or pushing them through Wrangler CLI. You also have the power to use your own CI tool whether that’s something like GitHub Actions or CircleCI to handle your build. Taking your output directory you can bring these files directly to Pages to create a new project and all subsequent deployments after that. Every deployment will be distributed right to the Cloudflare network within seconds.

After using your preferred CI tooling outside of Pages, there are two ways to bring your pre-built assets and create a project with the direct uploads feature:

1. Use the Wrangler CLI

2. Drag and drop them into the Pages interface

With an estimated 43k weekly Wrangler downloads, you too can use it to iterate quickly on your Pages projects right through the command line. With Wrangler (now with brand-new updates!), you can both create your project and new deployments with a single command.

After Wrangler is installed and authenticated with your Cloudflare account, you can execute the following command to get your site up and running:

npx wrangler pages publish <directory>

Integration with Wrangler provides not only a great way to publish changes in a fast and consecutive manner, but also enables a seamless workflow between CI tooling for building right to Pages for deployment. Check out our tutorials on using CircleCI and GitHub Actions with Pages!

However, we realize that sometimes you just want to get your site deployed instantaneously without any additional set up or installations. In fact, getting started with Pages shouldn’t have to require extensive configuration. The drag and drop feature allows you to take your pre-built assets and virtually drag them onto the Pages UI. With either a zip file or a single folder of assets, you can watch your project deploy in just a few short seconds straight to the 270+ cities in our network.

With this ease of deploying projects, the possibilities of what you can build are still endless. You can enjoy the fruits of Pages in a project created with direct uploads including but not limited to unique preview URLs, integration with Workers, Access and Web Analytics, and custom redirects/headers.

In thinking about your developer setup, direct uploads provide the flexibility to build the way you want such as:

• Designing and building your own CI workflow

• Utilizing the CI tooling of your choice

• Accommodating complex monorepo structures

• Implementing custom CI logic for your builds.

We’ll have to admit, the idea of publishing assets directly to our network came from a sister product to Pages called Workers Sites and the resemblance is striking! However, Pages affords many feature enhancements to the developer experience that show as a pain point on Workers Sites.

With Pages direct uploads, you can enjoy the freedom and flexibility of customizing your workflow that Workers Sites provides while including an interface to track and share changes and manage production/preview environments. Check out our tutorial on how to migrate over from Workers Sites.

This release immediately unlocks a broad range of use cases, allowing the most basic of projects to the most advanced to start deploying their websites to Pages today. Refer to our developer documentation for more technical details. As always, head over to the Cloudflare Developers Discord server and let us know what you think in the #direct-uploads-beta channel.

Calling all New York City developers! If you’re interested in learning more about Cloudflare Pages, join us for a series of workshops on how to build a full stack application on Thursday, May 12th. Follow along with demonstrations of using Pages alongside other products like Workers, Images and Cloudflare Gateway, and hear directly from our product managers. Register now!

Photo by Joyce Romero / Unsplash

// The simplest Service Worker: A passthrough script
addEventListener('fetch', event => {
  event.respondWith(fetch(event.request))
})

The code above is simple and sweet: when a request comes into one of Cloudflare’s data centers, passthrough to the origin server. There is absolutely no need for us to introduce any complex tooling or dependencies. Nevertheless, introduce we will! The problem is, once your script grows even just a little bit, you’ll be tempted to use JavaScript’s fancy new module system. However, in doing so, you’ll have a little bit of trouble uploading your script via our API (we only accept a single JS file).

Throughout this post, we’ll use contrived examples, shaky metaphors, and questionably accurate weather predictions to explain how to bundle your Service Worker with Webpack.

Let’s just say Webpack is a module bundler. That is, if you have code in multiple files, and you tie them together like this:

// Import the CoolSocks class from dresser.js
import { CoolSocks } from './dresser'
import { FancyShoes } from './closet'

Then you can tell webpack to follow all of those import statements to produce a single file. This is useful because Service Workers running on Cloudflare need to be a single file as well.

Remember when I said something about predicting weather? Let’s build a worker with TypeScript that responds with the current weather.

Make sure to have NodeJS installed.

# Make a new project directory
mkdir weather-worker
cd weather-worker
mkdir src dist
# Initialize project and install dependencies
npm init
npm install --save-dev \
  awesome-typescript-loader \
  typescript \
  webpack \
  webpack-cli \
  workers-preview
touch src/index.ts src/fetch-weather.ts webpack.config.js tsconfig.json

You should now have a file in your project called package.json. Add the following code to that file:

  "scripts": {
    "build": "webpack",
    "build:watch": "webpack --watch",
    "preview": "workers-preview < dist/bundle.js"
  }

Now edit the following files to match what is shown:

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "esnext",
    "lib": ["es2015", "webworker"],
    "jsx": "react",
    "noImplicitAny": true,
    "preserveConstEnums": true,
    "outDir": "./dist",
    "moduleResolution": "node"
  },
  "include": ["src/*.ts", "src/**/*.ts", "src/*.tsx", "src/**/*.tsx"]
}

const path = require('path')

module.exports = {
  entry: {
    bundle: path.join(__dirname, './src/index.ts'),
  },

  output: {
    filename: 'bundle.js',
    path: path.join(__dirname, 'dist'),
  },

  mode: process.env.NODE_ENV || 'development',

  watchOptions: {
    ignored: /node_modules|dist|\.js/g,
  },

  devtool: 'cheap-module-eval-source-map',

  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.json'],
    plugins: [],
  },

  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'awesome-typescript-loader',
      },
    ],
  },
}

For newcomers, this file will seem incredibly cryptic. All I can say is just to accept it as magic for now. You’ll eventually understand what’s going on.

A note about devtool: 'cheap-module-eval-source-map'. Specifying this type of sourcemap is fast, lightweight, and results in stacktraces much more representative of your source code. They’re not exact (yet!), but we’re getting there.

Cloudflare fiddle devtools uses source maps to point you to the correct source file. Click through to see the problematic line.

import { fetchWeather } from './fetch-weather'

addEventListener('fetch', (event: FetchEvent) => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request: Request) {
  const weather = await fetchWeather('austin')
  const body = `
    ${weather.location.city}, ${weather.location.region}<br>
    ${weather.item.condition.temp} ${weather.item.condition.text}
  `.trim()

  return new Response(body, {
    headers: { 'Content-Type': 'text/html' },
  })
}

/**
 * Fetch the current weather conditions and forecast for a particular location
 * @param location location string to fetch
 * @param unit temperature units (c or f)
 */
export async function fetchWeather(location: string, unit = 'f') {
  const url = `https://query.yahooapis.com/v1/public/yql?q=select *
  from weather.forecast
  where u='${unit}'
    AND woeid in (
      select woeid from geo.places(1)
      where text="${location}"
  )&format=json`
    .split('\n')
    .join(' ')
    // yahoo's api doesn't like spaces unless they're encoded
    .replace(/\s/g, '%20')

  const res = await fetch(url)

  if (res.status >= 400) {
    throw new Error('Bad response from server')
  }

  const result = await res.json()

  return result.query.results && result.query.results.channel
}

Now simply run:

npm run build && npm run preview

This ought to build your script and open a page very similar to:

This is great, but instead of returning the weather for every single resource request, maybe we should only return the weather on pathnames that match a particular pattern. Something like:

GET /weather/:city
GET /weather/austin
GET /weather/toronto

In that pattern, city is a variable. Anything that starts with /weather/ will match, and everything after will be our city. This shouldn’t match a path like /weather/austin/tatious. Luckily there are off-the-shelf solutions on npm to handle exactly this sort of logic.

Webpack also understands how to import npm modules into your bundle. To illustrate this, we’re going to use the fantastic path-to-regexp module.

Install and save the module:

npm install -S path-to-regexp

The path-to-regexp module converts the url path pattern /weather/:city to a regular expression. Using that regular expression, we can extract the variable city out of a pathname string. For instance, in the string ‘/weather/toronto’, the city variable is ‘toronto’. However, for the string ‘/users/123’, there is no match at all.

Let’s modify our src/index.ts file to include this new routing logic.

import * as pathToRegExp from 'path-to-regexp'
import { fetchWeather } from './fetch-weather'

type TWeatherRequestParams = { city: string }
const weatherPath = '/weather/:city'

addEventListener('fetch', (event: FetchEvent) => {
  // Create a regular expression based on the pathname of the request
  const weatherPathKeys: pathToRegExp.Key[] = []
  const weatherRegex = pathToRegExp(weatherPath, weatherPathKeys)
  const url = new URL(event.request.url)
  const result = weatherRegex.exec(url.pathname)

  // No result, return early and passthrough
  if (!Array.isArray(result)) return

  // Build the request parameters object
  const params = weatherPathKeys.reduce(
    (params, key, i) => {
      params[key.name as keyof TWeatherRequestParams] = result[i + 1]
      return params
    },
    {} as TWeatherRequestParams,
  )

  event.respondWith(handleWeatherRequest(params))
})

async function handleWeatherRequest(params: TWeatherRequestParams) {
  const weather = await fetchWeather(params.city)
  const body = `
    ${weather.location.city}, ${weather.location.region}<br>
    ${weather.item.condition.temp} ${weather.item.condition.text}
  `.trim()

  return new Response(body, {
    headers: { 'Content-Type': 'text/html' },
  })
}

Notice that after installing the module, all we have to do is import by its name on npm. This is because webpack knows to look inside of your node_modules directory to resolve import statement paths.

Run:

npm run build && npm run preview -- \
  --preview-url https://foo.bar.com/weather/austin

You should see the weather for Austin, TX displayed. Congrats!

Webpack is an incredibly robust and configurable piece of technology. It’s not just a module bundler, but rather a general static asset build system for web development. Although it was built with front-end assets in mind, it’s a perfect fit for bundling Cloudflare Service Workers.

You can view the full source of our weather script here: github.com/jrf0110/weather-workers

If you have a worker you'd like to share, or want to check out workers from other Cloudflare users, visit the “Recipe Exchange” in the Workers section of the Cloudflare Community Forum.

_{CC BY-SA 2.0 image by David Joyner}

TypeScript is JavaScript with optional types. Here’s a simple example:

// Sends some data to some analytics endpoint
function sendAnalyticsJS(data) {
  if (typeof data.type !== 'string') {
    throw new Error('The `type` property is required')
  }

  navigator.sendBeacon('/beacon', JSON.stringify(data))
}


// Results in run-time error
//    The `type` property is required
sendAnalyticsJS({ foo: 'bar' })

The JavaScript code will result in a run-time error. This is fine if the developer catches it early, but it would be better if the developer were warned as the bug was introduced. Here’s the same code written using TypeScript:

// Describe the shape of the data parameter
interface IAnalyticsData {
  // Type is required
  type: string
  // All other fields are fair game
  [propName: string]: string
}


// We don’t particularly need the data.type check here since
// the compiler will stamp out the majority of those cases.
function sendAnalytics(data: IAnalyticsData) {
  if (typeof data.type !== 'string') {
    throw new Error('The `type` property is required')
  }

  navigator.sendBeacon('/beacon', JSON.stringify(data))
}


// Results in compile-time error:
//   Argument of type '{ foo: string; }' is not assignable to
//   parameter of type 'IAnalyticsData'.
//   Property 'type' is missing in type '{ foo: string; }'.
sendAnalytics({ foo: 'bar' })

These annotations are all optional and the more you add, the more the compiler can help you. Compiling the TypeScript version results in code equivalent to the first example. The only difference is that the developer is warned about an error while writing the code.

With TypeScript, JavaScript developers are given powerful tools that aid the development of applications, large and small. Anders Hejlsberg, lead architect of C# and core dev for TypeScript, describes the language as, “JavaScript that scales.”

Using TypeScript means you can:

• Interactively explore library interfaces from your text editor

• Enjoy useful auto-completion

• Use good refactoring tools

• Navigate your codebase via the ontology that describes it (by that, I mean jumping to class and interface definitions, modules, etc. from individual instances/references)

• And most importantly to this post, generate documentation that’s tightly coupled to your codebase.

_{The screenshot above is of the generated documentation from a TypeScript project at Cloudflare.}

The amount of work required to annotate source code with JSDoc comments is comparable to adopting TypeScript annotations. However, JSDoc comments are not tightly coupled to the codebase, so when the code changes, an independent change of the JSDoc comment is also required. Contrast to TypeScript where the structure is gleaned directly from the source. Here’s a side-by-side comparison between JSDoc and TypeScript:

/**
 * A class representing a point
 * @class  Point
 */
class Point {
  /**
   * Create a point.
   * @param {number} x - The x value.
   * @param {number} y - The y value.
   */
  constructor(x, y) {
    /**
     * The x coordinate
     * @name  Point#x
     * @type {number}
     */
    this.x = x
    /**
     * The y coordinate
     * @name  Point#y
     * @type {number}
     */
    this.y = y
  }


  /**
   * Get the x value.
   * @return {number} The x value.
   */
  getX() {
    return this.x
  }


  /**
   * Get the y value.
   * @return {number} The y value.
   */
  getY() {
    return this.y
  }


  /**
   * Convert a string containing two comma-separated numbers into a point.
   * @param {string} str - The string containing two comma-separated numbers.
   * @return {Point} A Point object.
   */
  static fromString(str) {
    const args = str.split(',').map(arg => +arg)
    return new Point(args[0], args[1])
  }
}

TypeScript

/** Class representing a point. */
class Point {
  /** The x coordinate */
  public x: number
  /** The x coordinate */
  public y: number


  /**
   * Create a point.
   * @param x - The x value.
   * @param y - The y value.
   */
  constructor(x: number, y: number) {
    this.x = x
    this.y = y
  }


  /**
   * Get the x value.
   */
  getX() {
    return this.x
  }


  /**
   * Get the y value.
   */
  getY() {
    return this.y
  }

  /**
   * Convert a string containing two comma-separated numbers into a point.
   * @param str - The string containing two comma-separated numbers.
   */
  static fromString(str: string): Point {
    const args = str.split(',').map(arg => +arg)
    return new Point(args[0], args[1])
  }
}

The above code sample was taken from the JSDoc documentation and adapted for use with TypeScript.

The annotations for TypeScript are much more compact, they’re syntax-highlighted, and most importantly, if something is wrong, the compiler lets us know. Long-form descriptions of things are still made in comments, but the type information has been moved into language semantics.

The downside to adopting TypeScript is the large amount of work required to fit the build tools into your current processes. However, we won’t focus on the nitty-gritty details of build tools since the ecosystem is rapidly changing.

At Cloudflare, we use a tool called TypeDoc to help build documentation. It’s set up such that documentation-generation is on watch and will re-build on codebase changes. Anybody hacking on the project will always have up-to-date docs at localhost:3000/docs.

If you’re using TypeScript 2.x, use the following command to install TypeDoc for your project:

npm install --save-dev https://github.com/DatenMetzgerX/typedoc/tarball/typescript-2-build

Otherwise, for prior versions of TypeScript, you can install straight from

npm install --save-dev typedoc

From within your project directory, run the following command:

# Change the --out flag to wherever you’d like the output to be stored
./node_modules/.bin/typedoc --out dist/docs --mode modules .

You should see a bunch of HTML documents generated. One for each class and module.

dist/docs
├── assets
│   ├── css
│   │   ├── main.css
│   │   └── main.css.map
│   ├── images
│   │   ├── icons.png
│   │   ├── icons@2x.png
│   │   ├── widgets.png
│   │   └── widgets@2x.png
│   └── js
│       ├── main.js
│       └── search.js
├── classes
│   ├── _src_my_class.html
│   └── ...
├── globals.html
├── index.html
├── interfaces
│   ├── _src.my_interface.html
└── modules
    ├── _src_my_module_.html
    └── ...

I wanted to build something akin to Lodash’s documentation (a beautiful single page API reference with examples and links to source code). Luckily, you can use TypeDoc’s --json flag to produce a set of useful descriptions of your codebase in JSON format.

./node_modules/.bin/typedoc --json dist/docs.json --mode modules

Note: In order to use the --json flag, you’ll need to setup a proper tsconfig.json for your TypeScript project.

With this high-level, structured description of our code base, we can render any HTML we’d like with a few scripts and a templating language like Handlebars. Here’s a simple script to render a list of code base modules:

const fs = require('fs')
const hbs = require('handlebars')
const project = require('./dist/docs.json')


// The HTML template to use for our simple docs
const tmpl = `
<!DOCTYPE HTML>
<html>
  <head>
    <title>My Project Documentation</title>
  </head>
  <body>
    <h1>Modules</h1>
    <ul>
    {{#each project.children}}
      <li>{{this.name}}</li>
    {{/each}}
    </ul>
  </body>
</html>
`


// Compile the template with handlebars using our project
// object as context key
const result = hbs.compile(tmpl)({ project })


fs.writeFileSync('dist/docs.html', result)

While this means that there is a lot of work up front to create a template that suits the needs of this particular code base, I hope to use the same infrastructure for TypeScript projects at Cloudflare moving forward.

TypeDoc gets us halfway there. It provides a structured and automated way to create reference material that is always in sync with our codebase; but we can do more than reference material. Suppose you’re writing a getting-started.md file. You might say something like this:

To get started, call the `viewer.init()` method.

Since we’re using TypeDoc and Handlebars, we can assume we have all the information necessary to actually link to the source code. That might look something like this:

{{!-- Pull the AMPViewer class into scope --}}
{{#Class "AMPViewer"}}
{{!-- Pull the init member from AMPViewer into scope --}}
{{#Member "init"}}
{{!-- Link viewer.init(...) to its location in the source code --}}
{{!-- Also, if the function signature of the .init() method ever changes, --}}
{{!-- it will be reflected here --}}
To get started, call the
`viewer.[init({{> signature signature=signatures.0}})]({{getSourceURL this.sources.0}})`
{{/Member}}
{{/Class}}

While the above looks arcane, it’s just Markdown and Handlebars. The template contains a block helper called Class that will pull the AMPViewer class object into the current scope. Then using the AMPViewer class, we pull the init member into the current scope. We use the {{> signature}} partial to pretty-print the function’s signature and the getSourceUrl helper to link to this method in the source code.

If the source code changes, our docs update too.

Over next couple of months, we’ll be open sourcing the tools we’ve created to generate our documentation. We’ll also open source the theme shown in this post so you can generate docs without worrying about the styling. We hope to create a rich TypeScript ecosystem and to have fantastic documentation for all of our projects.

If you’re thinking of generating documentation by annotating your source, use TypeScript instead and enjoy the benefits.