Unify file writing across ssg & dev/ssr

[altano]

The Problem

The existing integration API is making simple file writing difficult.

If you want to create an integration that writes a file you currently have to do two completely different things to make it work in both ssg and dev/ssr modes. An example of this is the @astrojs/image integration that

• for ssg, hooks into 'astro:build:done' to call writeFile for every image and
• for dev/ssr, hooks into 'astro:config:setup' to injectRoute and creates an endpoint that can return a Response on demand.

Saying "I want to generate some files and write them to disk" should not require all this work. And, that work isn't obvious when reading the integration API documentation. There are many integrations, e.g. astro-seo-images, that just hook into 'astro:build:done' and don't support dev/ssr at all.

Here are the problems I can think of, off the top of my head, that having a split API causes:

• Integrations won't implement both, making them only support whichever mode the author wants (e.g. ssg-only with no dev support)
• Having two APIs means they will just keep diverging, e.g. I recently added custom encoding support for non-html routes, but that only works in ssg mode
• It's hard to add abstractions to both APIs. E.g. I recently proposed a file cache but that would be hard to make work with both ssg and dev/ssr.
• The existing integration APIs don't allow basic operations like deleting files/pages, e.g. astro-seo-images takes page routes as input so that it can screenshot the page. But, it has no API to cleanly access that page and it has no API to delete the page once it generates an image, so the page ends up in the final build output.

Things to Support

I can think of two types of file-generating integrations that we'd want to support:

1. Integrations like @astrojs/image where the main entry point is a component. When the component is rendered it possibly needs to generate file[s]. These have arbitrary inputs (the props to the component) that can be anything.
2. Integrations like astro-seo-images where the input is an existing static file or an Astro page (html or non-html). These integrations might transform the inputs (e.g. compress images) where the output replaces the input. They might be purely additive, where a new file is written but the old file is untouched.

Solution Brainstorming

I feel confident I understand the problem but I don't at all feel comfortable proposing a specific solution. I don't really know Astro/Vite well enough. I can think out loud though:

For case 1 above, perhaps Astro can provide a file-generating integration API? It would do what @astrojs/image does internally: Astro can call writeFile in ssg and provide an endpoint in dev/ssr. All it would ask of the file integration is to provide buffers. That would handle the component-generating-static-files case.

For the second case, Astro would need to provide an API that allowed the integration to specify bunch of options:

• What files or pages they take as input (is this just getStaticPaths?)
• Whether they transform the source material, e.g. whether those inputs should be deleted or not (e.g. remove the input file from the build output, or remove/deleteRoute the page)
• A callback function that takes the input and returns a Response
  • There can be Response metadata, e.g. a cache key to enable caching of files

In both cases, Astro has to own enumerating all the inputs and calling the integration to generate files for those inputs, in all modes: ssg/dev/ssr.

[altano]

PR with some of the ideas above (less ambitiously implemented) can be found here: withastro/astro#4765