How to run SvelteKit & Cloudflare Page locally?

Question

I'm trying to create a new app using SvelteKit & Cloudflare Pages and I'm struggling with running the application locally in a proper manner. Currently, in order to get the app running locally I run 2 scripts in 2 different terminals:

1. vite build --watch
   • this creates the cloudflare directories in the .svelte-kit directory
   • vite dev doesn't seem to create the cloudflare directories so I've used vite build
2. wrangler pages dev .svelte-kit/cloudflare --live-reload
   • this starts the app

The above approach works, namely, it starts the app as expected. The problem is that any changes I'm making to the code are visible in the browser tab after 3-4 seconds which from a DX point of view is far from enjoying. Ideally, when running locally, any code changes should be visible in the browser tab in 1-sec-ish.

This is the first time I'm tinkering with SvelteKit & Cloudflare Pages so I'm sure I'm missing something. Therefore, the question is: how should one run a SvelteKit & Cloudflare Pages app locally "the right way"? "The right way" means that I can see the effect of my code changes in 1-sec-ish and I can run the app locally using something like wrangler or miniflare in order for the local environment to resemble as much as possible the production one.

P.s.: I've checked docs like https://developers.cloudflare.com/pages/framework-guides/deploy-a-svelte-site/ and https://www.npmjs.com/package/@sveltejs/adapter-cloudflare readme.md but they focus mainly on how to run the app in production
P.p.s: I believe the 2 scripts can be merged into a single one using something like concurrently but at the moment my focus is on having quick feedback when it comes to code changes
P.p.p.s.: bundling and tinkering with the javascript modules themselves is not one of my strong points yet so if you have any helpful articles, they're more than welcome

Answer 1

I'd suggest using server hooks to setup the platform, and then use the Miniflare v3 APIs to simulate Cloudflare bindings locally. Then you can just use the standard Sveltekit/vite commands to run locally e.g. npm run dev.

Here's a template project you can use as a starter that supports D1 and KV bindings, plus the cf properties, that the env would normally get. It also uses the same file location as wrangler, so you can use regular --local commands from wrangler to handle migrations etc.

See https://github.com/sdarnell/cf-svelte/

It uses hooks.server.ts to dynamically load miniflare in dev only:

// /src/hooks.server.ts
import { dev } from '$app/environment';
import type { Handle } from '@sveltejs/kit';

export const handle = (async ({ event, resolve }) => {
    if (dev && !event.platform) {
        const mf = await import('./lib/server/miniflare');
        event.platform = await mf.setupPlatform();
    }
    return resolve(event);
}) satisfies Handle;

Then in the miniflare.ts helper file it parses a wrangler.toml file, then creates a Miniflare instance with the corresponding bindings:

...
    const kvs = Object.fromEntries((toml.kv_namespaces || []).map(d => [d.binding, d.id]));
    const dbs = Object.fromEntries((toml.d1_databases || []).map(d => [d.binding, d.database_id]));

    const root = '.wrangler/state/v3';
    const mf = new Miniflare({
        log: new Log(LogLevel.WARN),
        modules: true,
        script: '',
        d1Databases: dbs,
        kvNamespaces: kvs,
        kvPersist: `${root}/kv`,
        d1Persist: `${root}/d1`,
        compatibilityDate: toml.compatibility_date,
    });

    platform = {
        env: await mf.getBindings(),
        context: {},
        caches: {},
        cf: cachedCfDotJson,
    } as App.Platform;
...

Update: the cf-svelte project has been updated to import wrangler which does effectively the same as above, but it is now supported by Cloudflare. This eliminates the miniflare.ts file.

Answer 2

Had the same requirement, and a quick Google which brought me here, didn't help; however, it turns out the solution can be found in the current Cloudflare docs:

https://developers.cloudflare.com/pages/platform/functions/local-development/

In summary, running the following should do the trick:

npx wrangler pages dev -- npm run dev