@cloudflare/kv-asset-handler

What is @cloudflare/kv-asset-handler?

@cloudflare/kv-asset-handler is a package designed to help developers serve static assets from Cloudflare Workers using Cloudflare's KV (Key-Value) storage. It simplifies the process of handling requests for static assets, such as HTML, CSS, JavaScript, and images, by providing a straightforward API to fetch and serve these assets efficiently.

What are @cloudflare/kv-asset-handler's main functionalities?

Serve Static Assets

This feature allows you to serve static assets stored in Cloudflare's KV storage. The code sample demonstrates how to use the `getAssetFromKV` function to handle fetch events and return the requested asset.

const { getAssetFromKV } = require('@cloudflare/kv-asset-handler');

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event));
});

async function handleRequest(event) {
  try {
    const response = await getAssetFromKV(event);
    return response;
  } catch (e) {
    return new Response('Error fetching asset', { status: 500 });
  }
}

Custom Cache Control

This feature allows you to customize cache control settings for the assets served. The code sample shows how to set browser and edge TTL (Time To Live) values to control caching behavior.

const { getAssetFromKV, mapRequestToAsset } = require('@cloudflare/kv-asset-handler');

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event));
});

async function handleRequest(event) {
  try {
    const options = {
      cacheControl: {
        browserTTL: 60 * 60 * 24, // 1 day
        edgeTTL: 60 * 60 * 24 * 30, // 30 days
      },
    };
    const response = await getAssetFromKV(event, options);
    return response;
  } catch (e) {
    return new Response('Error fetching asset', { status: 500 });
  }
}

Custom Asset Mapping

This feature allows you to customize how requests are mapped to assets in KV storage. The code sample demonstrates how to modify the request URL to remove a '/static' prefix before fetching the asset.

const { getAssetFromKV, mapRequestToAsset } = require('@cloudflare/kv-asset-handler');

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event));
});

async function handleRequest(event) {
  try {
    const customKeyModifier = request => {
      let url = new URL(request.url);
      url.pathname = url.pathname.replace('/static', '');
      return new Request(url.toString(), request);
    };
    const response = await getAssetFromKV(event, { mapRequestToAsset: customKeyModifier });
    return response;
  } catch (e) {
    return new Response('Error fetching asset', { status: 500 });
  }
}

Other packages similar to @cloudflare/kv-asset-handler

express-static

The `express-static` middleware is used in Express.js applications to serve static files. It is similar to @cloudflare/kv-asset-handler in that it helps serve static assets, but it is designed for use with Express.js and does not integrate with Cloudflare Workers or KV storage.

serve-static

The `serve-static` package is a standalone middleware for serving static files. It is often used with Node.js servers and frameworks like Express. Unlike @cloudflare/kv-asset-handler, it does not provide integration with Cloudflare Workers or KV storage.

static-server

The `static-server` package is a simple, zero-configuration command-line HTTP server for serving static files. It is useful for local development and testing but does not offer the same level of integration with Cloudflare Workers or KV storage as @cloudflare/kv-asset-handler.

README

@cloudflare/kv-asset-handler

Installation

Add this package to your package.json by running this in the root of your project's directory:

npm i @cloudflare/kv-asset-handler

Usage

This package was designed to work with Worker Sites.

getAssetFromKV

getAssetFromKV is a function that takes a FetchEvent object and returns a Response object if the request matches an asset in KV, otherwise it will throw an Error.

Example

This example checks for the existence of a value in KV, and returns it if it's there, and returns a 404 if it is not. It also serves index.html from /.

import { getAssetFromKV } from '@cloudflare/kv-asset-handler'

addEventListener('fetch', event => {
  event.respondWith(handleEvent(event))
})

const customKeyModifier = url => {
  //custom key mapping optional
  if (url.endsWith('/')) url += 'index.html'
  return url.replace('/docs', '').replace(/^\/+/, '')
}

async function handleEvent(event) {
  if (event.request.url.includes('/docs')) {
    try {
      return await getAssetFromKV(event, { mapRequestToAsset: customKeyModifier })
    } catch (e) {
      return new Response(`"${customKeyModifier(event.request.url)}" not found`, {
        status: 404,
        statusText: 'not found',
      })
    }
  } else return fetch(event.request)
}

Optional Arguments

You can customize the behavior of getAssetFromKV by passing the following properties as an object into the second argument

getAssetFromKV(event, { mapRequestToAsset: ... })

mapRequestToAsset

type: function(Request) => Request

Maps the incoming request to the value that will be looked up in Cloudflare's KV

By default, mapRequestToAsset is set to the exported function mapRequestToAsset. This works for most static site generators, but you can customize this behavior by passing your own function as mapRequestToAsset. The function should take a Request object as its only argument, and return a new Request object with an updated path to be looked up in the asset manifest/KV.

For SPA mapping pass in the serveSinglePageApp function

Example

Strip /docs from any incoming request before looking up an asset in Cloudflare's KV.

import { getAssetFromKV, mapRequestToAsset } from '@cloudflare/kv-asset-handler'
...
const customKeyModifier = request => {
  let url = request.url
  //custom key mapping optional
  url.replace('/docs', '').replace(/^\/+/, '')
  return mapRequestToAsset(new Request(url, request))
}
let asset = await getAssetFromKV(event, { mapRequestToAsset: customKeyModifier })

cacheControl

type: object

cacheControl allows you to configure options for both the Cloudflare Cache accessed by your Worker, and the browser cache headers sent along with your Workers' responses. The default values are as follows:

let cacheControl = {
  browserTTL: null, // do not set cache control ttl on responses
  edgeTTL: 2 * 60 * 60 * 24, // 2 days
  bypassCache: false, // do not bypass Cloudflare's cache
}

browserTTL

type: number | null nullable: true

Sets the Cache-Control: max-age header on the response returned from the Worker. By default set to null. which will not add the header at all.

edgeTTL

type: number nullable: false

Sets the Cache-Control: max-age header on the response used as the edge cache key. By default set to 2 days (2 * 60 * 60 * 24).

bypassCache

type: boolean

Determines whether to cache requests on Cloudflare's edge cache. By default set to false (recommended for production builds). Useful for development when you need to eliminate the cache's effect on testing.

ASSET_NAMESPACE

type: KV Namespace Binding

The binding name to the KV Namespace populated with key/value entries of files for the Worker to serve. By default, Workers Sites uses a binding to a Workers KV Namespace named __STATIC_CONTENT.

It is further assumed that this namespace consists of static assets such as html, css, javascript, or image files, keyed off of a relative path that roughly matches the assumed url pathname of the incoming request.

return getAssetFromKV(event, { ASSET_NAMESPACE: MY_NAMESPACE })

ASSET_MANIFEST (optional)

type: text blob (JSON formatted)

The mapping of requested file path to the key stored on Cloudflare.

Workers Sites with Wrangler bundles up a text blob that maps request paths to content-hashed keys that are generated by Wrangler as a cache-busting measure. If this option/binding is not present, the function will fallback to using the raw pathname to look up your asset in KV. If, for whatever reason, you have rolled your own implementation of this, you can include your own by passing a stringified JSON object where the keys are expected paths, and the values are the expected keys in your KV namespace.

let assetManifest = { "index.html": "index.special.html" }
return getAssetFromKV(event, { ASSET_MANIFEST: JSON.stringify(assetManifest) })

Other functions

mapRequestToAsset

type: function(Request) => Request

The default function for mapping incoming requests to keys in Cloudflare's KV.

Takes any path that ends in / or evaluates to an html file and appends index.html or /index.html for lookup in your Workers KV namespace.

serveSinglePageApp

type: function(Request) => Request

A custom handler for mapping requests to a single root: index.html. The most common use case is single-page applications - frameworks with in-app routing - such as React Router, VueJS, etc. It takes zero arguments.

import { getAssetFromKV, serveSinglePageApp } from '@cloudflare/kv-asset-handler'
...
let asset = await getAssetFromKV(event.request, { mapRequestToAsset: serveSinglePageApp })