Astro Compiler

https://github.com/withastro/compiler-rs
Admin
Astro Compiler transforms .astro component files into JavaScript modules and ASTs using a...
Tokens:6,183
Snippets:92
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install @astrojs/compiler-rs

Source: https://github.com/withastro/compiler-rs/blob/main/packages/compiler/README.md

Install the Astro compiler package for Node.js via npm.

```bash
npm install @astrojs/compiler-rs
```

--------------------------------

### Top-level return in component script

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Example of using 'return' at the top level of the component script to redirect unauthenticated users.

```astro
---
import { getUser } from "../lib/auth.js";

const user = await getUser();
if (!user) {
  return Astro.redirect("/login");
}
---
```

--------------------------------

### Script tags with attributes

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

When any attributes are present, the content follows standard HTML script element rules. This example shows three script tags with different attributes: defer, type="module", and type="application/json".

```astro
<script defer>
	// JavaScript
</script>

<script type="module">
  // JavaScript module
  import { foo } from "./foo.js";
</script>

<script type="application/json">
  { "key": "value" }
</script>
```

--------------------------------

### Build commands for the Astro compiler

Source: https://github.com/withastro/compiler-rs/blob/main/CONTRIBUTING.md

Commands to build the NAPI native addon, astro2tsx, the TypeScript package, and everything. Run these from the repository root.

```shell
# Build the NAPI native addon (debug mode)
pnpm run build:napi

# Build the astro2tsx (debug mode)
pnpm run build:astro2tsx

# Build the TypeScript package
pnpm run build:compiler

# Build everything
pnpm run build:all
```

--------------------------------

### Minimal .astro file with frontmatter, template, and style

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

A minimal .astro file with a component script, a template using a variable, and a style block.

```astro
---
const greeting = "Hello";
---

<h1>{greeting}, World!</h1>

<style>
  h1 { color: royalblue; }
</style>
```

--------------------------------

### Attribute shorthand

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Shows the shorthand syntax where {prop} is equivalent to prop={prop}.

```astro
<Component {prop} />
<!-- equivalent to: -->
<Component prop={prop} />
```

--------------------------------

### Run TypeScript tests with pnpm

Source: https://github.com/withastro/compiler-rs/blob/main/AGENTS.md

Commands to run TypeScript tests. First build the NAPI addon with `pnpm run build:napi`, then run the package tests with `pnpm test`. The `pnpm test` command runs the `@astrojs/compiler-rs` suite using `node --test 'packages/compiler/test/**/*.ts'`.

```shell
# Build the addon first, then run the package tests
pnpm run build:napi
pnpm test
```

--------------------------------

### Minimal .astro file with comment and heading

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

A minimal .astro file containing only a comment and an h1 element.

```astro
<!-- A comment! -->
<h1>Hello, World!</h1>
```

--------------------------------

### Add new test cases

Source: https://github.com/withastro/compiler-rs/blob/main/CONTRIBUTING.md

Command to run astro_codegen tests after adding a new .astro fixture file, which generates a new .snap file.

```shell
cargo test -p astro_codegen
```

--------------------------------

### Run Rust tests

Source: https://github.com/withastro/compiler-rs/blob/main/CONTRIBUTING.md

Commands to run all Rust tests, only astro_codegen tests, and update snapshots with cargo insta review.

```shell
# Run all Rust tests (unit + snapshot)
cargo test

# Run only astro_codegen tests
cargo test -p astro_codegen

# Update snapshots after changes
cargo insta review
```

--------------------------------

### File structure diagram

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

ASCII diagram showing the order of sections in an .astro file: component script, template, and style blocks.

```text
┌──────────────────────────────────┐
│  ---                             │
│  Component Script                │
│  ---                             │
├──────────────────────────────────┤
│  Template                        │
└──────────────────────────────────┘
```

--------------------------------

### Basic style block

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Default <style> blocks contain standard CSS.

```astro
<style>
  h1 { color: red; }
</style>
```

--------------------------------

### Parse .astro to AST with parse()

Source: https://github.com/withastro/compiler-rs/blob/main/packages/compiler/README.md

Parse an .astro component and return an ESTree-compatible AST. The result.ast is logged as formatted JSON.

```javascript
import { parse } from "@astrojs/compiler-rs";

const result = parse(source);

console.log(JSON.stringify(result.ast, null, 2));
```

--------------------------------

### Run TypeScript tests

Source: https://github.com/withastro/compiler-rs/blob/main/CONTRIBUTING.md

Command to run the TypeScript test suite.

```shell
pnpm run test
```

--------------------------------

### Namespace in component names not supported

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Colons in component names are not namespace separators; the whole name is treated as a single component name. Also shows that spaces are not allowed.

```astro
<Namespace:Component />
```

```astro
<Namespace : Component />
```

--------------------------------

### Transform .astro to JavaScript with transform()

Source: https://github.com/withastro/compiler-rs/blob/main/packages/compiler/README.md

Transform an .astro component source string into a JavaScript module. The filename option sets the source path and sourcemap: "both" generates both inline and external source maps.

```javascript
import { transform } from "@astrojs/compiler-rs";

const result = transform(source, {
  filename: "/Users/astro/Code/project/src/pages/index.astro",
  sourcemap: "both",
});
```

--------------------------------

### Multiple root elements

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Unlike JSX, no single root element is required. Shows multiple root elements and multiple elements inside an expression.

```astro
<header>…</header>
<main>…</main>
<footer>…</footer>

<!-- or inside an expression: -->
{
  <div>1</div>
  <div>2</div>
  <div>3</div>
}
```

--------------------------------

### Fragment tag syntax

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Shows the <Fragment> tag as an alternative to the shorthand fragment syntax, which may accept attributes.

```astro
<Fragment>
	<div>Item 1</div>	
	<div>Item 2</div>
</Fragment>
```

--------------------------------

### Void elements

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

HTML void elements do not need to be self-closed.

```astro
<input type="text">
<br>
<img src="image.png">
```

--------------------------------

### Basic script block

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

A basic script block in an Astro component. Multiple script blocks are allowed per file.

```astro
<script>
  console.log("Hello");
</script>
```

--------------------------------

### Unclosed HTML tags

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Like HTML, tags do not need to be explicitly closed.

```astro
<p>Hello
<p>World
```

--------------------------------

### Whitespace between script and template is ignored

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Shows that whitespace after the component script's closing fence is ignored and does not produce text nodes.

```astro
---
const greeting = "Hello";
---



<h1>{greeting}, World!</h1>
```

--------------------------------

### Empty expressions inside attributes

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Empty expressions {} inside attributes are allowed.

```astro
<Component attribute={} />
```

--------------------------------

### HTML doctype declaration

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

The HTML doctype declaration is allowed in the template.

```astro
<!DOCTYPE html>
```

--------------------------------

### Top-level text nodes

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Top-level text inside the template is treated as text nodes.

```astro
Hello, World!
```

--------------------------------

### Attribute names with hyphens and colons

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Attribute names follow HTML conventions and can include hyphens and colons, as shown.

```astro
<div @click="handler" x.data="value" :class="my-class" />
```

--------------------------------

### Comments inside opening tags

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Comments are allowed inside the opening tag of an element.

```astro
<div
	{/* Hello */}
	class="my-class"
></div>
```

--------------------------------

### Style block with lang attribute

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

The lang attribute specifies a preprocessor language, such as SCSS, and the content follows that preprocessor's syntax.

```astro
<style lang="scss">
  $accent: #1d4ed8;
  .card { border-color: $accent; }
</style>
```

--------------------------------

### Math element with literal braces

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Inside <math> elements, curly braces are treated as literal text, so {R} and {2x} are not expressions.

```astro
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <semantics>
    <annotation encoding="application/x-tex">
      f\colon X \to \mathbb{R}^{2x}
    </annotation>
  </semantics>
</math>
```

--------------------------------

### Title and textarea with expressions and literal HTML

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

In <title> and <textarea>, expressions are evaluated while inner HTML tags are treated as literal text.

```astro
<title>{pageTitle} - Site with <b>bold</b></title>
<textarea>{defaultValue} with <div>tags</div></textarea>
```

--------------------------------

### TypeScript in bare script tag

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

A bare script tag with no attributes can contain TypeScript. The content adheres to standard TypeScript syntax.

```astro
<script>
  interface User {
    id: number;
    name: string;
  }

  // ...
</script>
```

--------------------------------

### HTML comments in template and expressions

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

HTML comments are allowed both in the template and inside expressions.

```astro
<!-- This is an HTML comment -->
{
	<!-- This is an HTML comment inside an expression -->
}
```

--------------------------------

### Template literal attributes

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Attributes can use backticks for interpolation without opening an expression.

```astro
<Component attribute=`hello ${value}` />
```

--------------------------------

### is:raw directive

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

The is:raw attribute treats content as raw text instead of JSX, allowing non-JS content.

```astro
<Component is:raw>{<% non-JS content %>}</Component>

<div is:raw>
	{not an expression, just text}
</div>
```

--------------------------------

### Less-than signs in text nodes

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Less-than signs in text nodes are parsed following HTML rules and do not need to be escaped.

```astro
<p>5 < 10</p>
```

--------------------------------

### Unquoted attribute values

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Attribute values do not need to be quoted if they contain only alphanumeric characters, hyphens, underscores, and periods.

```astro
<Component data-id=12345 class=my-class />
```

--------------------------------

### Whitespace in expressions

Source: https://github.com/withastro/compiler-rs/blob/main/docs/SYNTAX_SPEC.md

Whitespace inside expressions is preserved as text nodes, unlike JSX. Shows three cases: whitespace around elements, leading/trailing spaces, and whitespace-only expressions.

```astro
<!-- Whitespace around element -->
{
    <div>Hello</div>
}

<!-- Leading/trailing spaces -->
{   <div>test</div>   }

<!-- Whitespace-only expression -->
{   }
```
Tokens:
Raw