Cloudflare Workers

mion can run on Cloudflare Workers for globally-distributed edge deployments. The @mionjs/platform-cloudflare package provides a Web standard Request -> Response fetch handler with access to Worker bindings via the platform context.

Installation

npm install @mionjs/platform-cloudflare @mionjs/router

Quick Start

import {initMionRouter} from '@mionjs/router';
import {createCloudflareHandler} from '@mionjs/platform-cloudflare';
import {routes} from './cloudflare-routes.ts';

await initMionRouter(routes, {aot: true});

export default createCloudflareHandler();

import {Routes, route} from '@mionjs/router';

export const routes = {
    sayHello: route((ctx, name: string): string => {
        return `Hello ${name}!`;
    }),
} satisfies Routes;

wrangler.toml Example

A minimal wrangler.toml for a mion Worker:

name = "my-mion-api"
main = "dist/worker.js"
compatibility_date = "2024-01-01"

The main field points to the bundled output produced by Vite (see AOT Compilation Required below). Run wrangler deploy to publish.

Configuration

You can pass configuration options to createCloudflareHandler:

import {initMionRouter} from '@mionjs/router';
import {createCloudflareHandler} from '@mionjs/platform-cloudflare';
import {routes} from './cloudflare-routes.ts';

await initMionRouter(routes, {aot: true, basePath: 'api'});

export default createCloudflareHandler({
    basePath: '/api',
    defaultResponseHeaders: {'access-control-allow-origin': '*'},
});

AOT Compilation Required

mion's default JIT compilation generates validation and serialization functions at runtime using new Function(). Workers block this for security reasons, so Cloudflare projects must be bundled with pre-compiled AOT caches. The mion Vite plugin handles this automatically — see AOT Compilation for the full explanation.

Vite Configuration

A minimal vite.config.ts for a Cloudflare Worker:

import {defineConfig} from 'vite';
import {mionPlugin} from '@mionjs/devtools/vite-plugin';

export default defineConfig({
    plugins: [
        mionPlugin({
            aotCaches: {},
            server: {
                startScript: 'src/index.ts',
                runMode: 'buildOnly',
            },
        }),
    ],
    build: {
        lib: {
            entry: 'src/index.ts',
            formats: ['es'],
            fileName: 'worker',
        },
        rollupOptions: {
            output: {inlineDynamicImports: true},
        },
    },
});

inlineDynamicImports: true is required because Workers don't support dynamic code splitting — every dependency must be bundled into a single file.

Worker Entry

The Worker entry file calls initMionRouter with aot: true to enable strict AOT mode. In strict mode @mionjs/run-types is not loaded at all, every route must be present in the AOT cache, and the Vite plugin auto-injects the cache contents at bundle time:

import {initMionRouter} from '@mionjs/router';
import {createCloudflareHandler} from '@mionjs/platform-cloudflare';
import {routes} from './cloudflare-routes.ts';

await initMionRouter(routes, {aot: true});

export default createCloudflareHandler();

For TypeScript support of the virtual modules (only needed if you import them manually), add this to your tsconfig.json:

{
  "compilerOptions": {
    "types": ["@mionjs/devtools/virtual-modules"]
  }
}

Type Reference

CloudflareHandlerOptions

export interface CloudflareHandlerOptions {
    /** Set of default response headers to add to every response */
    defaultResponseHeaders: Record<string, string>;
    /** Path prefix to strip from incoming URL (e.g., '/api/mion') */
    basePath: string;
}