Add Incremental Static Regeneration support for the Netlify's on-demand builders

[lilnasy]

Changes

• Closes Add TTL support for Netlify adapter for On Demand Builders #6654
• Previous Effort Add ttl option to netlify adapter for builders #6219
• Exposes Netlify on-demand builder's ttl configuration as a local
• Usage

• Adding types

• Available only when builders mode is enabled.

Testing

Added a fixture

Docs

Added to the package README

[changeset-bot]

🦋 Changeset detected

Latest commit: e51d701

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

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

[ematipico]

locals in an Astro component are read-only properties and you won't be able to set anything like this. The only place where you can write stuff in the locals is inside the middleware.

[natemoo-re]

locals in an Astro component are read-only properties and you won't be able to set anything like this. The only place where you can write stuff in the locals is inside the middleware.

Ah, that is a very important limitation of this API! Should we use a Proxy during astro dev that throws an error when users attempt to assign a value via set()?

[lilnasy]

@ematipico It works. Do you mean it should be read-only?

[lilnasy]

There is no official word of this outside of Netlify's API reference, but most of on-demand builders' functionality has been brought into other functions.

I found this out from a Netlify support thread, and the gist of it is, its use case has become niche: single cache store used globally - instead of per-region, as it is for normal and edge functions.

This PR could still be merged for feature-completeness. I will be updating the Netlify part of the ISR guide to use Cache-Control headers instead.

[ematipico]

@ematipico It works. Do you mean it should be read-only?

@lilnasy

Yes. Astro.locals must be read-only. That's what dev and node adapter do in the first place. Making Astro.locals writeable in the netlify would cause different behaviour in the APIs. I understand that it works, but that's not how the APIs should be crafted.

locals are meant to be written in the middleware layer.

locals in an Astro component are read-only properties and you won't be able to set anything like this. The only place where you can write stuff in the locals is inside the middleware.

Ah, that is a very important limitation of this API! Should we use a Proxy during astro dev that throws an error when users attempt to assign a value via set()?

We don't use Proxy in core, but yeah, that's another way to do it.

[lilnasy]

@ematipico Considering that serializability restrictions are relaxed, maybe a setTtl() function is more appropriate.

---
Astro.locals.netlify.builders.setTtl(45)
---
<h1>Astro</h1>

[ematipico]

@ematipico Considering that serializability restrictions are relaxed, maybe a setTtl() function is more appropriate.

---
Astro.locals.netlify.builders.setTtl(45)
---
<h1>Astro</h1>

Yeah that's way better I'd say

[lilnasy]

I would like a pointer for adding a no-op for dev.

I see dev mode support was added in #7385, but the two tests added in it are for build.

[ematipico]

I would like a pointer for adding a no-op for dev.

I see dev mode support was added in #7385, but the two tests added in it are for build.

Yeah, the PR title is misleading (it was picked up from a third-party contributor).

I am not sure how we can fix this case, with the code we have now. I think Astro should provide a safe way to retrieve the "adapter runtime", and if the adapter doesn't provide any runtime, it should be undefined.

E.g.

const runtime = Astro.locals.getAdapterRuntime();
if (runtime) {
	runtime.setBuilderTtl(45)
}

The downside is that these kinds of things are only visible when building the project and deploying it.

[lilnasy]

Should I add a import.meta.env.PROD check in the docs for now?

[ematipico]

Looks good!

[ElianCodes]

A couple of small changes, but after applying, good to go!

[ElianCodes]

Good to go!