A new compiler for Astro

[Princesseuh]

• Start Date: 2026-05-05
• Reference Issues: A new compiler for Astro #1306
• Implementation: https://github.com/withastro/compiler-rs
• Author: @Princesseuh

Summary

Create a new compiler for Astro, without HTML correction, easier to maintain, more correct, and adopt it as the official Astro compiler going forward.

Background & Motivation

The Astro compiler turns .astro files into JavaScript modules, for Astro to then execute.

The current implementation, written in Go, has been serving us since Astro 0.21 After several years of production use, a few things have become clear:

• Maintenance has stalled. The codebase is hard to onboard onto, and the team has not been successful in finding contributors (internal or external) who are both willing and able to maintain Go code. Issues sit open for long periods, because nobody on the core team is comfortable owning fixes there.
• Proper architecture and tooling is needed. The Go compiler uses its own HTML parsing, does its TS understanding itself, has its own (although forked from esbuild) CSS parsing, etc. A lot of tooling now exists that we can rely on instead of owning ourselves, especially in the Rust ecosystem, reducing our surface area to cover ourselves and reducing bugs.
• HTML correction has been a long-standing source of bugs. The behavior surprises users, makes debugging harder, and is increasingly out of step with how modern frameworks treat author-written markup.
• JSX-style strictness is often more valuable than HTML's behavior. HTML is on purpose lenient with regards to unclosed tags and attributes, but the vast majority of the time this only results in broken or unexpected results in the browser.

Goals

• Create a new official compiler for Astro.
• Make the new compiler maintainable by the current team and approachable for new contributors.
• Reach feature and behavior parity with the current Go compiler for everything that is not explicitly being dropped, so that existing Astro projects continue to build without needing changes in most cases.
• Match or exceed the current compiler's performance on real-world Astro projects.
• Run in every environment Astro itself supports today.
• Supports semantically invalid HTML structures, but reject (what is commonly perceived as) syntactically invalid ones.

Non-Goals

• HTML correction is intentionally being dropped. The new compiler will not silently rewrite author markup to be "valid HTML". Behavior changes from this will be documented as part of the migration, but reintroducing correction is out of scope.
• Supporting syntactically invalid HTML. Unclosed tags like <div>Hello will now results in an error, like they would in JSX, so will unterminated attributes: <div class="Hello >World</div>
• No new language features. This proposal is specifically about replacing the implementation, not about extending the .astro syntax. Any syntax-level changes are separate proposals.
• TSX output. A compiler for Astro itself and a compiler for the TSX output needed by the language server has different requirements. As such, I propose to focus this new effort on what's needed for runtime, and consider more relevant and suited alternatives for the language-server down the line.
• AST parity. The Go compiler returned its own AST format, completely different from other tools. As part of relying on existing libraries, we could now return a more standard AST.

[delucis]

TSX output. A compiler for Astro itself and a compiler for the TSX output needed by the language server has different requirements. As such, I propose to focus this new effort on what's needed for runtime, and consider more relevant and suited alternatives for the language-server down the line.

Could you expand on this? What will the language server use? Will it continue to use the Go compiler?

[Princesseuh]

TSX output. A compiler for Astro itself and a compiler for the TSX output needed by the language server has different requirements. As such, I propose to focus this new effort on what's needed for runtime, and consider more relevant and suited alternatives for the language-server down the line.

Could you expand on this? What will the language server use? Will it continue to use the Go compiler?

Yes, for now.

The architecture used by both the Go and Rust compiler is good for outputting runtime code, but bad for outputting the partial TSX needed by the language-server. You can somewhat make it work (like the Go compiler did, and the Rust compiler could), but you'll always have a lot of issues.

For instance, auto-import is often flaky because the outputted TSX has to be weirdly corrected because of the compiler's understanding of partial code. This is inherently not fixable in either the Go or Rust compiler, you need a completely different kind of lexing, parsing, printing etc.

In recent times, Biome's parser has gained pretty good support for Astro files, and it is perfect for outputting TSX for the language-server, perfectly handling incomplete files, unclosed tags etc. This comes with some other costs (performance is lower, most notably, but also the ecosystem is all built around oxc), but it'd still be the best bet there, so I'd like to use that instead

[Princesseuh]

This is now in Stage 3!!! #1357