vite-plugin-cloudflare-functions

0.8.4 verified Mon Apr 27 auth: no javascript

Vite plugin (v0.8.4) that makes Cloudflare Pages Functions work seamlessly with Vite, offering HMR, local dev with wrangler, and support for D1, R2, KV, and Durable Objects. Released ~monthly, it integrates Cloudflare's workers-types, generates TypeScript declarations, and allows configuration of persist-to, compatibility-date, and more. Key differentiator: provides a Vite-native experience for Cloudflare Pages Functions, enabling fast development with auto-reload and type generation. Requires Vite >=3.1.8, wrangler ^2.20.1 || ^3.0.0, and optional HTTP client.

Common errors

error Cannot find module 'vite-plugin-cloudflare-functions' or its corresponding type declarations. ↓

cause Missing TypeScript declarations or module resolution issue.

fix

Install the package and ensure 'compilerOptions.moduleResolution' is set to 'bundler' or 'node' in tsconfig.json.

error Error: The 'config' file is not found in the 'functions' directory. ↓

cause Custom 'functionsDir' path does not exist or is misconfigured.

fix

Check the 'functionsDir' option in the Vite config and create the directory if needed.

error Error: The 'wrangler' CLI is not installed. ↓

cause Missing wrangler peer dependency.

fix

Run 'npm install --save-dev wrangler'.

error Error: The environment variable is not set: CF_ACCOUNT_ID, CF_API_TOKEN ↓

cause Missing Cloudflare credentials for production deployment.

fix

Set CF_ACCOUNT_ID and CF_API_TOKEN in your environment variables or .env file.

error Error: The 'persistTo' directory path must be a string. ↓

cause Incorrect type or format for the 'persistTo' option.

fix

Provide a string path, e.g., 'persistTo: './data/persist''.

Warnings

gotcha Plugin requires wrangler to be installed, but it is a peer dependency; not auto-installed by npm. ↓

fix Run 'npm install --save-dev wrangler'.

breaking In v0.6.0, the plugin disables inheriting HTTP_PROXY / HTTPS_PROXY env variables by default, which may break proxied environments. ↓

fix Set 'inheritHttpProxy: true' in plugin options to restore old behavior.

deprecated The 'ohmyfetch' package is obsolete; prefer 'ofetch'. ↓

fix Replace 'ohmyfetch' with 'ofetch' in your project.

gotcha TypeScript declarations require an additional dependency '@cloudflare/workers-types' to function properly. ↓

fix Install '@cloudflare/workers-types' as a dev dependency.

gotcha Durable Objects (DO) configuration changed in v0.7.0; the 'do' config format is more explicit. ↓

fix Update DO config to use the new schema as documented.

gotcha Plugin uses 'mlly' for module loading; ensure your Node version meets the minimum (>=v18.16.0). ↓

fix Upgrade Node.js to v18.16.0 or later.

deprecated The 'fast-glob' dependency has been updated to v3.3.3; older versions may cause globbing issues. ↓

fix Update vite-plugin-cloudflare-functions to >=0.8.3.

Install

npm install vite-plugin-cloudflare-functions

yarn add vite-plugin-cloudflare-functions

pnpm add vite-plugin-cloudflare-functions

Imports

default

wrong

import { CloudflareFunctions } from 'vite-plugin-cloudflare-functions'

correct

import CloudflareFunctions from 'vite-plugin-cloudflare-functions'

Default export; named export does not exist.

CloudflareFunctionsPlugin

wrong

import CloudflareFunctionsPlugin from 'vite-plugin-cloudflare-functions'

correct

import { type CloudflareFunctionsPlugin } from 'vite-plugin-cloudflare-functions'

Type import for TypeScript; use 'import type' to avoid bundling.

defineCloudflareFunctionsConfig

wrong

import { defineCloudflareFunctionsConfig } from 'vite-plugin-cloudflare-functions'

correct

import { defineCloudflareFunctionsConfig } from 'vite-plugin-cloudflare-functions/config'

Config helper is exported from a subpath.

Quickstart

Configures vite-plugin-cloudflare-functions with TypeScript support and a sample handler function.

// vite.config.ts
import { defineConfig } from 'vite'
import CloudflareFunctions from 'vite-plugin-cloudflare-functions'

export default defineConfig({
  plugins: [
    CloudflareFunctions({
      // Path to functions directory (default: 'src/functions')
      functionsDir: 'src/functions',
      // Generate TypeScript declarations (default: true)
      dts: true,
      // Enable local persistence for KV, D1, etc.
      persistTo: 'path/to/persist',
      // Set Cloudflare compatibility date
      compatibilityDate: '2024-12-01'
    })
  ]
})

// Example function: src/functions/hello.ts
import { defineHandler } from 'vite-plugin-cloudflare-functions/handler'

export const onRequest: PagesFunction = defineHandler({
  async fetch(request, env, ctx) {
    return new Response('Hello from Cloudflare Functions!')
  }
})