introduce new initOpenNextCloudflareForDev utility and make getCloudflareContext synchronous

[dario-piotrowicz]

This PR introduces a new initOpenNextCloudflareForDev utility to add to the Next.js config file that makes the getCloudflareContext work in middlewares (or more generally, the edge runtime) during local development (via next dev)

It getCloudflareContext has also been converted to be synchronous

For more details see the changeset file: .changeset/chilly-dryers-begin.md

---

fixes #137
fixes #226

[changeset-bot]

🦋 Changeset detected

Latest commit: cf9b45e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@opennextjs/cloudflare	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in Stackblitz

pnpm add https://pkg.pr.new/@opennextjs/cloudflare@265

commit: cf9b45e

[vicb]

Thought: Maybe we can getPlatformProxy(...) in initOpenNextCloudflare() so that getCloudflareContext could be made sync?

This comment says "the function is an async one but it doesn't need to be awaited", it might be nice to add the rationale if we add the implementation to our repo.

[dario-piotrowicz]

Thought: Maybe we can getPlatformProxy(...) in initOpenNextCloudflare() so that getCloudflareContext could be made sync?

Yes, we could, this would mean that everyone would always have to call initOpenNextCloudflare(), I mentioned in my comment that we don't need to go that route as not forcing users to do that might provide a better DX

but again if you strongly prefer us to go that route I'm ok with it

This comment says "the function is an async one but it doesn't need to be awaited", it might be nice to add the rationale if we add the implementation to our repo.

Yes, given the implementation of next dev, it takes some time from when Next.js loads the config and when it serves the app, we did see that that amount of time is enough for the proxy to be ready in time. It would require very little changes here, just removing the on-the-fly proxy generation from getCloudflareContext and changing the function signature to be sync

[dario-piotrowicz]

@vicb I've addressed all the feedback, the only thing left is to decide whether we want to force this sort of thing via a initOpenNextCloudflare() and potentially convert getCloudflareContext to be sync or not

up to you, just let me know if you want to me make the change 👍
(it doesn't really take much effort to do code-wise, it's just a matter of DX)

[vicb]

@vicb I've addressed all the feedback, the only thing left is to decide whether we want to force this sort of thing via a initOpenNextCloudflare() and potentially convert getCloudflareContext to be sync or not

up to you, just let me know if you want to me make the change 👍 (it doesn't really take much effort to do code-wise, it's just a matter of DX)

Give me some time to think about it, I'm not settled.

Some thoughts I have for now about initOpenNextCloudflare()

Cons:

initOpenNextCloudflare() always need to be called but we can have an error message when it's not called

Pros

• I think it's easier to document (i.e. "always call initOpenNextCloudflare()" vs " call enableEdgeDevGetCloudflareContext if you call getConflareContext from a middleware"). I think Vercel is working on the ability to run middlewares on the node runtime and we will add support for routes on the edge runtime at some point. It will make it harder to explain
• I think it's easier for users to understand (They don't have to understand what "EdgeDev" is)
• We could setup the cloudflare context in there so that getCloudflareContext() becomes sync. A lot of user are complaining about that on Discord and GH - See how it impacts us in the KVCache
• Calling the init on a per need basis (vs always calling initOpenNextCloudflare()) could introduce unrelated test failures when you start adding the call - i.e. how you had to bump the timeout in this PR

[dario-piotrowicz]

Give me some time to think about it, I'm not settled.

Some thoughts I have for now about initOpenNextCloudflare()

...

Well there is only one con and many pros, I dislike that we need to then ask users to always call the function, but given the benefits it does seem like it might be worth it

By the way, either way I am not too convinced about the name since this is a dev (next dev) only thing and in my opinion extremely unlikely to be useful outside of dev (because we have other places where we could accept options/tweak things, like in our templates, in the open-next config, etc...) for this reason I would really prefer it if the function had dev somewhere in its name (e.g. initOpenNextCloudflareForDev())

[vicb]

Cant't wait for this PR to get in 🎉

[vicb]

should this be an API route returning JSON and testing array.toContain(...) so that order does not matter?

[dario-piotrowicz]

the dependence on the ordering can also easily be fixed by sorting the keys: 6006cf2
(I also had to filter the variables to avoid the ASSETS issue)

I am happy to also add (or instead) an API route and do array.toContain whatever you prefer, I'm happy with anything 🙂

[vicb]

I think API + array.toContain would be simpler but the code is already here and working so up to you.

[dario-piotrowicz]

I just simplified the test there: 6e6d076

All we care about here is checking that we can get access to the cloudflare context in the middleware, regarding the context variables we already test that they are present here:

opennextjs-cloudflare/examples/api/e2e/base.spec.ts

Lines 18 to 26 in a18f826

	test("returns a hello world string from the cloudflare context env", async ({ page }) => {
	const res = await page.request.get("/api/hello", {
	headers: {
	"from-cloudflare-context": "true",
	},
	});
	expect(res.headers()["content-type"]).toContain("text/plain");
	expect(await res.text()).toEqual("Hello World from the cloudflare context!");
	});

So I think that testing the existence of the env object is enough here (and if we wanted to have a comprehensive e2e test for getCloudflareContext with all the various variables, cf, etc... that should probably live in the api example), what do you think?

[vicb]

suggestion: maybe start simple with the TL;DR and add details (or not) in following paragraph.

something like

`initOpenNextCloudflareForDev()` must be called from the [Next.js config file](https://nextjs.org/docs/app/api-reference/config/next-config-js) so that your bindings can be accessed  using `getCloudflareContext()` when running the Next.js development server (`next dev`).

`getCloudflareContext` is now sync.

[dario-piotrowicz]

the changeset title is already a good TL;DR, isn't it?

I think I don't fully understand what you're suggesting, if you want feel free to suggest a code change or to push on the branch

[vicb]

I think the change set should first highlight what is most important for the users:

1. that the init function must be called from the config
2. that getCloudflareContext is sync

IMO mentioning the edge runtime of our recommendation could be pushed down or moved to the doc site.

[dario-piotrowicz]

I've updated the changeset I hope the new version works for you

[vicb]

I've pushed the kvCache update

[vicb]

Could you please update the README and opennext.js.org to tell users to add the init?

[vicb]

Could you please update https://github.com/opennextjs/opennextjs-cloudflare/blob/main/packages/cloudflare/README.md

Either to ask the user to add the call to the init function
Or if you can update opennext.js.org, remove the content and link to the doc site (I was mostly using the content for the experimental branch when the experimental features were not documented anywhere else)

Great stuff, thanks 🚀

[vicb]

maybe:

Suggested change

	Also makes `getCloudflareContext` synchronous, so `await`ing such function is no longer necessary.
	Also makes `getCloudflareContext` synchronous.

[vicb]

maybe:

Suggested change

	* (Currently all the setup that this function performs is making sure that `getCloudflareContext` works as intended,
	* in the future mode improvements might be added)
	*

[vicb]

Note: we should make sure not to print this when using wrangler - that's #229 that we should tackle in a follow up PR.

[vicb]

what about cutting a minor?

It would signal users that there are changes:

• calling theinitOpenNextCloudflareForDev function,
• getCloudflareContext becoming sync

If you do that, please also prepare:

• a PR to update the c3 template to 0.4.x
• a PR to the doc site (copy the current content to 0.3, add the changes in the current content, add a migration from 0.3)