sveltekit-cloudflare-durable-objects

Bridge the gap between SvelteKit and Cloudflare Durable Objects

Automatically export your Durable Objects to the Cloudflare Worker bundle generated by @sveltejs/adapter-cloudflare.

The Problem

When using SvelteKit with Cloudflare's adapter, Durable Object classes need to be exported from the worker entry point (.svelte-kit/cloudflare/_worker.js). However, this file is generated during the build process, making it difficult to include your Durable Objects exports.

The typical error you'll encounter:

[ERROR] Your Worker depends on the following Durable Objects, which are not exported in your entrypoint file

There is a suggested work-around:

https://github.com/sveltejs/kit/issues/13692#issuecomment-3055244347

Unfortunately that is not idempotent. This plugins aims to solve that by setting a marker and making it a Vite plugin so that you don't need to worry about it.

The Solution

This package provides two ways to automatically add your Durable Objects exports to the worker bundle:

1. Vite Plugin (recommended) - Seamlessly integrates with your build process
2. CLI Tool - For manual or custom build workflows

Both methods are idempotent - safe to run multiple times without duplicating exports.

Installation

pnpm add -D sveltekit-cloudflare-durable-objects
# or
npm install -D sveltekit-cloudflare-durable-objects
# or
yarn add -D sveltekit-cloudflare-durable-objects

Usage

Option 1: Vite Plugin (Recommended)

Add the plugin to your vite.config.ts:

import { sveltekit } from '@sveltejs/kit/vite';
import cloudflareDoExporter from 'sveltekit-cloudflare-durable-objects';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    sveltekit(),
    cloudflareDoExporter({
      // Optional: specify your Durable Object files
      // Default: ['src/lib/durable-objects.ts']
      durableObjects: ['src/lib/durable-objects.ts']
    })
  ]
});

That's it! The plugin will automatically export your Durable Objects after each production build.

Note: The plugin only runs during vite build (production builds), not during vite dev (development mode). This is intentional - the worker file is only generated during production builds.

Option 2: CLI Tool

Add to your package.json scripts:

{
  "scripts": {
    "build": "vite build && sveltekit-cloudflare-do"
  }
}

Or run directly:

pnpm sveltekit-cloudflare-do

Configuration

Vite Plugin Options

interface DurableObjectsExporterOptions {
  /**
   * Path(s) to your Durable Object file(s)
   * @default ['src/lib/durable-objects.ts']
   */
  durableObjects?: string | string[];

  /**
   * Path to the worker file (relative to project root)
   * @default '.svelte-kit/cloudflare/_worker.js'
   */
  workerPath?: string;

  /**
   * Enable verbose logging
   * @default false
   */
  verbose?: boolean;
}

CLI Options

sveltekit-cloudflare-do [options]

Options:
  --help, -h              Show help message
  --version, -v           Show version
  --verbose               Enable verbose logging
  --worker <path>         Path to worker file
  --do <path>             Path to durable object file (can be used multiple times)

Configuration File

You can also configure options in package.json:

{
  "sveltekit-cloudflare-do": {
    "durableObjects": ["src/lib/durable-objects.ts"],
    "workerPath": ".svelte-kit/cloudflare/_worker.js"
  }
}

Or in .do-exporter.json:

{
  "durableObjects": ["src/lib/durable-objects.ts"],
  "workerPath": ".svelte-kit/cloudflare/_worker.js"
}

Multiple Durable Objects

If you have multiple Durable Object files:

// vite.config.ts
cloudflareDoExporter({
  durableObjects: [
    'src/lib/durable-objects/chat.ts',
    'src/lib/durable-objects/counter.ts',
    'src/lib/durable-objects/session.ts'
  ]
})

Complete Example

1. Create your Durable Object

// src/lib/durable-objects.ts
import { DurableObject } from 'cloudflare:workers';

export class MyDurableObject extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
  }

  async fetch(request: Request): Promise<Response> {
    return new Response('Hello from Durable Object!');
  }
}

2. Configure Wrangler

// wrangler.jsonc
{
  "name": "my-sveltekit-app",
  "main": ".svelte-kit/cloudflare/_worker.js",
  "durable_objects": {
    "bindings": [
      {
        "name": "MY_DURABLE_OBJECT",
        "class_name": "MyDurableObject"
      }
    ]
  }
}

3. Add the Vite Plugin

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import cloudflareDoExporter from 'sveltekit-cloudflare-durable-objects';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    sveltekit(),
    cloudflareDoExporter()
  ]
});

4. Build and Deploy

pnpm build
wrangler deploy

Development Workflow

Understanding when and how the plugin runs:

1. During development (vite dev):

   • The plugin does NOT run - this is intentional
   • The dev server doesn't use the worker file, so exports aren't needed
   • You can develop your SvelteKit app normally

2. During production build (vite build):

   • The plugin runs automatically after the build
   • It adds Durable Objects exports to .svelte-kit/cloudflare/_worker.js
   • The worker file is now ready for deployment

3. Testing locally with Wrangler:

   • Run vite build first to generate the worker file
   • Then use wrangler dev or wrangler pages dev
   • Your Durable Objects will be properly exported

How It Works

After your SvelteKit production build completes, this tool:

1. Reads the generated worker file (.svelte-kit/cloudflare/_worker.js)
2. Checks if Durable Objects are already exported (idempotency)
3. Appends export statements for your Durable Object files
4. Adds a marker comment to prevent duplicate exports

Example of what gets added:

// DURABLE_OBJECTS_EXPORT - do not remove
export * from '../../src/lib/durable-objects.ts';

Troubleshooting

Error during vite dev or wrangler dev

Error: Worker file not found at .svelte-kit/cloudflare/_worker.js

Solution: This is expected! The plugin only runs during production builds, not development mode. If you see this error:

1. If using vite dev: This error should not occur with version 0.1.1+. Update the package if you're seeing this.
2. If using wrangler dev: Run vite build first to generate the worker file, then run wrangler dev.

The workflow should be:

# Development
vite dev              # No worker file needed, plugin doesn't run

# Testing with Wrangler
vite build            # Generates worker file, plugin adds exports
wrangler dev          # Uses the built worker file

# Deployment
vite build            # Generates worker file, plugin adds exports
wrangler deploy       # Deploys the worker

Warning: "No such Durable Object class is exported"

Error: A DurableObjectNamespace in the config referenced the class "MyDurableObject", but no such Durable Object class is exported from the worker

Solution:

1. Make sure you've run vite build to generate the worker file
2. Verify that the plugin ran successfully (you should see a success message)
3. Check that the class name in wrangler.jsonc matches your exported class name exactly
4. Ensure your Durable Object file path is correct in the plugin configuration

Worker file not found

Make sure you run vite build before trying to deploy or use wrangler dev. The plugin handles this automatically during the build process.

Durable Object not found at runtime

Ensure your Durable Object class:

1. Imports DurableObject from 'cloudflare:workers'
2. Is exported with export class MyDurableObject
3. Is specified in your Wrangler configuration with the exact class name

TypeScript errors

Generate Cloudflare types:

wrangler types

License

MIT

Contributing

Issues and pull requests welcome!

Related

• SvelteKit Cloudflare Adapter
• Cloudflare Durable Objects
• Wrangler