# prettier-plugin-astro: making .astro files format without changing what they render

> prettier-plugin-astro is the official Prettier plugin for Astro files, and the interesting part is not the formatting but the three Astro specific options that keep a reformatted file rendering exactly as before. It is a small, well documented plugin, and it is also where Astro whitespace handling is made explicit.

**withastro/prettier-plugin-astro** — Prettier plugin for Astro

- Repository: https://github.com/withastro/prettier-plugin-astro
- Stars: 613 · Forks: 48
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/withastro-prettier-plugin-astro

## The plugin is the official Prettier integration for .astro files

prettier-plugin-astro adds support for formatting .astro files to Prettier, and it is the official plugin for the Astro project. The repository lives under the withastro organisation, the package is published as prettier-plugin-astro, and the manifest describes it as a Prettier Plugin for formatting Astro files.

What it does not do is reformat the Astro compiler or replace the Astro language server. It is a Prettier plugin, which means it plugs into Prettier's existing option system, existing config file resolution and existing CLI, and applies Prettier's usual formatting rules to a file type Prettier does not understand on its own.

That last part is the reason a plugin exists at all. Prettier is a JavaScript and TypeScript formatter with a plugin interface, and Astro files are a compiler-specific template format with frontmatter, markup and expressions. Without a plugin, either Prettier refuses to touch .astro files or a maintainer keeps a separate formatting path for them.

The package is MIT licensed, version 1.1.1 in the manifest, and the types are shipped as a hand written index.d.ts at the root alongside the built output. The build is Rollup, the tests are Vitest, and the repository also carries a biome.jsonc and an eslint.config.js.

## Installation is one dev dependency and one config entry

The install step installs Prettier and the plugin together as dev dependencies:

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

There is a pnpm variant, kept in a collapsed section of the README:

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

Then the plugin is added to the Prettier configuration file, which the README shows as a .prettierrc.mjs:

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

That is the minimum. The README also gives a recommended configuration, and the reason it recommends it is compatibility rather than formatting quality. It says that for optimal compatibility with the different package managers and Prettier plugins, you should manually specify the parser to use for Astro files:

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

The overrides block pins the parser for *.astro files so that a different plugin in your config cannot claim them first. If you already have overrides for other file types, this one joins them.

## Astro Compress HTML is the option that changes rendered output

Of the three plugin specific options, astroCompressHTML is the one that matters most, and it is the one most likely to surprise you. It is a mirror of the compressHTML setting in astro.config.mjs, and it tells the formatter which whitespace the compiler will collapse, so that reformatting a file never changes what it renders.

The mechanism is worth spelling out. Astro's own default is jsx, and since Astro 7.0.0 that means a whitespace run containing a newline is dropped, while a same-line space is treated as content. If the formatter assumed a different rule, it would treat a meaningful space as insignificant and remove it, and the page would render differently after a format.

That is the whole purpose of the option: it does not change the formatting, it tells the formatter the truth about the compiler so the formatting stays safe. The default in the plugin is jsx, matching Astro's own default.

The README also says to set this to match your project if you have changed compressHTML in your Astro config. The accepted values are html, jsx and none, and true and false are accepted as aliases for html and none, so the value can be copied across verbatim from an Astro configuration file. The CLI override is --astro-compress-html and the API override is astroCompressHTML.

## Allow shorthand and skip frontmatter cover the other two cases

astroAllowShorthand controls how matching identifier attributes are formatted, with the example given being an element written as name={name} against the shorthand form {name}. When the option is unset, the formatter preserves whatever form the input used. When it is true, the formatter uses the shorthand, and when it is false it uses the explicit form where possible.

The default of unset is the conservative choice, because it means the formatter does not churn a file just because the preferred style differs. That matters in a repository where the shorthand is a matter of taste rather than a rule.

astroSkipFrontmatter is for projects that format their JavaScript with another tool. The README gives the example of using Biome, and notes that in that case it is possible to skip formatting the frontmatter, so the two formatters do not fight over the same lines. The default is false, and the option is named for exactly what it does.

Together the three options cover the three things that actually vary between projects: whether the shorthand is preferred, who owns the frontmatter, and how the compiler treats whitespace. Everything else comes from Prettier itself, and the README says that most options from Prettier will work with the plugin, set either in a configuration file or through CLI flags.

## VS Code users may not need to install it at all

There is a section on formatting with the VS Code Prettier extension directly, and it opens with a note that changes the practical advice. The Astro VS Code extension already uses Prettier and this plugin to format your code. You only need to install the plugin separately if you are not using Astro's own VS Code extension, or if you want Prettier extension features that Astro's extension does not support, such as the toolbar panel showing Prettier's status.

If you do want that, the settings are short. The Prettier document selector tells VS Code that Prettier can be used for .astro files, and the language specific default formatter points it at the Prettier extension:

```json
{
  "prettier.documentSelectors": ["**/*.astro"],
  "[astro]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}
```

The README also has a small piece of advice for people filing issues: when you report a formatting problem with your .astro files in VS Code, say which extension you are using to format them, Astro's own extension or the Prettier extension. That is a fair request, because the two paths can produce different results from the same plugin.

The two extensions are the Astro VS Code extension and the VS Code Prettier extension, and the difference between them is the reason the plugin's behaviour can look inconsistent from inside the editor.

## A plugin that formats its own source with Biome and ESLint

The repository is a small, modern TypeScript project and the tooling says so. The scripts in the manifest show Biome handling both formatting and linting of the code, with a separate import sorting step, and ESLint running alongside it for the rules Biome does not cover. There is a format script for the code, a format:imports script, and matching CI variants that check rather than write. The lint script runs biome lint and eslint --cache, and lint:fix adds the write flags.

The formatting of the source of a formatter is itself worth a glance: the plugin is formatted with Biome, not with Prettier, which avoids the circularity of using Prettier to format a Prettier plugin. Tests run through vitest, with watch and UI variants, and a typecheck script runs tsc --noEmit.

Releases are managed with changesets. The release script runs the build and then changeset publish, and the .changeset directory at the repository root is where the pending release notes are written. The dependency list is small and tells you what the plugin actually does under the hood: @astrojs/compiler-rs for the Astro compiler itself, @prettier/parse-srcset for srcset attribute parsing, and sass-formatter for embedded style blocks.

The last push was on 2026-10-16 and the most recent release is v1.1.1 from 2026-10-09, preceded by v1.1.0 in September 2026 and v1.0.1 in mid September 2026, so the project is on a 1.x line and shipping frequently. Changes to it are subject to the Astro governance document and the Astro style guide.

## Conclusion

Adopt prettier-plugin-astro if your project has .astro files and you want them in the same Prettier run as the rest of your code, and you are willing to set the compressHTML option to match your Astro config so reformatting cannot change rendered output. Do not adopt it if you format with Biome instead, where the frontmatter skip option is the only piece you would need. Before you enable it, add the plugin to your Prettier config with the parser override for *.astro files, and check your astro.config.mjs compressHTML value, because the plugin default follows Astro's own default of jsx rather than your project setting.

## FAQ

### How do I install prettier-plugin-astro?

Run `npm i --save-dev prettier prettier-plugin-astro`, or `pnpm add --save-dev prettier prettier-plugin-astro` if you use pnpm. Then add `plugins: ['prettier-plugin-astro']` to your Prettier configuration file.

### What is the astroCompressHTML option for?

It mirrors the compressHTML setting in astro.config.mjs and tells the formatter which whitespace the Astro compiler will collapse, so reformatting a file never changes what it renders. The default is jsx, matching Astro's own default since Astro 7.0.0, and html, jsx and none are accepted, with true and false as aliases for html and none.

### Do I need to install prettier-plugin-astro to format Astro files in VS Code?

Not if you use the Astro VS Code extension, since it already uses Prettier and this plugin. You only need the plugin separately if you are not using that extension, or you want Prettier extension features it does not support, such as the toolbar panel showing Prettier's status.

### How do I stop the plugin from formatting the frontmatter?

Set the astroSkipFrontmatter option to true, which is useful when another tool such as Biome formats your JavaScript. The default is false, and the CLI override is --astro-skip-frontmatter.

## Sources

- [Issues](https://github.com/withastro/prettier-plugin-astro/issues)
- [README](https://github.com/withastro/prettier-plugin-astro/blob/main/README.md)
- [Releases](https://github.com/withastro/prettier-plugin-astro/releases)
- [withastro/prettier-plugin-astro on GitHub](https://github.com/withastro/prettier-plugin-astro)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/withastro-prettier-plugin-astro