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

`bash
pnpm add -D sveltekit-cloudflare-durable-objects


or

npm install -D sveltekit-cloudflare-durable-objects

or

yarn add -D sveltekit-cloudflare-durable-objects
`

Usage

$3

Add the plugin to your vite.config.ts:

`typescript
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.

$3

Add to your package.json scripts:

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

Or run directly:

`bash
pnpm sveltekit-cloudflare-do
`

Configuration

$3

`typescript
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;
}
`

$3

`bash
sveltekit-cloudflare-do [options]

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

$3

You can also configure options in package.json:

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

Or in .do-exporter.json:

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

Multiple Durable Objects

If you have multiple Durable Object files:

`typescript
// 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

$3

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

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

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

$3

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

$3

`typescript
// 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()
]
});
`

$3

`bash
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:

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

Troubleshooting

$3

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:
`bash


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
`

$3

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

$3

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

$3

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

$3

Generate Cloudflare types:

`bash
wrangler types
``

License

MIT

Contributing

Issues and pull requests welcome!

Related

- SvelteKit Cloudflare Adapter
- Cloudflare Durable Objects
- Wrangler