Standalone .astro file usage

[florian-lefebvre]

Body

Summary

Be able to easily use .astro files in non Astro projects.

Background & Motivation

A huge part of Astro's success can be attributed, I think, to the .astro file format (Recently a proper spec was made: withastro/compiler#1138). It's super easy to reason about and it's powerful.

However .astro files are currently only usable in Astro projects. But I think some projects would be happy to adopt purely as a file format, without bringing all of Astro alongside. For example, usage in pure Vite projects for more custom setups.

I'm also wondering if that could help with / replace the Container API.

Goals

• Expose an easy way to consume .astro files in Vite
• Expose an easy way to render .astro files

Example

We already have the compiler which is great! I'm suggesting we have a new vite-plugin-astro package (already experimented with it in withastro/astro#17094) as well as a package purely usable for rendering (including jsx rendering, this way it also covers types).

Most of the work is extracting stuff from core into public packages, then use these packages back in core.

[matthewp]

The biggest hurdle here is that .astro components are heavily tied to the runtime in a way that's difficult to extract. For example, islands are the most popular feature of Astro components, but you can't just throw this new plugin into a regular Vite project and get islands. It's necessary to provide the metadata that allows the runtime to know what islands exist and how to wire them up. There other things like this, styles are another thing.

I'm sure it's possible to untangle all of these things into an API that makes sense and is nice, but it's a lot of work. Looking at the prototype, what's missing are tests / examples that show using this outside of Astro. I'd be curious to see what that looks like. Figuring that part out would also unearth all of the parts that need to be pulled into the plugin (which is likely quite a bit, including a lot of the build, but that's ok of course).

[florian-lefebvre]

Yeah true, I've been thinking about this too. I guess the question woukd be: what belongs to .astro as a format or Astro as a framework? Which in reality has more implications, like: if it's a framework feature, does it belong in the compiler itself? Or does the compiler needs to expose an API to add stuff to it? Definitely not easy.

I have some kind of example at https://github.com/web-runes/vite-deploy/pull/47/changes but it's not really useful because it completely lacks the runtime implementation

[matthewp]

I think that depends on the feature and user expectations. Things like tsconfig aliasing is a feature of the framework and I wouldn't expect it to happen in this new plugin. I don't think being able to run any Astro file unmodified should be a goal here. But islands are the biggest feature of Astro components, so I definitely would expect those to work.

[florian-lefebvre]

I wast thinking about view transitions directives

[matthewp]

I would expect those should probably work since they are not tied to the ClientRouter component.

[matthewp]

Note that this concern is probably less true after the astro/fetch refactor.

[matthewp]

Astro as composable Vite plugins

Summary

Split astro into a set of independently usable Vite plugins — the .astro language, a pages router, and one plugin per feature — and rebuild the astro CLI as a composition of them.

Background & Motivation

Astro has become a collection of strong primitives — the .astro component language, islands, file-based routing, content collections, actions, i18n, sessions, image optimization, fonts — delivered as a single package with a single CLI.

However currently using this is an all-or-nothing proposition. If you want to use something else for a particular task you can, but you will incur the cost in package size nonetheless, which often pushes you towards using the built-in primitives. For Astro this presents a risk, if the perception of any of the parts is negative it can lead to negative feelings about the framework as a whole.

Additionally, many projects do not start out using Astro, but they do start out using Vite. Making Astro available as a plugin lets those people upgrade to use Astro without rewriting their entire application.

Goals

• Make it possible to use Astro in all Vite projects, and to use Astro itself in Vite+.
• Make it possible to use Astro islands in non-Astro projects, like in a mostly-api app that uses Hono.
  • Related, using Astro for the "marketing site" of a SPA that is using something else.
• Allow sites to choose non-Astro based tools when Astro tools already exist; for example building an Astro site that includes an RPC library, such as TRPC without the burden of also having Astro Actions installed.
• Reducing the overall filesize of typical Astro applications.
• Set us up for Astro 8 in which we could trim the astro package itself.

Non-goals

• Changing what astro does for existing users, the .astro language, the integration API, or the adapter API.
• Replacing integrations with Vite plugins. Integrations remain the extension mechanism of the full framework; the plugins are a lower layer the framework is built on.
• Extracting features into framework-agnostic cores (e.g. content collections for non-Astro use). Possible later; out of scope here.
• Supporting bundlers other than Vite. There will be a separate packgae for the runtime so this is theoretically possible but not something worth pursuing.

Example

Just the language — Astro components rendered by Hono routes, with a React island:

// vite.config.js
import astro from '@astrojs/vite-plugin-astro';
import react from '@astrojs/react/renderer';
export default { plugins: [astro({
 renderers: [react()]
})] };

// src/app.ts
import { renderToResponse } from '@astrojs/runtime';
import Page from './components/Page.astro';

const app = new Hono();

app.get('/hello/:name', (c) => renderToResponse(Page, { props: { name: c.req.param('name') } }));

Pages — a site with file routing and nothing else:

import astro from '@astrojs/vite-plugin-astro';
import pages from '@astrojs/vite-plugin-pages';
export default { plugins: [astro(), pages()] };   // vite dev / vite build

Pick your features:

export default {
  plugins: [
    astro({ site: 'https://example.com' }),
    pages({ output: 'server' }),
    content(),
    markdown(),
    assets(),
    i18n({ defaultLocale: 'en', locales: ['en', 'es'] }),
    // no actions, no sessions, no toolbar
  ],
};

[florian-lefebvre]

I think the proposal is great 👍 and can probably ask TSC for a vote

[florian-lefebvre]

Approving for stage 2

[ascorbic]

This is great. Approving for stage 2

[ematipico]

Approving for stage 2

[matthewp]

This has been moved to stage 2: #1450

[matthewp]

#1450