vite-plugin-cloudflare-functions

Make Cloudflare Pages Functions works with Vite friendly.

Features

When should you use this plugin?

• If it is not necessary to use a heavy SSR framework like nuxt
• If your application is a static SPA, but you also want to write several API endpoints

If you have used some meta SSR framework like nuxt, there is no need to use this plugin. But if you want to add some API endpoints to your SPA, just use it.

This plugin provides some simple utilities to help you develop a SPA with serverless API endpoints powered by Cloudflare Pages Functions.

• Dev: Automatically start wrangler pages dev server
• Dev: Automatically generate serverless functions API type declaration
• Build: Automatically move the functions source directory for monorepo

Installation

1npm i -D vite-plugin-cloudflare-functions

1// vite.config.ts
2
3import { defineConfig } from 'vite';
4
5import CloudflarePagesFunctions from 'vite-plugin-cloudflare-functions';
6
7export default defineConfig({
8  plugins: [
9    CloudflarePagesFunctions()
10  ]
11});

Usage

Functions

Just write pages functions as usual, but you can use the following utility functions to make auto-generation and IDE type inference work.

• makePagesFunction
• makeRawPagesFunction
• makeResponse: create a Response using your JSON object
• makeRawResponse: same with new Response(...) but wrapped with a generic type used for type inference

1// /api/[msg].ts
2
3import {
4  makeRawPagesFunction,
5  makePagesFunction,
6  makeResponse
7} from 'vite-plugin-cloudflare-functions/worker';
8
9export const onRequestGet = makePagesFunction(({ params }) => ({
10  status: 'OK',
11  data: 'Hello, ' + params.msg + '!'
12}));
13
14export const onRequestPost = makeRawPagesFunction(({ params }) =>
15  makeResponse({
16    status: 'OK',
17    data: 'Post ' + params.msg + ' OK!'
18  })
19);

Override environment

For example, you have set the environment variable PASS (you can config it in the plugin option, see Configuration).

1// cloudflare.d.ts
2
3/// <reference types="@cloudflare/workers-types" />
4/// <reference types="vite-plugin-cloudflare-functions/types" />
5
6import 'vite-plugin-cloudflare-functions/worker';
7
8declare module 'vite-plugin-cloudflare-functions/worker' {
9  interface PagesFunctionEnv {
10    PASS: string;
11  }
12
13  interface PagesFunctionData {}
14}

Then you can find the parameter env has corresponding type declarations.

1// /api/index.ts
2
3import { makePagesFunction } from 'vite-plugin-cloudflare-functions/worker';
4
5export const onRequestGet = makePagesFunction(({ env }) => ({
6  pass: env.PASS
7}));

Client

Just write you client code as usual, but for we generate the API endpoint response body type declarations automatically, so that with the provided client useFunctions (powered by axios), your IDE will provide smarter IntelliSense.

1// /main.ts
2import { useFunctions } from 'vite-plugin-cloudflare-functions/client';
3
4const client = useFunctions();
5
6client.get('/api/world').then((resp) => {
7  // The type of resp is { status: string, data: string }
8});

Full example is here.

Configuration

1// vite.config.ts
2
3import { defineConfig } from 'vite';
4
5import CloudflarePagesFunctions from 'vite-plugin-cloudflare-functions';
6
7export default defineConfig({
8  plugins: [
9    CloudflarePagesFunctions({
10      // Cloudflare Functions root directory
11      root: './functions',
12      // Copy the functions directory to outDir or do nothing
13      outDir: undefined,
14      // Generate API type declarations
15      dts: './cloudflare.d.ts',
16      // Wrangler configuration
17      wrangler: {
18        // Wrangler dev server port
19        port: 8788,
20        // Enable wrangler log
21        log: true,
22        // Bind variable/secret
23        binding: {
24          KEY: 'VALUE'
25        },
26        // Bind KV namespace
27        kv: [
28          'NAMESPACE'
29        ],
30        // Bind D1 database 
31        d1: [
32          'D1'
33        ],
34        // Bind Durable Object
35        do: {
36          DO: 'DO'
37        },
38        // Bind R2 bucket
39        r2: [
40          'BUCKET'
41        ],
42        // Bind Workers AI
43        ai: [
44          'AI'
45        ]
46      }
47    })
48  ]
49});

Note

This plugin starts the wrangler pages dev server under the hood. The configuration field binding, kv, do, d1, r2, ai are passed to run the command wrangler pages dev to start pages dev server. You can find more information about this command at Commands - Cloudflare Worker docs.

The generated command of the above example is wrangler pages dev --local --ip localhost --port 8788 --proxy <generated by vite dev server> --binding KEY=VALUE --kv NAMESPACE --d1 D1 --do DO=DO --r2 BUCKET --ai AI.

License

MIT License © 2022 XLor