@cloudflare/kv-asset-handler - npm Package Compare versions

Comparing version 0.0.6 to 0.0.7

CHANGELOG.md

 # Changelog
 
+## 0.0.7
+
+- ### Features
+
+  - **Add handler for SPAs - [ashleymichal], [issue/46] [pull/47]**
+
+    Some browser applications employ client-side routers that handle navigation in the browser rather than on the server. These applications will work as expected until a non-root URL is requested from the server. This PR adds a special handler, `serveSinglePageApp`, that maps all html requests to the root index.html. This is similar to setting a static asset route pattern in an Express.js app.
+
+    [ashleymichal]: https://github.com/ashleymichal
+    [issue/46]: https://github.com/cloudflare/kv-asset-handler/issues/46
+    [pull/47]: https://github.com/cloudflare/kv-asset-handler/pull/47
+
+- ### Documentation
+
+  - **Add function API for `getAssetFromKV` to README.md - [ashleymichal], [issue/48] [pull/52]**
+
+    This function, used to abstract away the implementation for retrieving static assets from a Workers KV namespace, includes a lot of great options for configuring your own, bespoke "Workers Sites" implementation. This PR adds documentation to the README for use by those who would like to tinker with these options.
+
+    [ashleymichal]: https://github.com/ashleymichal
+    [issue/46]: https://github.com/cloudflare/kv-asset-handler/issues/48
+    [pull/47]: https://github.com/cloudflare/kv-asset-handler/pull/52
+
 ## 0.0.6
 
-- ### Fixes 
+- ### Fixes
 
-  - **Improve caching - [victoriabernard92], [issue/38][pull/37]**
+  - **Improve caching - [victoriabernard92], [issue/38] [pull/37]**
 
@@ -9,0 +31,0 @@ - Don't use browser cache by default: Previously, `kv-asset-handler` would set a `Cache-Control` header on the response sent back from the Worker to the client. After this fix, the `Cache-Control` header will only be set if `options.cacheControl.browserTTL` is set by the caller.

package.json

 {
   "name": "@cloudflare/kv-asset-handler",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Routes requests to KV assets",
@@ -5,0 +5,0 @@ "main": "./src/index.js",

README.md

@@ -14,13 +14,10 @@ # @cloudflare/kv-asset-handler
 
-Currently this exports a single function `getAssetFromKV` that maps `FetchEvent` objects to KV Assets, and throws an `Error` if it cannot.
+This package was designed to work with [Worker Sites](https://workers.cloudflare.com/sites).
 
-```js
-import { getAssetFromKV } from '@cloudflare/kv-asset-handler'
-```
+### `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`.
 
-Note this package was designed to work with Worker Sites. If you are not using Sites make sure to call the bucket you are serving assets from `__STATIC_CONTENT`
 
-### Example
+#### Example
 
@@ -35,2 +32,3 @@ 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 `/`.
 })
+
 const customKeyModifier = url => {
@@ -41,6 +39,7 @@ //custom key mapping optional
 }
+
 async function handleEvent(event) {
   if (event.request.url.includes('/docs')) {
     try {
-      return await getAssetFromKV(event, customKeyModifier)
+      return await getAssetFromKV(event, { mapRequestToAsset: customKeyModifier })
     } catch (e) {
@@ -55,1 +54,116 @@ return new Response(`"${customKeyModifier(event.request.url)}" not found`, {
 ```
+
+### 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`](#maprequesttoasset-1).  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`](#servesinglepageapp) function
+
+#### Example
+
+Strip `/docs` from any incoming request before looking up an asset in Cloudflare's KV.
+
+```js
+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:
+
+```javascript
+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](https://developers.cloudflare.com/workers/reference/storage/api/#namespaces) 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.
+
+```js
+import { getAssetFromKV, serveSinglePageApp } from '@cloudflare/kv-asset-handler'
+...
+let asset = await getAssetFromKV(event.request, { mapRequestToAsset: serveSinglePageApp })
+```

src/index.js

@@ -28,2 +28,24 @@ import mime from 'mime'
 
+/**
+ * maps the path of incoming request to /index.html if it evaluates to
+ * any html file.
+ * @param {Request} request incoming request
+ */
+function serveSinglePageApp(request) {
+  // First apply the default handler, which already has logic to detect
+  // paths that should map to HTML files.
+  request = mapRequestToAsset(request)
+
+  // Detect if the default handler decided to map to
+  // a HTML file in some specific directory.
+  if (request.url.endsWith('.html')) {
+    // If expected HTML file was missing, just return the root index.html
+    return new Request(`${new URL(request.url).origin}/index.html`, request)
+  } else {
+    // The default handler decided this is not an HTML page. It's probably
+    // an image, CSS, or JS file. Leave it as-is.
+    return request
+  }
+}
+
 const defaultCacheControl = {
@@ -160,2 +182,2 @@ browserTTL: null,
 
-export { getAssetFromKV, mapRequestToAsset }
+export { getAssetFromKV, mapRequestToAsset, serveSinglePageApp }

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

36483

increased by27.42%

Number of package files

12

increased by20%

Lines of code

423

increased by14.63%

Number of lines in readme file

166

increased by219.23%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes