{"id":10517,"date":"2026-07-27T22:59:22","date_gmt":"2026-07-28T03:59:22","guid":{"rendered":"https:\/\/master.dev\/blog\/?p=10517"},"modified":"2026-07-27T22:59:23","modified_gmt":"2026-07-28T03:59:23","slug":"cloudflare-workers-and-hyperdrive-with-sveltekit","status":"publish","type":"post","link":"https:\/\/master.dev\/blog\/cloudflare-workers-and-hyperdrive-with-sveltekit\/","title":{"rendered":"Cloudflare Workers and Hyperdrive with SvelteKit"},"content":{"rendered":"\n

Let’s get into web application setup for Cloudflare Workers on SvelteKit<\/a>. I’ve written about Cloudflare where we introduced workers<\/a>, and then where we showed some of the one-off development considerations needed for getting Workers to work in TanStack Start<\/a>.<\/p>\n\n\n\n

This will be similar to the latter, except we’ll look at SvelteKit rather than TanStack.<\/p>\n\n\n\n

I’ve found the Cloudflare\/SvelteKit integration not quite as seamless as TanStack’s, but it’s still outstanding and doesn’t take too much effort to get up and running.<\/p>\n\n\n\n

What are Cloudflare Workers?<\/h2>\n\n\n\n

Cloudflare Workers are conceptually similar to AWS Lambda functions. They’re cloud functions that spin up on demand, as much or as little as your application’s traffic demands at any given moment. Except Cloudflare Workers have very, very low latency. The “cold starts” Lambda is known to have are virtually non-existent with Workers.<\/p>\n\n\n\n

What’s the Catch?<\/h2>\n\n\n\n

Not much, really. There was a time when Cloudflare Workers had a runtime that was a subset of Node, but those days are over. Cloudflare Workers now have a Node compat mode that solves those problems.<\/p>\n\n\n\n

The main limitation with Workers is that they have special rules requiring you to clean up after yourself in ways other runtimes don’t. Namely, you cannot have long-running I\/O objects surviving between requests. In particular, you cannot simply have a module export a db<\/code> object that connects to your database. Each request must spin that connection up fresh.<\/p>\n\n\n\n

Introducing Hyperdrive<\/h2>\n\n\n\n

Spinning up a fresh database connection was always a bad idea in any<\/em> cloud function runtime, such as AWS Lambda. These functions spin up as needed, and during periods of bursting traffic, the number of Lambda functions being created could easily overwhelm your database.<\/p>\n\n\n\n

But with Workers requiring a fresh connection per request,<\/em> this is even more dangerous. To say nothing of the fact that we’d hardly want to ruin Workers’ low latency by requiring them to perform the time-consuming operation of establishing a fresh TCP connection to our database, let alone once per request<\/em>.<\/p>\n\n\n\n

To solve these problems, Cloudflare has a tool called Hyperdrive<\/a>, which keeps a pool of pre-warmed connections to our database open. Our Workers then quickly connect to Hyperdrive and gain immediate access to these pre-warmed connections.<\/p>\n\n\n\n

Getting Started<\/h2>\n\n\n\n

Let’s scaffold an essentially empty SvelteKit application. We’ll go to the directory we want our app, and then kick things off.<\/p>\n\n\n

npx sv create .<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
Enabling Cloudflare<\/h2>\n\n\n\n
Let’s set up basic Cloudflare infrastructure for our project.<\/p>\n\n\n
npx wrangler deploy<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
We’ll be asked a few questions, to which the defaults should be fine.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
This will install some new dependencies and set up the Cloudflare plugin.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Very nice!<\/p>\n\n\n\n
One Problem<\/h2>\n\n\n\n
If we open our Cloudflare dashboard, we will not see this new app present, and if we look in our terminal, we’ll see why.<\/p>\n\n\n\n
[build] \u2718 [ERROR] Types file not found at worker-configuration.d.ts.
[build]
[build]
[build]
[build] \ud83e\udeb5  Logs were written to \"\/Users\/arackis\/Library\/Preferences\/.wrangler\/logs\/wrangler-2026-07-12_23-14-01_652.log\"
[build]
\u2718 [ERROR] Error: Command failed with exit code 1: npm run build

  \u2718 [ERROR] Types file not found at
  worker-configuration.d.ts.


  \ud83e\udeb5  Logs were written to
  \"\/Users\/arackis\/Library\/Preferences\/.wrangler\/logs\/wrangler-2026-07-12_23-14-01_652.log\"

  > sveltekit-temp@0.0.1 build
  > wrangler types --check && vite build<\/pre>\n\n\n\n
The problem is the build<\/code> task Cloudflare scaffolded us.<\/p>\n\n\n
\"build\"<\/span>: \"vite build && wrangler types --check\"<\/span><\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
The problem is the latter piece: wrangler types --check<\/code>. This asks Wrangler to confirm that the generated typings are fully aligned with the application’s needs. In my experience, this is a fickle check that fails for reasons you may not care about, such as secrets not being properly declared in your Wrangler under certain circumstances, even if not directly accessed in code. To fix this error, you can run this:<\/p>\n\n\n
npx wranger types<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
This generates the types and passes the build. But I’d recommend just removing the wrangler types --check<\/code> from the build script.<\/p>\n\n\n\n
You’ll absolutely need to run npx wrangler types<\/code> to get typings generated for when you start using Hyperdrive, adding secrets, using Durable Objects, etc. But I wouldn’t fail the build step if your types aren’t completely up to date, especially if those mismatches don’t actually cause TypeScript errors.<\/p>\n\n\n\n
If your typings are not correct in a way that matters, you’ll see TypeScript errors pretty quickly, so the check was never all that valuable to begin with.<\/p>\n\n\n\n
And that’s that. Note that if you got this<\/em> error instead (or ever do get it)<\/p>\n\n\n\n
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.<\/pre>\n\n\n\n
Just rm -rf node_modules<\/code>, delete your lockfile, then re-run npm i<\/code>.<\/p>\n\n\n\n
Connecting GitHub<\/h2>\n\n\n\n
To enable easy deployments, let’s connect GitHub to our new app. We’ll go to our Cloudflare dashboard<\/a>.<\/p>\n\n\n\n
Find our app under Workers & Pages<\/strong>.<\/a><\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Go to the build<\/strong> section.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Then choose the right repo.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Now pushes to main<\/code> will automatically deploy to Cloudflare.<\/p>\n\n\n\n
Accessing Cloudflare Goodies from SvelteKit<\/h2>\n\n\n\n
Cloudflare manages the things we need, from secrets to Hyperdrive connection strings on the env<\/code> object. With TanStack we imported our env directly, via a special import.<\/p>\n\n\n
import<\/span> { env } from<\/span> \"cloudflare:workers\"<\/span>;<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
With SvelteKit, this env object is injected into a platform<\/code> object that shows up in server contexts. In fact, when we first ran npx wranger deploy<\/code> that command, it adjusted our typings for this.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
As we can see, env<\/code> now exists in the platform object. This is what is passed into server loaders like page.server.ts<\/code> for a route.<\/p>\n\n\n
import<\/span> type { PageServerLoad } from<\/span> \".\/$types\"<\/span>;\n\nexport<\/span> const<\/span> load: PageServerLoad = async<\/span> ({ platform, locals }) => {\n  return<\/span> {\n    value<\/span>: platform?.env.SECRET_1,\n  };\n};<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Other server-only locations, like API routes, also get env<\/code>. <\/p>\n\n\n\n
Note that this does\u00a0not<\/em>\u00a0work for universal loaders, since those also run on the client, and SvelteKit cannot expose things on this Cloudflare\u00a0env<\/code>\u00a0object to the client.<\/p>\n\n\n\n
Remote Functions<\/h2>\n\n\n\n
To access the Cloudflare env<\/code> object from a remote function, you import getRequestEvent<\/code>.<\/p>\n\n\n
import<\/span> { getRequestEvent, query } from<\/span> \"$app\/server\"<\/span>;<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Then call it as needed.<\/p>\n\n\n
export<\/span> const<\/span> getPosts = query(async<\/span> () => {\n  const<\/span> evt = getRequestEvent();\n  const<\/span> val = evt.platform?.env.SECRET_1;\n\n  return<\/span> [\n    \/* ... *\/<\/span>\n  ];\n});<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Databases and Hyperdrive<\/h2>\n\n\n\n
Hyperdrive is Cloudflare’s answer for connecting to a database from a cloud function that can spin up as often as needed, depending on your web application’s traffic.<\/p>\n\n\n\n
Since Cloudflare workers spin up quickly, on demand, to satisfy the requests they receive, they’re a poor candidate for opening a fresh TCP connection to your database for each request, since doing so would be slow and would risk overloading your database with more connections than it can support.<\/p>\n\n\n\n
We also can’t just expose a top-level db<\/code> object that’s exported from a module for reasons we’ll see shortly.<\/p>\n\n\n\n
Hyperdrive solves all these problems by giving you a pre-warmed connection pool.<\/p>\n\n\n\n
Setting up Hyperdrive<\/h3>\n\n\n\n
Go to the Cloudflare dashboard and, under Storage and databases, find the option Postgres & MySQL (Hyperdrive)<\/strong>.<\/p>\n\n\n\n
\"\"
Amusingly, the Hyperdrive in the menu option may be truncated due to how it’s displayed.<\/figcaption><\/figure>\n\n\n\n
Hit the connect to database<\/strong> button.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
You’ll be greeted with a few options for how to proceed. For this post, I’ll be using PlanetScale.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Follow the prompts, authenticate if needed, select your database, and most importantly, be sure to fill in your database name; you almost certainly do not want the default value of the postgres<\/code>.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Once complete, you should see a new Wrangler entry.<\/p>\n\n\n\n
\"\"
Screenshot<\/figcaption><\/figure>\n\n\n\n
That’s what mine looks like, and no, there’s nothing secret or private about that data. In fact, you’ll need it in your Wrangler file and committed to git if you want Cloudflare’s GitHub integration to work.<\/p>\n\n\n\n
Copy that into your Wrangler file and add a localConnectionString<\/code> for use during local development.<\/p>\n\n\n
{\n  \"hyperdrive\"<\/span>: [\n    {\n      \"binding\"<\/span>: \"HYPERDRIVE\"<\/span>,\n      \"id\"<\/span>: \"cabc3adcf4c44c03b55e2d17aaef7d99\"<\/span>,\n      \"localConnectionString\"<\/span>: \"postgresql:\/\/docker:docker@localhost:5432\/my_library\"<\/span>\n    }\n  ]\n}<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
You can now update your typings via npx wrangler types<\/code>.<\/p>\n\n\n\n
Connect to Hyperdrive<\/h3>\n\n\n\n
Now, via your same env<\/code> object, you can connect to your database through Hyperdrive.<\/p>\n\n\n
const<\/span> pool = new<\/span> Pool({\n  connectionString<\/span>: env.HYPERDRIVE.connectionString,\n});<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Managing Database Connections<\/h2>\n\n\n\n
As with TanStack, the same Cloudflare rules apply. We cannot keep a long-running I\/O object open between requests. Doing so would cause errors with Cloudflare; that’s why we can’t just export<\/code> a live db<\/code> object from a TypeScript module that contains a database connection when we use Cloudflare Workers.<\/p>\n\n\n\n
With TanStack Start we solved this with global request middleware, which ran once per request, and allowed us to open a database connection (via Hyperdrive), and put that db object on context, which is present in all server-only contexts.<\/p>\n\n\n\n
With SvelteKit, we can do similarly with a server hook. If we add a src\/hooks.server.js<\/code> file, the handle<\/code> function exported therefrom is invoked once per request<\/em>, making it a perfect place to set up our database connection.<\/p>\n\n\n
export<\/span> async<\/span> function<\/span> handle<\/span>({ event, resolve }<\/span>) <\/span>{\n  const<\/span> pool = new<\/span> Pool({\n    connectionString<\/span>: event.platform!.env.HYPERDRIVE.connectionString,\n  });\n  const<\/span> db = getDb(pool);\n\n  if<\/span> (event.url.pathname.includes(\"\/.well-known\/appspecific\/com.chrome.devtools\"<\/span>)) {\n    return<\/span> new<\/span> Response(null<\/span>, { status<\/span>: 204<\/span> }); \/\/ Return empty response with 204 No Content<\/span>\n  }\n\n  event.locals.db = db;\n\n  const<\/span> response = await<\/span> resolve(event);\n  return<\/span> response;\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
As you can see, we added our db<\/code> object to the event.locals<\/code> object. This is a standard feature with SvelteKit; in fact, there’s already a Locals<\/code> interface in the src\/app.d.ts<\/code> to hold any of these things we manually add.<\/p>\n\n\n
import<\/span> type<\/span> { DB } from<\/span> \".\/data\/db\"<\/span>;\n\ndeclare<\/span> global {\n  namespace<\/span> App {\n    interface<\/span> Platform {\n      env: Env;\n      ctx: ExecutionContext;\n      caches: CacheStorage;\n      cf?: IncomingRequestCfProperties;\n    }\n\n    \/\/ interface Error {}<\/span>\n    interface<\/span> Locals {\n      db: DB;\n    }\n    \/\/ interface PageData {}<\/span>\n    \/\/ interface PageState {}<\/span>\n  }\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
In server-only contexts like Server loaders, we can access our db<\/code> object<\/p>\n\n\n
export<\/span> const<\/span> load: PageServerLoad = async<\/span> ({ platform, locals }) => {\n  const<\/span> users = await<\/span> locals.db.select().from(user).limit(10<\/span>);\n\n  return<\/span> {\n    users,\n  };\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Similarly in Remote Functions, use the getRequestEvent<\/code> to get the request object, on which you’ll find the same locals<\/code> object, with the db<\/code> object.<\/p>\n\n\n
import<\/span> { eq } from<\/span> \"drizzle-orm\"<\/span>;\nimport<\/span> { getRequestEvent, query } from<\/span> \"$app\/server\"<\/span>;\nimport<\/span> { books as<\/span> booksTable } from<\/span> \"$drizzle\/schema\"<\/span>;\n\nexport<\/span> const<\/span> getBooks = query(async<\/span> () => {\n  const<\/span> evt = getRequestEvent();\n  const<\/span> books = await<\/span> evt.locals.db.select().from(booksTable).where(eq(booksTable.userId, \"106394015208813116232\"<\/span>)).limit(5<\/span>);\n\n  return<\/span> books;\n});<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Concluding Thoughts<\/h2>\n\n\n\n
I’m extremely excited about web development with Cloudflare’s platform. Workers are an outstanding, low-latency way to host web applications. The SvelteKit integration is great, and with just a few tricks, you can be up and running quickly.<\/p>\n","protected":false},"excerpt":{"rendered":"
In which Adam highlights the integration process and notes some challenges compared to the TanStack setup we covered shortly ago.<\/p>\n","protected":false},"author":21,"featured_media":10546,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"sig_custom_text":"","sig_image_type":"featured-image","sig_custom_image":0,"sig_is_disabled":false,"inline_featured_image":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_feature_clip_id":0,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_post_was_ever_published":false},"categories":[1],"tags":[334,501,386,3,161,162],"class_list":["post-10517","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog-post","tag-cloudflare","tag-cloudflare-workers","tag-database","tag-javascript","tag-svelte","tag-sveltekit"],"acf":[],"jetpack_featured_media_url":"https:\/\/i0.wp.com\/master.dev\/blog\/wp-content\/uploads\/2026\/07\/cloudflaresveltekit.jpg?fit=2000%2C1200&ssl=1","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/master.dev\/blog\/wp-json\/wp\/v2\/posts\/10517","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/master.dev\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/master.dev\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/master.dev\/blog\/wp-json\/wp\/v2\/users\/21"}],"replies":[{"embeddable":true,"href":"https:\/\/master.dev\/blog\/wp-json\/wp\/v2\/comments?post=10517"}],"version-history":[{"count":9,"href":"https:\/\/master.dev\/blog\/wp-json\/wp\/v2\/posts\/10517\/revisions"}],"predecessor-version":[{"id":10560,"href":"https:\/\/master.dev\/blog\/wp-json\/wp\/v2\/posts\/10517\/revisions\/10560"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/master.dev\/blog\/wp-json\/wp\/v2\/media\/10546"}],"wp:attachment":[{"href":"https:\/\/master.dev\/blog\/wp-json\/wp\/v2\/media?parent=10517"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/master.dev\/blog\/wp-json\/wp\/v2\/categories?post=10517"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/master.dev\/blog\/wp-json\/wp\/v2\/tags?post=10517"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}