Prettier Astro Plugin

https://github.com/withastro/prettier-plugin-astro
Admin
A Prettier plugin for formatting .astro files with support for Astro-specific syntax and formatting...
Tokens:43,556
Snippets:301
Trust Score:8.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install with npm

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/README.md

Installs Prettier and the Astro plugin as dev dependencies using npm.

```shell
npm i --save-dev prettier prettier-plugin-astro
```

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

### Install with pnpm

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/README.md

Installs Prettier and the Astro plugin as dev dependencies using pnpm.

```shell
pnpm add --save-dev prettier prettier-plugin-astro
```

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

### Usage of element tables

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/elements.md

Usage example showing how to import and use the internal functions and sets. Demonstrates typical return values and a helper that checks raw-text tags.

```ts
import { displayOfTag, isInlineDisplay, rawTextElements, voidElements } from './src/elements';

displayOfTag('div'); // 'block'
displayOfTag('span'); // 'inline'
isInlineDisplay('inline-block'); // true
isInlineDisplay('block'); // false
rawTextElements.has('script'); // true
voidElements.has('img'); // true

const isRawByTag = (tag: string) => rawTextElements.has(tag); // → opensRawSubtree for plain HTML tags
```

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

### Example of Lorem Ipsum Text

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/test/fixtures/options/option-prose-wrap-always/input.md

A placeholder text block used for demonstration purposes.

```text
Lorem ipsum dolor sit amet consectetur adipisicing elit. At dignissimos quasi saepe odit sed repellendus voluptatum sunt, quia
dolorem quam quos aliquid dolorum, iste suscipit nisi aliquam. Illum eius velit distinctio corporis recusandae, animi odit quis cupiditate
non culpa voluptatem, officiis magnam quod aperiam perferendis obcaecati temporibus, iure natus hic?
```

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

### Configure Astro plugin options in .prettierrc.mjs

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/options.md

Example `.prettierrc.mjs` configuration file that sets the three Astro plugin options. Shows how to enable the plugin and configure `astroAllowShorthand`, `astroSkipFrontmatter`, and `astroCompressHTML`.

```js
// .prettierrc.mjs
/** @type {import('prettier').Config} */
export default {
	plugins: ['prettier-plugin-astro'],
	astroAllowShorthand: true,
	astroSkipFrontmatter: false,
	astroCompressHTML: 'jsx',
};
```

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

### Configure .prettierrc.mjs with astroCompressHTML and astroAllowShorthand

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/printer.md

Example configuration file showing a non-trivial option combination. Sets astroCompressHTML to 'html' to mirror Astro's compressHTML setting and astroAllowShorthand to true to normalize attribute shorthand.

```javascript
// .prettierrc.mjs — non-trivial option combination
/** @type {import('prettier').Config} */
export default {
	plugins: ['prettier-plugin-astro'],
	astroCompressHTML: 'html', // mirror Astro's compressHTML setting
	astroAllowShorthand: true, // normalize <Comp value={value} /> to <Comp {value} />
};
```

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

### Direct test of module internals

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/utils.md

Dev-time usage example for testing the module internals directly. Imports `decodeQuoteEntities`, `manualDedent`, and `printClassNames` from `./src/printer/utils` and shows expected results for each function.

```ts
import { decodeQuoteEntities, manualDedent, printClassNames } from './src/printer/utils';

manualDedent('  a\n  b').result; // 'a\nb'; tabSize: 2, char: ' '
decodeQuoteEntities('&quot;x&quot;'); // '"x"'
printClassNames('  foo   bar  '); // 'foo bar'
```

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

### Usage example with prettier.format

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/utils.md

Shows how the internal helpers affect formatting behavior through the public API. Formats an Astro snippet with the plugin and demonstrates that class attribute lines are trimmed and whitespace runs collapsed to single spaces.

```js
import prettier from 'prettier';
import prettierPluginAstro from 'prettier-plugin-astro';

// class attribute normalization: lines are trimmed, runs collapsed
const src = `<div class="
  foo   bar
    baz
">x</div>`;

const out = await prettier.format(src, { parser: 'astro', plugins: [prettierPluginAstro] });
// class="foo bar" / "baz" lines preserved with their indentation collapsed to single spaces
```

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

### Accept props with Astro.props

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/test/fixtures/markdown/embedded-in-markdown/output.md

Define and accept props in an Astro component using the `Astro.props` global. The example shows destructuring with a default value for an optional prop.

```astro
---
// Example: <SomeComponent greeting="(Optional) Hello" name="Required Name" />
const { greeting = "Hello", name } = Astro.props;
---

<div>
  <h1>
    {greeting}, {name}!
  </h1>
</div>
```

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

### Example .prettierrc.cjs with Astro options

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/README.md

Configuration file for the Astro Prettier plugin. Sets astroAllowShorthand to false, astroSkipFrontmatter to false, and astroCompressHTML to 'jsx'. Use this to control formatting of shorthand attributes, skip frontmatter formatting, and match the compressHTML setting in astro.config.mjs.

```js
{
  astroAllowShorthand: false;
  astroSkipFrontmatter: false;
  astroCompressHTML: 'jsx';
}
```

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

### Prettier config with astroCompressHTML: 'jsx'

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/whitespace.md

Example configuration that changes whitespace decisions. Sets astroCompressHTML to 'jsx' (the default) and htmlWhitespaceSensitivity to 'strict' to preserve author-owned whitespace.

```js
// .prettierrc.mjs
export default {
	plugins: ['prettier-plugin-astro'],
	astroCompressHTML: 'jsx', // default: whitespace runs containing a newline are kept, same-line spaces reflow
	htmlWhitespaceSensitivity: 'strict', // author-owned whitespace is preserved
};
```

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

### Accept props with Astro.props

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/test/fixtures/markdown/embedded-in-markdown/input.md

Define and accept props in an Astro component. Props are available on the `Astro.props` global in the frontmatter script. The example shows a default value for `greeting` and a required `name` prop.

```astro
---
// Example: <SomeComponent greeting="(Optional) Hello" name="Required Name" />
const { greeting = 'Hello', name } = Astro.props;
---
<div>
    <h1>{greeting}, {name}!</h1>
</div>
```

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

### Prettier config with astroCompressHTML: 'html' or 'none'

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/whitespace.md

Example configuration mirroring Astro's compressHTML option. Use 'html' (equivalent to true) for browser HTML whitespace rules, or 'none' (equivalent to false) to disable collapsing.

```js
// Astro's own compressHTML mirror — copy the value across verbatim (true/false aliases):
export default {
	plugins: ['prettier-plugin-astro'],
	astroCompressHTML: 'html', // == true; browser HTML whitespace rules
	// or astroCompressHTML: 'none' // == false; no collapsing
};
```

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

### Register astro parser with Prettier

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/index.md

Registers the `astro` parser under the key `astro`. The `parse` function comes from `src/parser.ts` with signature `parse(source: string, options: ParserOptions): AstroNode`. `astFormat: 'astro'` is the AST format id consumed by the printer, and `locStart`/`locEnd` map every `AstroNode` to its `start`/`end` source offsets for Prettier's comment handling and cursor positioning.

```ts
export const parsers: Record<string, Parser> = {
	astro: {
		parse,
		astFormat: 'astro',
		locStart: (node: AstroNode) => node.start,
		locEnd: (node: AstroNode) => node.end,
	},
};
```

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

### attributesOf

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/ast.md

Utility function to get the attributes of an Astro node's opening element.

```APIDOC
## `attributesOf`

### Description
Returns the attributes array of a node's opening element.

### Signature
```ts
export function attributesOf(node: AstroNode): AstroNode[] {
	const opening = node.openingElement as AstroNode | undefined;
	return (opening?.attributes as AstroNode[] | undefined) ?? [];
}
```

### Parameters
- `node` (`AstroNode`) - Required - Item with an `openingElement`.

### Returns
`AstroNode[]` - The `attributes` array of the node's `openingElement`, or `[]` if absent.
```

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

### attributesOf: Get attributes from an Astro node

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/ast.md

Returns the attributes array from a node's openingElement, or an empty array if the openingElement or its attributes are absent.

```ts
export function attributesOf(node: AstroNode): AstroNode[] {
	const opening = node.openingElement as AstroNode | undefined;
	return (opening?.attributes as AstroNode[] | undefined) ?? [];
}
```

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

### Error handling for malformed input

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/parser.md

Catches a SyntaxError when formatting invalid Astro input. The error includes a loc property with start line and column.

```javascript
import prettier from 'prettier';
import prettierPluginAstro from 'prettier-plugin-astro';

try {
	await prettier.format('---\nconst x = ;\n---\n', {
		parser: 'astro',
		plugins: [prettierPluginAstro],
	});
} catch (error) {
	// SyntaxError: "... Unexpected token (3:1)"
	if (error instanceof SyntaxError) {
		console.error(error.message); // includes "(line:column)"
		if (error.loc) {
			console.error(`line ${error.loc.start.line}, column ${error.loc.start.column}`);
		}
	}
}
```

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

### Basic Prettier configuration (.prettierrc.mjs)

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/README.md

Adds the Astro plugin to the Prettier configuration file.

```js
// .prettierrc.mjs
/** @type {import("prettier").Config} */
export default {
  plugins: ['prettier-plugin-astro'],
};
```

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

### Define props with TypeScript interface

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/test/fixtures/markdown/embedded-in-markdown/output.md

Define props with TypeScript by exporting a `Props` interface. The example shows a required `name` prop and an optional `greeting` prop with a default value.

```astro
---
// Example: <SomeComponent />  (WARNING: "name" prop is required)
export interface Props {
  name: string;
  greeting?: string;
}
const { greeting = "Hello", name } = Astro.props;
---

<div>
  <h1>
    {greeting}, {name}!
  </h1>
</div>
```

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

### Recommended Prettier configuration with parser override (.prettierrc.mjs)

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/README.md

Recommended configuration that manually specifies the 'astro' parser for .astro files to ensure optimal compatibility with different package managers and Prettier plugins.

```js
// .prettierrc.mjs
/** @type {import("prettier").Config} */
export default {
  plugins: ['prettier-plugin-astro'],
  overrides: [
    {
      files: '*.astro',
      options: {
        parser: 'astro',
      },
    },
  ],
};
```

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

### Format .astro files with CLI flags

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/configuration.md

Run Prettier from the CLI with the plugin and all three options. Note that --astro-allow-shorthand is used without a value, which sets it to true.

```shell
prettier --write "src/**/*.astro" \
  --plugin prettier-plugin-astro \
  --astro-allow-shorthand \
  --astro-skip-frontmatter \
  --astro-compress-html html

```

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

### parse

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/parser.md

Documentation for the `parse` function, the main entry point of the parser module. It details the function signature, parameters, return type, error handling, and the internal pipeline of transformations applied to the AST.

```APIDOC
## `parse`

### Description
Parses the raw contents of an `.astro` file into an `AstroNode` (an `AstroRoot`), applying a series of transformations to prepare the AST for Prettier's printers. It reads Prettier's parser options to configure whitespace handling and throws a `SyntaxError` if the compiler reports an error.

### Signature
```ts
export function parse(source: string, options: ParserOptions): AstroNode
```

### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source` | `string` | yes | The raw contents of an `.astro` file. |
| `options` | `ParserOptions` | yes | Prettier's parser options, including the plugin options. The function reads `options.astroCompressHTML` and `options.htmlWhitespaceSensitivity` to build the whitespace `Settings`; `options.originalText` is not used here (it is used by the printers via the same options object). |

`ParserOptions` is Prettier's built-in type (augmented by this plugin, see [options](./options.md)). Relevant fields as consumed by this module:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `astroCompressHTML` | `'jsx' \| 'html' \| 'none'` | `'jsx'` | Whitespace-collapsing mode; `'jsx'` runs `normalizeWhitespace`, anything else runs `resolveBlankContainers`. |
| `htmlWhitespaceSensitivity` | `'css' \| 'strict' \| 'ignore'` | Prettier default (`'css'`) | How significant whitespace is considered to be; feeds into `Settings.sensitivity`. |

### Return type
`AstroNode` — the mutated `AstroRoot` node:

- The `body` array is removed (`delete ast.body`) and replaced by `ast.template`, an `AstroNode` of type `JsExpressionRoot` whose `node` is a `JSXFragment` with `astroRoot: true` and the body as `children`.
- `ast.comments` is set to the filtered `JsComment[]` (see [Astro comments](./ast.md#jscomment)).
- Every node may carry plugin-added (non-standard) fields: `astroStyleAttribute`, `astroSrcsetAttribute`, `astroShorthand`, `astroBacktick`, `astroIgnored`, `astroSvg`, `astroSvgText`, `astroPreserveWhitespace`, `astroChildren`, `astroRoot`, `raw`, `value`.

### Throws
| Error type | Condition | Source |
|------------|-----------|--------|
| `SyntaxError` | The compiler diagnostics contain an entry with `severity: 'error'`. The message is `${diagnostic.text} (${line}:${column})` and the error carries a non-standard `loc` property `{ start: { line, column } }`. | `src/parser.ts:65` (`syntaxError`), thrown at `src/parser.ts:39` |

The `syntaxError` factory (lines 65–72):

```ts
function syntaxError(diagnostic: Diagnostic): Error {
	const label = diagnostic.labels[0];
	const line = label?.line ?? 1;
	const column = (label?.column ?? 0) + 1;
	const error = new SyntaxError(`${diagnostic.text} (${line}:${column})`);
	(error as Error & { loc: unknown }).loc = { start: { line, column } };
	return error;
}
```

### Pipeline (in order)
1. `parseAstro(source)` from `@astrojs/compiler-rs` → `{ ast, diagnostics }`.
2. Throw `SyntaxError` on the first `diagnostics` entry with `severity === 'error'`.
3. `stripParentheses` — unwraps `ParenthesizedExpression` / `TSParenthesizedType` nodes (Prettier re-derives parens itself; oxc emits explicit ones and they would compound on every pass).
4. `repairSpans` — `AstroScript` spans the whole `<script>` element, overlapping the tags Prettier sorts it against; its `start`/`end` are reset to the opening element's `end` and the closing element's `start`.
5. `markAttributes` — flags `style` attributes on HTML elements (`astroStyleAttribute`), `srcset` attributes on `img`/`source` (`astroSrcsetAttribute`), normalizes `class` attribute values via `printClassNames`, and flags `astroShorthand` (attribute source starts with `{`) and `astroBacktick` (expression source starts with `` ` ``).
6. `markSvgNamespace` — walks `<svg>` subtrees, marking `astroSvg`, `astroSvgText` (for `text`, `textPath`, `tspan`, or ancestors in text content), and `astroPreserveWhitespace` (from `xml:space="preserve"`); stops at `foreignObject`.
7. `applyPrettierIgnore` — a comment `prettier-ignore` marks the next non-`JSXText` sibling with `astroIgnored`.
8. Build `template` via `templateFragment` — a `JsExpressionRoot` wrapping a `JSXFragment` (`astroRoot: true`) around `body`.
9. Whitespace: `mode === 'jsx'` → `normalizeWhitespace(template, settings)`; otherwise `resolveBlankContainers` (`src/parser.ts:252`) then `claimChildren` (`src/parser.ts:271`) (which calls `takeOverChildren` to hand layout of each element's children to the plugin's children printer).
10. `normalizeTagPairs` — pairs/self-closes tags: forces closing tags on raw-text elements, empties whitespace-only raw children, self-closes elements that are components, void elements, `<slot>`, or carry `set:html`/`set:text`.
11. `printableComments` — drops comments inside the frontmatter, inside `astroIgnored` nodes, and inside raw subtrees (Prettier throws on comments it never prints).
```

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

### Plugin entry point (src/index.ts)

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/index.md

The main entry point of the plugin, declaring the Prettier plugin contract with `languages`, `parsers`, and `printers` registrations. It also re-exports option records and types, and defines `defaultOptions` with `tabWidth: 2`.

```ts
// src/index.ts
import type { Parser, Printer, SupportLanguage } from 'prettier';
import type { AstroNode } from './ast';
import { options } from './options';
import { parse } from './parser';
import { printer } from './printer';

// https://prettier.io/docs/en/plugins.html#languages
export const languages: Partial<SupportLanguage>[] = [
	{
		name: 'astro',
		parsers: ['astro'],
		extensions: ['.astro'],
		vscodeLanguageIds: ['astro'],
	},
];

// https://prettier.io/docs/en/plugins.html#parsers
export const parsers: Record<string, Parser> = {
	astro: {
		parse,
		astFormat: 'astro',
		locStart: (node: AstroNode) => node.start,
		locEnd: (node: AstroNode) => node.end,
	},
};

// https://prettier.io/docs/en/plugins.html#printers
export const printers: Record<string, Printer> = {
	// Prettier types `print`'s callback as taking an `AstPath`, but it passes one taking a selector.
	astro: printer as unknown as Printer,
};

const defaultOptions = {
	tabWidth: 2,
};

export type { CompressHTML, PluginOptions } from '../index';
export { defaultOptions, options };
```

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

### AstroNode interface definition

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/types.md

Defines the internal AstroNode interface used by the prettier-plugin-astro. It includes required type, start, and end fields, optional synthetic and ownChildren flags, and an index signature for compiler and plugin-added fields.

```ts
export interface AstroNode {
	type: string;
	start: number;
	end: number;
	[synthetic]?: boolean;
	[ownChildren]?: boolean;
	[key: string]: unknown;
}
```

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

### Define Astro plugin options record

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/options.md

Defines the `options` record with `SupportOption` entries for `astroAllowShorthand`, `astroSkipFrontmatter`, and `astroCompressHTML`. The `astroCompressHTML` choices include boolean aliases that use the `redirect` mechanism, requiring `as unknown as` casts because Prettier's `SupportOption` type omits `redirect`.

```ts
// https://prettier.io/docs/en/plugins.html#options
export const options: Record<keyof PluginOptions, SupportOption> = {
	astroAllowShorthand: {
		category: 'Astro',
		type: 'boolean',
		description:
			'Choose whether matching identifier attributes are normalized to shorthand or explicit form, when unset the form that was written stay as-is.',
	},
	astroSkipFrontmatter: {
		category: 'Astro',
		type: 'boolean',
		default: false,
		description: 'Skips the formatting of the frontmatter.',
	},
	astroCompressHTML: {
		category: 'Astro',
		type: 'choice',
		default: 'jsx',
		description:
			"Mirror of Astro's compressHTML config. Tells the formatter which whitespace the compiler will collapse.",
		choices: [
			{
				value: 'jsx',
				description:
					"Astro's default since 7.0.0. Whitespace runs containing a newline are dropped; same-line spaces are content.",
			},
			{
				value: 'html',
				description: 'Browser HTML whitespace rules. Equivalent to compressHTML: true.',
			},
			{ value: 'none', description: 'No collapsing. Equivalent to compressHTML: false.' },
			// Prettier's SupportOption types omit `redirect`, which its own option normaliser honours.
			{ value: true, redirect: 'html' } as unknown as { value: boolean; description: string },
			{ value: false, redirect: 'none' } as unknown as { value: boolean; description: string },
		],
	},
};
```

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

### Import and use an Astro component

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/test/fixtures/markdown/embedded-in-markdown/output.md

Import an Astro component in the frontmatter script and use it in the HTML template. The component must begin with an uppercase letter to distinguish it from native HTML elements.

```astro
---
// Import your components in your component script...
import SomeComponent from "./SomeComponent.astro";
---

<!-- ... then use them in your HTML! -->
<div>
  <SomeComponent />
</div>
```

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

### Configure prettier-plugin-astro with astroCompressHTML: 'none'

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/children.md

Use this .prettierrc.mjs configuration to observe the lending behavior when an element must wrap. The astroCompressHTML: 'none' setting and printWidth: 40 force a wrap, making the borrowed closing bracket visible.

```javascript
// .prettierrc.mjs — observe lending when an element must wrap
/** @type {import('prettier').Config} */
export default {
	plugins: ['prettier-plugin-astro'],
	astroCompressHTML: 'none',
	printWidth: 40,
};

// Input:
//   <div><span>a</span><span>long content that forces a wrap</span></div>
// After a wrap the second <span> can take a line of its own; its opening tag's
// ">" may be carried by the first <span> rather than adding rendered space.
```

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

### syntaxError factory

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/parser.md

Factory that builds a SyntaxError from a compiler diagnostic. It extracts the first label's line and column (defaulting to 1 and 0), constructs the error message as `${diagnostic.text} (${line}:${column})`, and attaches a non-standard `loc` property with the start position.

```ts
function syntaxError(diagnostic: Diagnostic): Error {
	const label = diagnostic.labels[0];
	const line = label?.line ?? 1;
	const column = (label?.column ?? 0) + 1;
	const error = new SyntaxError(`${diagnostic.text} (${line}:${column})`);
	(error as Error & { loc: unknown }).loc = { start: { line, column } };
	return error;
}
```

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

### Catch CssSyntaxError when formatting faulty style tag

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/errors.md

Shows how to catch the embedded-language error when formatting invalid Astro content. The example uses faulty CSS in a `<style>` tag; the catch block receives a `CssSyntaxError` whose message is visible because `PRETTIER_DEBUG` was set by `surfacingErrors`.

```js
import prettier from 'prettier';
import prettierPluginAstro from 'prettier-plugin-astro';

try {
	await prettier.format('<style>a { color: red;</style>', {
		parser: 'astro',
		plugins: [prettierPluginAstro],
	});
} catch (error) {
	// CssSyntaxError (from the CSS parser) — message is visible because PRETTIER_DEBUG was set
	console.error(error.message);
}
```

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

### Handle parse errors with SyntaxError and loc

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/index.md

Handle parse errors when formatting Astro code. The plugin contributes the parser; parse failures surface as SyntaxError from the parse call inside Prettier. The error object includes a loc property with start line and column.

```javascript
import prettier from 'prettier';
import prettierPluginAstro from 'prettier-plugin-astro';

try {
	await prettier.format('<div>{unclosed}</div>', {
		parser: 'astro',
		plugins: [prettierPluginAstro],
	});
} catch (error) {
	if (error instanceof SyntaxError && (error.loc)) {
		console.error(`Parse error at ${error.loc.start.line}:${error.loc.start.column}`);
	}
}
```

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

### Frontmatter script with TypeScript in Astro

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/test/fixtures/markdown/embedded-in-markdown/output.md

Shows the frontmatter script in an Astro component. The code between the --- fences runs at build-time, and TypeScript is supported out-of-the-box.

```astro
---
// Anything inside the `---` code fence is your component script.
// This JavaScript code runs at build-time.
// See below to learn more about what you can do.
console.log("This runs at build-time, is visible in the CLI output");
// Tip: TypeScript is also supported out-of-the-box!
const thisWorks: number = 42;
---

<div class="example-1">
  <h1>Hello world!</h1>
</div>
```

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

### Format with plugin via Prettier API

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/configuration.md

Use the plugin via the Prettier API. Passes the plugin and sets astroAllowShorthand to true and astroCompressHTML to 'none'.

```typescript
import prettier from 'prettier';
import prettierPluginAstro from 'prettier-plugin-astro';

await prettier.format(source, {
  parser: 'astro',
  plugins: [prettierPluginAstro],
  astroAllowShorthand: true,
  astroCompressHTML: 'none',
});

```

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

### JsComment interface (src/ast.ts:13)

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/types.md

Internal interface representing a comment node in the AST. `type` is `'Line'` for `//` comments and `'Block'` for `/* */` comments; `value` holds the comment text; `start` and `end` are source offsets. Produced by `parse` (`src/parser.ts:32`) as `ast.comments` via `printableComments` and consumed by Prettier's comment attachment machinery.

```ts
export interface JsComment {
	type: 'Line' | 'Block';
	value: string;
	start: number;
	end: number;
}
```

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

### Format Astro source programmatically

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/options.md

Programmatic usage of Prettier's `format` API with the Astro plugin, setting `astroAllowShorthand` and `astroCompressHTML` options directly.

```ts
import prettier from 'prettier';
import prettierPluginAstro from 'prettier-plugin-astro';

await prettier.format(source, {
	parser: 'astro',
	plugins: [prettierPluginAstro],
	astroAllowShorthand: false,
	astroCompressHTML: 'none',
});
```

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

### Walk AST and find divs with isNode and tagNameOf

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/ast.md

Shows how to use the AST helpers isNode, childrenOf, and tagNameOf to walk an AstroNode tree and collect all nested div elements. The parse and walk functions are assumed to be available in the consumer's context.

```ts
import { isNode, childrenOf, tagNameOf } from './src/ast';

const root = parse(source, options); // AstroNode
// Walk and find every nested div
const divs: AstroNode[] = [];
walk(root, (node) => {
	if (isNode(node) && tagNameOf(node) === 'div') divs.push(node);
});
```

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

### Compose Settings object from ParserOptions

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/configuration.md

The plugin composes a Settings object from ParserOptions in two places: src/parser.ts:49 for whitespace normalization and src/printer/children.ts:106 for separator computation. Both use the same structure with mode and sensitivity properties.

```ts
const settings = {
	mode: options.astroCompressHTML,
	sensitivity: options.htmlWhitespaceSensitivity,
};
```

```ts
const settings = {
	mode: options.astroCompressHTML,
	sensitivity: options.htmlWhitespaceSensitivity,
};
```

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

### Pin astro parser in .prettierrc.mjs

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/configuration.md

Recommended parser pinning from the README to maximize compatibility across package managers and plugins. Forces the 'astro' parser for .astro files.

```javascript
// .prettierrc.mjs
/** @type {import("prettier").Config} */
export default {
  plugins: ['prettier-plugin-astro'],
  overrides: [
    {
      files: '*.astro',
      options: {
        parser: 'astro',
      },
    },
  ],
};

```

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

### PluginOptions interface definition

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/types.md

Defines the plugin's options interface. `astroAllowShorthand` normalizes matching identifier attributes to shorthand when `true` and expands them when `false`; `astroSkipFrontmatter` skips formatting the frontmatter; `astroCompressHTML` mirrors Astro's `compressHTML` setting. All fields are optional.

```ts
export interface PluginOptions {
	astroAllowShorthand?: boolean;
	astroSkipFrontmatter?: boolean;
	astroCompressHTML?: CompressHTML;
}
```

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

### Format Astro files with CLI overrides

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/options.md

CLI command to format Astro files with the plugin, overriding options via flags. The `--astro-compress-html` flag accepts values like `html`.

```shell
prettier --write "src/**/*.astro" \
  --plugin prettier-plugin-astro \
  --astro-allow-shorthand \
  --astro-skip-frontmatter \
  --astro-compress-html html
```

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

### Whitespace Utility Functions

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/whitespace.md

Documentation for the whitespace utility functions `forcesBreak` and `blankContentIsFree` from the prettier-plugin-astro source.

```APIDOC
## `forcesBreak`

### Description
Determines whether a node's doc group should always break. Returns `true` when the node breaks children, is a tag in `{body, script, style}`, has any element child, or has a child on its own line.

### Signature
```ts
export function forcesBreak(node: AstroNode): boolean
```

### Parameters
- **`node`** (`AstroNode`) - Required - Container node.

### Returns
- **`boolean`** - `true` if the node's doc group should always break, otherwise `false`.

### Behavior
- Returns `true` if `breaksChildren(node)` is `true`.
- Returns `true` if the node is a `JSXElement` with a tag in `breaksOwnContent` (i.e., `body`, `script`, `style`).
- Returns `true` if any child is an element child or sits on its own line.
- Otherwise returns `false`.

## `blankContentIsFree`

### Description
Returns `true` when a whitespace-only child list can be dropped entirely; `false` when the container must keep a single space because it renders content. Always `false` for `<slot>` and for custom elements with a `-` in the tag.

### Signature
```ts
export function blankContentIsFree(
	container: AstroNode,
	isRoot: boolean,
	settings: Settings,
): boolean
```

### Parameters
- **`container`** (`AstroNode`) - Required - The element/fragment whose whitespace-only children are in question.
- **`isRoot`** (`boolean`) - Required - `true` for the root template fragment.
- **`settings`** (`Settings`) - Required - Mode + sensitivity.

### Returns
- **`boolean`** - `true` if the whitespace-only child list can be dropped entirely; `false` if the container must keep a single space.

### Behavior
- Returns `false` for `<slot>` elements.
- Returns `false` for custom elements with a `-` in the tag (non-component names).
- Returns `isFree(boundary) || mayAlterRenderedWhitespace(boundary)`.
- Used by `resolveBlankContainers` in `src/parser.ts:252` in the `html`/`none` modes.
```

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

### Set plugin options in .prettierrc.mjs

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/configuration.md

Configure all three plugin options in a Prettier config file. The values shown are the defaults except astroAllowShorthand, which is unset by default (tri-state).

```javascript
// .prettierrc.mjs
/** @type {import("prettier").Config} */
export default {
  plugins: ['prettier-plugin-astro'],
  astroAllowShorthand: false,
  astroSkipFrontmatter: false,
  astroCompressHTML: 'jsx',
};

```

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

### ChildrenOptions

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/children.md

Options for printChildren, controlling layout mode and an optional suffix appended after all children.

```APIDOC
## ChildrenOptions

### Description
Options for printChildren, controlling layout mode and an optional suffix appended after all children.

### Interface
ts
export interface ChildrenOptions {
	mode?: ChildrenMode;
	suffix?: Doc;
}


### Fields
- **mode** (ChildrenMode) - Optional - Layout mode. Default behavior: 'loose' is used by the main printer for element children; 'fill' for the root; the printer also passes { mode: 'fill-lending' } for a self-closing final child. The function's own default parameter is {} (see below).
- **suffix** (Doc) - Optional - Extra doc appended after all children (the printer passes suffix: ['</', tag] to let a lender's text run before it). Default: undefined.
```

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

### Render dynamic HTML with map in Astro

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/test/fixtures/markdown/embedded-in-markdown/output.md

Render dynamic HTML by mapping over an array in the template using JavaScript expressions.

```astro
---
const items = ["Dog", "Cat", "Platipus"];
---

<ul>
  {items.map((item) => (
    <li>{item}</li>
  ))}
</ul>
```

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

### printChildren invocation with ChildrenOptions

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/api-reference/children.md

Shows how the printer calls printChildren when it encounters an `ownChildren` node, passing the path, options, print callback, and the ChildrenOptions (or an empty object if undefined).

```ts
printChildren(path, options, print, (args as ChildrenOptions | undefined) ?? {})
```

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

### Settings interface (src/whitespace.ts:14)

Source: https://github.com/withastro/prettier-plugin-astro/blob/main/_autodocs/types.md

Internal interface holding whitespace compression settings. `mode` is `'jsx' | 'html' | 'none'`; `sensitivity` is `'css' | 'strict' | 'ignore'`, mirroring Prettier's `htmlWhitespaceSensitivity`. Used as parameters for `normalizeWhitespace`, `blankContentIsFree`, and `separatorFor`.

```ts
export interface Settings {
	mode: CompressHTML;
	sensitivity: Sensitivity;
}
```
Tokens:
Raw