vite-plugin-cloudflare 🔥
Vite-plugin-cloudflare is a plugin for transforming & bundling cloudflare
workers with shimming modern node
polyfills like process,
os, stream and other node global functions and modules using Esbuild and Vite!
- Universal Vite plugin
- Lightning builds
- Workers compatible build using shimming
- Fast development and HMR compatible reloads
- Builtin Miniflare support
Install
npm i --save-dev vite-plugin-cloudflare esbuild@latest
Plugin
// vite.config.js
import { defineConfig } from "vite";
import vpc from "vite-plugin-cloudflare";
export default defineConfig({
plugins: [vpc({ scriptPath: "./worker/index.ts" })],
});
The plugin gets an options object with this type signature.
export type Options = {
// miniflare specific options for development (optional)
miniflare?: Omit<MiniflareOptions, "script" | "watch">;
// the worker file (required)
scriptPath: string;
// customize globals that need to polyfilled (process, setTimeout, ...)
polyfilledGlobals?: PolyfilledGlobals;
// customize mods (node's builtinModules) that need to polyfilled (utils, http, ...)
polyfilledModules?: PolyfilledModules;
// a fast-glob pattern for files who's changes should reload the worker (optional)
workerFilesPattern?: string | string[];
// enable modules (esm)
modules?: boolean;
};
Since this plugin works with Esbuild, options passed to the esbuild field of
your vite plugin will affect the worker result, unless they are not compatible
with the BuildOptions type of Esbuild.
Development
You can start your Vite dev server and continue developing your applications. As
previously mentioned, this plugin integrates Miniflare with Vite, so you'd have
a nice experience writing your workers.
vite dev
Build
When building, the plugin is going to start bundling your worker at the end of
the vite bundling phase and generates it into the config.outDir with the
worker.js file name.
vite build
Output:
vite v3.0.4 building for production...
✓ 6 modules transformed.
dist/assets/typescript.f6ead1af.svg 1.40 KiB
dist/index.html 0.44 KiB
dist/assets/index.2547d205.js 1.41 KiB / gzip: 0.72 KiB
dist/assets/index.d0964974.css 1.19 KiB / gzip: 0.62 KiB
🔥 [cloudflare] bundled worker file in 'dist/worker.js'
Wrangler
Update your wrangler config to be compatible with the build, for instance,
here's a config that uses the dist/worker.js bundled worker file generated by
vite-plugin-cloudflare and serves the assets from the vite build:
# wrangler.toml
name = "vite-ssr-worker"
main = "./dist/worker.js"
compatibility_date = "2022-08-10"
[site]
bucket = "./dist/client"
The values may change based on your build
Skip Requests
Vite has some builtin middlewares that handle different types of requests from the
client, and in a Vite plugin, we can inject our middlewares along
vite ones.
Vite-plugin-cloudflare injects a middleware, that is responsible for handling
the worker, So every request from the client (browser) may come to your worker
first, before vite native middlewares. These requests can be assets,
transforms and other types of vite-related requests that should not be handled by
vite-plugin-cloudflare and instead, they should be handled by vite.
This concern only occurs in dev mode, so no worries when building for production
Here's how we handle these type of requests in vite-plugin-cloudflare.
addEventListener("fetch", (event) => {
const { pathname } = new URL(url);
if (pathname.startsWith("/api")) {
event.respondWith(handleFetchEvent(event));
return;
}
event.respondWith(
new Response("", {
headers: {
"x-skip-request": "",
},
})
);
});
The x-skip-request header enforces vite-plugin-cloudflare to skip the response of the worker and passes the
request to the next vite middleware, so Vite would handle the request instead.
Authors
Contributing
Feel free to create issues/discussions and then PRs for the project!
Sponsors
Your sponsorship can make a huge difference in continuing our work in open source!
