enable getCloudflareContext to work in middlewares via a new enableEdgeDevGetCloudflareContext utility

[dario-piotrowicz]

This PR addresses the fact that getCloudflareContext can't work in dev (next dev) inside middlewares.

The issue is that those are always run in the edge runtime, although in production this is not a problem, in development (next dev) this prevents us from being able to import and use the wrangler node.js APIs from there.

I've tried to come up with some nice solutions but unfortunately I think the best we can do is basically borrow the setupDevPlatform next-on-pages idea and require users to call a function in their Next.js config file (this function then patches the vm.runInContext function to make the cloudflare context available in the "dev edge runtime").

So my solution here consist in having everything still working exactly the same for standard nodejs routes (if you don't call getCloudflareContext from a middleware you don't need to worry about anything), but for edge runtime routes/middlewares a utility called enableEdgeDevGetCloudflareContext needs to be invoked in the next config file.

We can properly document this, not invoking the function while invoking getCloudflareContext in a middleware also provides a helpful error that should hopefully make this very easy to follow:

Note

The Next.js docs say that middelwares currently run in the edge runtime, so maybe this can change in the future making this use case rarer

fixes #226

[changeset-bot]

🦋 Changeset detected

Latest commit: 1c298b1

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: 1c298b1

[vicb]

What about renaming this function to initOpenNextCloudflare()

I think it's easier for the user to understand as we expose lesst techincal details and we could add to this function later if needed.

[dario-piotrowicz]

mh... my idea was that people would not have to always include this but only when they face the cloudflare context in the edge runtime issue (a problem that can happen to a subset of users and one that hopefully can go away in the future if Next.js decides to support nodejs middlewares), that's why I made the name more specific

initOpenNextCloudflare() sounds like something they always need to have (similar to setupDevPlatform in next-on-pages)

we could add to this function later if needed.

That's true, but again your comment makes it sound to me like moving forward we'd want to recommend all users to include this, which I am not sure about 😕

So based on the above I think I do prefer something like enableEdgeDevGetCloudflareContext which makes it very clear to the user what this function does and when/why is needed besides making clear(er) that this is optional

But if you strongly prefer a generic name like initOpenNextCloudflare() I'd be ok with using that (although that's not my preference)

[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())