Enhanced Local Development Support for Cloudflare Bindings in Astro

[jplabsdev]

Summary

Introduce the ability to utilize Cloudflare bindings such as KV, DO, R2, Durable Objects, etc., during local development within the Astro framework.

Background & Motivation

Currently there's a gap in the local development workflow when using Astro with Cloudflare, specifically when attempting to access Cloudflare bindings. Presently, these bindings (KV, DO, R2, Durable Objects, etc.) are not accessible during local development and can only be accessed in a production build.

This lack of access during development inhibits developers from fully testing and integrating Cloudflare's functionalities into their projects before deploying to production. It leads to increased friction and inefficiency in the development process, as changes can only be tested in production builds. Consequently, developers are potentially deterred from fully leveraging the powerful features offered by the combination of Astro and Cloudflare.

Goals

• Enable local access to Cloudflare bindings within the Astro development environment. This includes KV, DO, R2, Durable Objects, and others.
• Enhance the local development experience of Astro with Cloudflare, making the integration seamless and efficient.
• Enable developers to thoroughly test their projects locally before deploying to production, minimizing errors and bugs.
• Facilitate the adoption of Astro for Cloudflare users, and vice versa, by making the integration between the two more accessible and user-friendly.

Example

The proposed solution should allow the following code to correctly return the Cloudflare bindings during local development:

import { getRuntime } from "@astrojs/cloudflare/runtime";
getRuntime(Astro.request);

Notes

• It's notable that Wrangler supports local development using tools like Miniflare and Workerd. This might suggest a potential path forward, not by having Astro mock Cloudflare, but rather by seeking closer integration with tools like Miniflare that are designed to provide a local development environment for Cloudflare Workers.

• This issue is not unique, as it has surfaced in several discussions within both the Cloudflare and Astro communities. There seems to be a recurring need for better local testing support for Cloudflare bindings within Astro.

• An additional point of consideration is the current Wrangler initialization process. As part of Wrangler v3, Astro is presented as a framework during setup. At the end of this process, developers are instructed to run astro dev via npm run dev, which calls wrangler pages dev with a proxy to astro dev. This flow can potentially give the impression that the bindings would work out of the box, which isn't the case currently. This part of the setup process could either be clarified or adjusted to reflect the true capabilities and limitations of the local development environment when it comes to Cloudflare bindings.

[aantipov]

Agree, with the notes above. Local development is very inefficient atm.
My current workaround is to run two processes in parallel:

1. nodemon -e astro,ts,vue,json --watch ./src --exec 'astro build' to rebuild the project on changes
2. wrangler pages dev ./dist --kv=MY_KV - a cloudflare dev server which auto-updates on changes to ./dist (and other relevant to Cloudflare Pages files like /functions/**/*)

The major drawback of that solution is that complete rebulding of the project (first process) takes too long ~12 sec.

Another possible solution to look into

I found out that Vite build supports --watch mode using rollup watcher under the hood which does exactly what we needs - efficiently rebuilds the project on changes.
It means we could throw away the nodemon solution and replace the first process with something like
astro build --watch

That would make the workaround a perfectly working solution which we could suggest in the Docs.

Unfortunately, atm the rollup watch mode doesn't work. When I specify the watcher

  vite: {
    build: {
      watch: {
        include: 'src/**',
      },
    },
  },

running astro build leads to an Error

I'm not sure, but this Error probably comes from the fact that SSR artifacts are moved by Cloudflare integration plugin to a different place - ./functions folder.

WDYT? Maybe there is a quick fix which would enable vite --watch option?

[alexanderniebuhr]

I doubt it is an issue with ./functions folder, because the issue also exists in advanced mode, that said the main issue is that --watch emits not the same than non watch.

[tom-huntington]

Cloudflare has recently provided proxy bindings https://github.com/james-elicx/cf-bindings-proxy

This library was written to accompany @cloudflare/next-on-pages, so that you can use bindings when developing Next.js apps locally through next dev.
It is intended to be used for frameworks that do not support Cloudflare bindings in a fast HMR environment.

GitHub issue here:
cloudflare/next-on-pages#271 (comment)

Current state of other frameworks

Also remix installed with `npm create cloudflare@latest` supports cloudflare bindings in development

// package.json
    "dev": "remix dev --no-restart -c \"npm run start\"",
    "start": "wrangler pages dev --compatibility-date=2023-06-21 ./public",

but astro wrangler pages dev --compatibility-date=2023-07-15 --proxy 3000 -- astro dev and svelte wrangler pages dev --compatibility-date=2023-07-15 --proxy 5173 -- npm run dev do not. Seems like the bindings aren't available with the --proxy flag

[alexanderniebuhr]

I'm in the process of developing a solution for this issue and would like to gather community feedback to prioritize features more effectively.

I'm considering two types of bindings, each with its own set of advantages. Both options are on the roadmap, but integrating both will require additional development time. I'd love to hear your thoughts on which feature should be prioritized. Your input will help guide the development process.

A) Mocked Bindings

What it is: An emulation of the bindings running locally, similar to the approach taken in Miniflare v2.
Advantages: Faster development and testing cycles; no need for connectivity or a remote worker.

B) Remote Bindings on Cloudflare (CF)

What it is: Proxied bindings on Cloudflare that run on Cloudflare's infrastructure and share the same data, similar to the approach taken by proxy/bridge solutions.
Advantages: More accurate data and testing.

[TheOtterlord]

Very cool to see! I'd probably prefer remote bindings first, because it's a complete environment, but it's honestly just awesome to see this 🙌

[alexanderniebuhr]

We've added support for local bindings in astro dev. Would appreciate testing & feedback!

https://docs.astro.build/en/guides/integrations-guide/cloudflare/#runtime

[aantipov]

You probably miss any of these files

I believe it's not documented

[e-jigsaw]

oookay?? put .dev.vars but Astro.locals.runtime is still undefined with astro dev. something missing?

[alexanderniebuhr]

If you can share a repro or example, I'll take a look for you! We should improve docs, PRs welcome!

[e-jigsaw]

I was trying it under existing astro project yesterday. I am working on monorepo(with pnpm workspaces), so I created a new astro project from scratch and tried it again, and now I can confirm that it's working.
I copied the code from existing project and investigated what might be causing it not to work, but even under the same conditions(same version, same adapter and plugins), existing project continues to have the same issue, while the one I created from scratch is working. It's weird. 🤔

Furthermore, it seems that .dev.vars is not always necessary. I confirmed that it works even without .dev.vars.

BTW, https://stackblitz.com/edit/stackblitz-starters-ttkpvr?file=src%2Fpages%2Findex.astro this code works on my local machine (worked not works well in StackBlitz I think). Nice work!

Thanks

[alexanderniebuhr]

Oh yeah I don't know about support on StackBlitz, probably it does not support miniflare/workerd easily.
If you find the reason why it does not work in a monorepo, I'm more than happy to try and get a fix for it, but I can't reproduce it.

[frankborden]

The setup works but each request from my browser tab seems to take some extra 200ms, and with the unbundled development and maximum connection limit it adds up fast. I have a small-ish page with a solidjs island and "local" changes the load time from 500ms to 15seconds.

astro.config.ts:

{
  // ...
  adapter: cloudflare({ runtime: { mode: "local" } }),
}

env.d.ts:

/// <reference types="astro/client" />

type ENV = {
  DB: D1Database;
  BUCKET: R2Bucket;
};

type Runtime = import("@astrojs/cloudflare").AdvancedRuntime<ENV>;

declare namespace App {
  interface Locals extends Runtime {}
}

[alexanderniebuhr]

Interesting, I've never have seen this. Can you make a reproducible example, which we can use to debug?

[frankborden]

https://github.com/frankborden/astro-cloudflare/

Created with:

> npm create astro@latest
> npm run astro add cloudflare
- configure astro config adapter with runtime "local"
- added worker.toml and .dev.vars
- set up env.d.ts

then npm run dev:

and with mode changed to "off":

So with just these few files the total time goes 84ms --> 709ms. Adding a client directive island with a component library etc really amplifies the effect.

[alexanderniebuhr]

Thanks will debug as soon as possible, currently just doing some other debugging.

[alexanderniebuhr]

@frankborden Just checking it. I was not able to debug this yet, but it might be related to: withastro/adapters#60

[yongyi520]

Hi,

2 questions

1. how do you access the local D1 data with astro dev?

It seems like whenever i tried to access it with astro dev command, it does not pick up any information from my D1 database, either remote or local

astro dev does not pick up the local data from .wrangler files for D1 data

When I use drizzle-orm to query the users for example, it says no table exist

2. How do you access remote D1 data with astro dev?
   I set up all the configurations from: https://artofsignals-web-astro.pages.dev/

• can confirm that I can get ENV variables

But there's no data in the D1 database somehow. Here's my wrangler.toml

[alexanderniebuhr]

Your config looks correct.
It's easier to open a support thread on Discord, but you can access the D1 database like this: https://github.com/withastro/adapters/blob/main/packages/cloudflare/test/fixtures/dev-runtime-pages/src/pages/d1.astro

[binyamin]

I had a similar problem. It seems Astro doesn't apply migrations like cloudflare does.

[alexanderniebuhr]

I had a similar problem. It seems Astro doesn't apply migrations like cloudflare does.

You should be able to apply those migrations using wrangler cli and then use them in Astro

[ammarriq]

Can we use cloudflare's production d1 and r2 bindings with HMR on astro dev?

[alexanderniebuhr]

I don't get the question, do you ask if you can use remote bindings?

[ammarriq]

Ya, I mean remote bindings in local development server

[alexanderniebuhr]

It is on the roadmap, but it is not supported yet

[ammarriq]

Do you have any idea how to sync wrangler local d1 tables with astro dev?

[alexanderniebuhr]

Can you explain what you mean?

[NuroDev]

By no means a complete solution but something that could be a stepping stone to make it easier to access Cloudflare bindings globally / outside of .astro files: As of wrangler version 3.24.0 (Release notes) you can now access local bindings via a new getBindingsProxy function.

Example

[[d1_databases]]
binding = "D1"
database_name = "D1"
database_id = "D1"
preview_database_id = "D1"

import { getBindingsProxy } from "wrangler";

const { bindings, dispose } = await getBindingsProxy();

const db = bindings.D1;
// 	  ^? D1Database

[aantipov]

Thanks for the idea. I used it in my tests to access the bindings and it works just great!

[alexanderniebuhr]

We'll implement the getBindingsProxy() natively in an upcoming version of the adapter.

[tom-huntington]

I have two local sqlite files

• one that npx wrangler d1 execute created and accesses
• another that astro accesses

❯ ls .wrangler/state/v3/d1/miniflare-D1DatabaseObject/
0a7ef88a919d8075ad9accd397b88822659af4c7329d4875c4d20d0bb34fbce1.sqlite
e7352547963de7050bd7d94658afc4fe78b61811b7815da12d90be8e863abf4d.sqlite

Can I get astro and wrangler to access the same local file?

These seem to be related:
#590 (reply in thread)
#590 (comment)

[alexanderniebuhr]

There is preview_database_id (https://developers.cloudflare.com/workers/wrangler/configuration/#d1-databases). Which should allow you to use one wrangler.toml

[alexanderniebuhr]

But we do plan to release an update soon, which would allow you to set your own database_id to the local runtime

[adarah]

Is there a workaround for now?
How can I find out the database_id of the sqlite file generated by astro dev and the used by wrangler?

[adarah]

I found a workaround. In wrangler.toml, set your preview_database_id to be the same value as the name of the binding inside astro.config.mjs.

For example:

  // astro.config.mjs
  adapter: cloudflare({
    runtime: {
      mode: 'local',
      type: 'pages',
      bindings: {
        // Binding's name, choose whatever you want
        "D123": {
          'type': 'd1',
        }
      }
    }
  }),

# wrangler.toml

[[d1_databases]]
# Set this to whatever name you chose in astro.config.mjs
binding = "D123"
database_name = <your_db_name_here>
database_id = <your_production_id>
# Set this to whatever name you chose in astro.config.mjs
preview_database_id = "D123"

Now you can run npx wrangler d1 execute --local --file=foo.sql and the changes will be in the
same sqlite file that astro dev uses.

I found out by poking around the adapter's and miniflare internals, but I don't know how brittle this setup is, use at your own risk

[alexanderniebuhr]

This is actually what we do suggest in multiple places already.

[alexanderniebuhr]

This proposal is effectively implemented. We'll continue to invest time into making it more robust and add more bindings over time. We also are actively working to try using a real Cloudflare runtime to get a 1:1 dev/prod match.

If you find any bugs/issues please open an issue at https://github.com/withastro/adapters/issues
If you have questions or need help please join us in our Support channel on Discord https://astro.build/chat

[AVGVSTVS96]

Does this work for static sites or just SSR? I have a static site deployed to pages with a GPT chat page running on a cloudflare function and am trying to figure out how to run a local dev mode with access to my function. In the Astro Discord server I was told that this adapter only works for SSR sites, so I guess I'm out of luck?

I did try enabling platformProxy anyway but had no luck running my function locally. I am only able to do so with the deprecated -- <command> - wrangler pages dev -- bun run dev.

Is there another solution for a static site or am I misunderstanding something? I suppose I'd have to create my own script using getPlatformProxy? Am I right in my understanding that this would allow me to run my function locally? I'm still new to programming and cloudflare so any help would be greatly appreciated!

This is my astro.config.ts:

export default defineConfig({
  adapter: cloudflare({
    runtime: { 
      mode: 'local',
    },
    platformProxy: {
      enabled: true,
    },
  }),
  output: 'server',

I tried runtime with mode set to local but this doesn't seem to be a valid option. It didn't work regardless.