[Pages] update bindings in your Astro application

[ntsd]

• update astro binding docs since @astrojs/cloudflare/runtime is deprecate
• reference type for @cloudflare/workers-types
• add access kv in astro component example
• add learn more about Cloudflare runtime link to Astro doc

[alexanderniebuhr]

@ntsd you were faster than me. Thanks for that!
I'm the Astro maintainer, who was developing the change. I'll just added some notes!

[dario-piotrowicz]

Thanks a lot @ntsd! 😃 (and thanks a lot @alexanderniebuhr for your help as well of course! 😄)

I think that technically the additions all look great, but I think we have a problem with the flow of the bindings section

Here is how the section looks like with the code removed:

I personally think that this reads quite poorly and doesn't have a clear flow (we start mentioning bindings as we do for all guides, then we move to Astro endpoints (which is ok), but then jump stright to the env.d.ts file, then implement an endpoint and at the end mention Astro components as an aftertought), I think that we should update it to a have a structure along the lines of:

A binding allows your application to interact with Cloudflare developer products, [...]

In Astro you can use bindings in Astro components and API routes by using the `context.local` [...]

Let's see an example with typescript:

First we need to update the `env.d.ts`: [...]

And then we can use the KV in our Astro component: [...]

and in our API route: [...]

What do you think?

[dario-piotrowicz]

Suggested change

	In Astro you can add server-side code via [endpoints](https://docs.astro.build/en/core-concepts/endpoints/), in such endpoints you can then use the `context.local` from [Astro Middleware](https://docs.astro.build/en/guides/middleware/) to access Cloudflare's environment and consecutively any bindings set for your application.
	In Astro you can add server-side code via [endpoints](https://docs.astro.build/en/core-concepts/endpoints/), in such endpoints you can then use the `context.local` from [Astro Middleware](https://docs.astro.build/en/guides/middleware/) to access the Cloudflare runtime which amongst other fields contains the Cloudflare's environment and consecutively any bindings set for your application.

But I am not 100% sure, I am wondering if mentioning the runtime part makes things more clear or just adds more noise 🤔

[dario-piotrowicz]

PS: why I think that a restructure is needed here, before I think that the bindings were only accessible in endpoints so that's why we were only mentioning those and the section was ok, but now that bindings are also available in Astro components then I think that the section needs to be a bit restructured because it's very much endpoints-based (and again it feels all a bit assembled together without a good structure).

[ntsd]

Hi @dario-piotrowicz ,

I did update the PR following your suggestion, thanks a lot.

Actually, I think this includes the Cloudflare runtime functions, I'm not sure that Binding or Cloudflare runtime is the bigger topic.

Maybe a structure like this, I can write all if you want.

Access to Cloudflare Runtime
- Environment Binding
- Get incoming request data
- Caches

[dario-piotrowicz]

Thanks a lot for the changes @ntsd, looks good to me 😄

(I've just left a couple of minor suggestions)

[dario-piotrowicz]

Hi @dario-piotrowicz ,

I did update the PR following your suggestion, thanks a lot.

Actually, I think this includes the Cloudflare runtime functions, I'm not sure that Binding or Cloudflare runtime is the bigger topic.

Maybe a structure like this, I can write all if you want.

Access to Cloudflare Runtime
- Environment Binding
- Get incoming request data
- Caches

Yeah good point @ntsd, thanks for bringing it up 🙂

The bindings section is there as that is like the basic/fundamental piece that generally you'd probably want to know about, and most modern framework guides here do have such a section.
I do agree that having an explanation of the rest of the Cloudflare runtime would be beneficial, but I am not sure if these guides should include various details or they should just refer back to the official Astro docs pages (as in, adding a To learn more about the Astro Cloudflare runtime see: https://docs.astro.build/en/guides/integrations-guide/cloudflare/#access-to-the-cloudflare-runtime sentence and making sure that the Astro docs mention everything that's needed).

I'm not really sure, I'd be keen to see what @deadlypants1973 thinks.
(Thinking about it, maybe by following such logic maybe we should even not include binding sections in any or our guides but just always refer back to the official framework docs? 🤔)

(In any case I think we could/should merge this PR as is (plus PCX tweaks if needed) and potentially handle the above in a followup PR)

[alexanderniebuhr]

Not sure, but in case it's relevant, https://github.com/withastro/astro/pull/8655/files will land in the next release (prob, this week)

refer back to the official Astro docs pages (as in, adding a To learn more about the Astro Cloudflare runtime see: https://docs.astro.build/en/guides/integrations-guide/cloudflare/#access-to-the-cloudflare-runtime sentence and making sure that the Astro docs mention everything that's needed).

@dario-piotrowicz I agree, it would be up to date 99% of the time. The Astro team can only maintain their own docs, while we try to open PRs for 3rd party docs, it's hard to keep track of them & update them everytime.

[ntsd]

@dario-piotrowicz @alexanderniebuhr Agree with adding the link to Astro docs. I updated the PR by adding the last sentence sent to the Astro doc.