prettier-plugin-embed

v0.8.0

Published

9 hours ago

A configurable Prettier plugin to format embedded languages in JS/TS files.

0High
0Medium
0Low

sec-ant

prettier plugin prettier-plugin embed embedded embedded-language format

prettier-plugin-embed-wide-logo

Prettier Plugin Embed

Online playground · Run the playground locally

A configurable Prettier plugin to format embedded languages in JS/TS Files.

npm i -D prettier prettier-plugin-embed

Introduction

What?

This Prettier plugin formats embedded languages in template literals within JavaScript and TypeScript files.

Why?

It adds per-language formatting controls, configurable block comments and tags, and per-identifier overrides to Prettier's embedded formatting. See prettier/prettier#4424 and prettier/prettier#5588 for related use cases.

How?

The plugin extends the embed method of Prettier's estree printer. Each integration delegates formatting to Prettier or a loaded language plugin. See the printer implementation for the integration point.

Features

Support for Additional Languages: Extend embedded formatting to languages such as XML, SQL, PHP, and more. See Language-Specific Options for the supported languages and their default identifiers.
Dual Identification Modes: Identify embedded languages by block comments /* comment */ `...` or tags tag`...` preceding the template literals.
Customizable Language Comments or Tags: Customize the comments or tags used for identifying the embedded languages.
Formatting Opt-out Mechanism: Offer the capability to deactivate formatting for certain comments or tags, including the built-in ones (html, css...) supported by the embedded-language-formatting option.
Configurable Formatting Style: Provide additional options to tailor the formatting style for embedded languages.
Strongly Typed API: Benefit from comprehensive type support for configuring this plugin's options.
Easy Integration: Integrate with the existing Prettier setup seamlessly, requiring minimal configuration to get started.

Installation

npm i -D prettier prettier-plugin-embed

Install Prettier 3 in the project that runs formatting. The consumer supplies the formatter and its language plugins.

Install the formatter plugin for each embedded language you use as a separate project dependency; the Language-Specific Options section shows which integrations require one.

Choose Prettier and runtime versions supported by every loaded language plugin. Parser availability and syntax support follow the installed formatter version.

The plugin loads Prettier through static imports, which resolve from the plugin's installation location. Standard project installs and Yarn's default Plug'n'Play dependency fallback allow these imports to access the project's installed Prettier.

Yarn projects using pnpFallbackMode: none, and pnpm projects using enableGlobalVirtualStore: true with hoisting disabled, need an explicit dependency relationship for this resolution. For these configurations, add the following to .yarnrc.yml (Yarn) or pnpm-workspace.yaml (pnpm) to connect the plugin to the project's installed Prettier:

packageExtensions:
  "prettier-plugin-embed@*":
    peerDependencies:
      prettier: ">=3.0.0 <4"

Projects can also use Yarn's default pnpFallbackMode: dependencies-only or pnpm's project-local virtual store (enableGlobalVirtualStore: false).

Usage

Playground

Try the plugin in the online playground. Edit JavaScript or TypeScript alongside your .prettierrc configuration, including the plugins array and embedded-language options. Formatting runs locally in your browser.

To report a formatting issue, keep the original code in Input, enable Compare to inspect the native Prettier output, then use Copy issue report. The report includes the input, configuration, output or error, formatter versions, and a shareable playground link. Share copies a link containing the current example and configuration.

See the playground guide for local development, keyboard shortcuts, browser limitations, and GitHub Pages deployment.

Getting Started

This is a Prettier plugin, which follows the standard usage pattern of many other Prettier plugins:

CLI:

Via --plugin:

prettier --write main.ts --plugin=prettier-plugin-embed

API:

Via the plugins options:

await prettier.format(code, {
  filepath: "main.ts",
  plugins: ["prettier-plugin-embed"],
});

Configuration File:

{
  "plugins": ["prettier-plugin-embed"]
}

For Yarn Plug'n'Play, load plugin objects from a JavaScript config so the imports resolve through Yarn's dependency map.

import * as prettierPluginEmbed from "prettier-plugin-embed";

export default {
  plugins: [prettierPluginEmbed],
};

Quick Start Config Examples

See Config Examples for complete language plugin configurations and sample output.

An Overview of the Philosophy

Set embeddedLanguageFormatting to "auto" (Prettier's default) to enable embedded formatting.

This plugin uses Prettier's built-in parsers and existing language plugins, adding the integration needed to format their languages inside template literals.

Install and load the formatter plugin for each additional language you use. For example, embedded XML requires both this plugin and @prettier/plugin-xml. The Language-Specific Options section lists the required plugins.

A preceding block comment such as /* xml */ `...` or a tag such as xml`...` identifies the embedded language. Configure each language with embedded<Language>Comments and embedded<Language>Tags. A leading block comment is checked first; templates without one are matched by their tag.

Tags support exact identifiers, member expressions, and regular expression strings in /pattern/flags form. Simple identifiers support patterns too: "/^query$/" matches the tag query. Member and call expressions use a normalized form for pattern matching; for example, factory(argument).query becomes factory().query.

For example, this JSON configuration matches prisma.$queryRaw, client.$queryRaw, and ctx.prisma.$queryRaw. JSON and JavaScript strings escape each backslash as \\:

{
  "plugins": ["prettier-plugin-embed", "prettier-plugin-sql"],
  "embeddedSqlTags": ["/\\.\\$queryRaw$/"]
}

Add comments or tags to embeddedNoopComments or embeddedNoopTags to preserve their template content as written. These options take priority among matching languages. Other overlapping matches use the first matching language in the internal registry; assign distinct identifiers or non-overlapping patterns to select a language explicitly.

[!IMPORTANT]
Specify comments or tags explicitly to keep language identification stable across plugin versions.

Language-Specific Options

Supported embedded languages and their default comment/tag identifiers are:

Astro: astro
CSS: css
Dockerfile: dockerfile, containerfile
ES (ECMAScript/JavaScript): js, jsx, es, es6, mjs, cjs, pac, javascript
Gherkin: gherkin, feature
GLSL: glsl, shader
Go Template: goTemplate, gotmpl
GraphQL: graphql, gql
Handlebars: handlebars, hbs
HTML: html, xhtml
Hugo: hugo, hugoPost
INI: ini, cfg, pro
Java: java
Jinja: jinja, jinja2, j2
JSON: json, jsonl
JSONata: jsonata
JTE: jte
LaTeX: latex, tex, aux, cls, bbl, bib, toc, sty
Liquid: liquid
Markdown: md, markdown
Marko: marko
Motoko: motoko, mo
Mustache: mustache
NGINX: nginx
Nunjucks: nunjucks, njk
Pegjs: pegjs, peggy, peg
PHP: php, php5
PowerShell: powershell, ps1
Prisma: prisma
Properties: properties
Pug: pug, jade
Ruby: ruby
Sh (Shell): sh
Solidity: solidity, sol
SQL: sql
Svelte: svelte
TOML: toml
TS (TypeScript): ts, tsx, cts, mts, typescript
XML: xml, opml, rss, svg
XQuery: xquery, xq
YAML: yaml, yml

NOOP

`embeddedNoopComments`

Type: string[]
Default: []
Description: Block comments that prevent their subsequent template literals from being identified as embedded languages and thus from being formatted.

`embeddedNoopTags`

Type: string[]
Default: []
Description: Tags that prevent their subsequent template literals from being identified as embedded languages and thus from being formatted.

This built-in option can override native embedded language formatting for the specified comments or tags, preserving their template literal content as written.

Astro

`embeddedAstroComments`

Type: string[]
Default: ["astro"]
Description: Block comments that identify embedded Astro in template literals. Requires the prettier-plugin-astro plugin.

`embeddedAstroTags`

Type: string[]
Default: ["astro"]
Description: Tags that identify embedded Astro in template literals. Requires the prettier-plugin-astro plugin.

Formatting embedded Astro requires the prettier-plugin-astro plugin to be installed and loaded. Its options control the embedded formatting behavior.

CSS

`embeddedCssComments`

Type: string[]
Default: ["css"]
Description: Block comments that make their subsequent template literals be identified as embedded CSS language.

`embeddedCssTags`

Type: string[]
Default: ["css"]
Description: Tags that make their subsequent template literals be identified as embedded CSS language.

`embeddedCssParser`

Type: "css" | "less" | "scss"
Default: "scss"
Description: The parser used to parse the embedded CSS language.

Embedded CSS uses the parsers and printers included with Prettier.

This can override the native formatting behavior for embedded CSS language. If you want to keep the native behavior, set embeddedCssComments or embeddedCssTags to [] or other values.

If you want to specify different parsers for different comments or tags, check embeddedOverrides.

Dockerfile

`embeddedDockerfileComments`

Type: string[]
Default: ["dockerfile", "containerfile"]
Description: Block comments that identify embedded Dockerfile in template literals. Requires the prettier-plugin-sh plugin.

`embeddedDockerfileTags`

Type: string[]
Default: ["dockerfile", "containerfile"]
Description: Tags that identify embedded Dockerfile in template literals. Requires the prettier-plugin-sh plugin.

Formatting embedded Dockerfile requires the prettier-plugin-sh plugin to be installed and loaded. Its options control the embedded formatting behavior.

Dockerfile and Shell share prettier-plugin-sh; the Dockerfile integration selects its dockerfile parser.

ES (ECMAScript/JavaScript)

`embeddedEsComments`

Type: string[]
Default: ["js", "jsx", "es", "es6", "mjs", "cjs", "pac", "javascript"]
Description: Block comments that make their subsequent template literals be identified as embedded ECMAScript/JavaScript language.

`embeddedEsTags`

Type: string[]
Default: ["js", "jsx", "es", "es6", "mjs", "cjs", "pac", "javascript"]
Description: Tags that make their subsequent template literals be identified as embedded ECMAScript/JavaScript language.

`embeddedEsParser`

Type: "babel" | "babel-flow" | "acorn" | "espree" | "flow" | "meriyah"
Default: "babel"
Description: The parser used to parse the embedded ECMASCript/JavaScript language.

Embedded ECMAScript and JavaScript use the parsers and printers included with Prettier.

If you want to specify different parsers for different comments or tags, check embeddedOverrides.

Gherkin

`embeddedGherkinComments`

Type: string[]
Default: ["gherkin", "feature"]
Description: Block comments that identify embedded Gherkin in template literals. Requires the prettier-plugin-gherkin plugin.

`embeddedGherkinTags`

Type: string[]
Default: ["gherkin", "feature"]
Description: Tags that identify embedded Gherkin in template literals. Requires the prettier-plugin-gherkin plugin.

Formatting embedded Gherkin requires the prettier-plugin-gherkin plugin to be installed and loaded. Its options control the embedded formatting behavior.

GLSL

`embeddedGlslComments`

Type: string[]
Default: ["glsl", "shader"]
Description: Block comments that make their subsequent template literals be identified as embedded GLSL language. This option requires the prettier-plugin-glsl plugin.

`embeddedGlslTags`

Type: string[]
Default: ["glsl", "shader"]
Description: Tags that make their subsequent template literals be identified as embedded GLSL language. This option requires the prettier-plugin-glsl plugin.

Formatting embedded GLSL language requires the prettier-plugin-glsl plugin to be loaded as well.

Go Template

`embeddedGoTemplateComments`

Type: string[]
Default: ["goTemplate", "gotmpl"]
Description: Block comments that identify embedded Go Template in template literals. Requires the @htnabe/prettier-plugin-go-template plugin.

`embeddedGoTemplateTags`

Type: string[]
Default: ["goTemplate", "gotmpl"]
Description: Tags that identify embedded Go Template in template literals. Requires the @htnabe/prettier-plugin-go-template plugin.

Formatting embedded Go Template requires the @htnabe/prettier-plugin-go-template plugin to be installed and loaded. Its options control the embedded formatting behavior.

GraphQL

`embeddedGraphqlComments`

Type: string[]
Default: ["graphql", "gql"]
Description: Block comments that make their subsequent template literals be identified as embedded GraphQL language.

`embeddedGraphqlTags`

Type: string[]
Default: ["graphql", "gql"]
Description: Tags that make their subsequent template literals be identified as embedded GraphQL language.

Embedded GraphQL uses the parsers and printers included with Prettier.

This can override the native formatting behavior for embedded GraphQL language. If you want to keep the native behavior, set embeddedGraphqlComments or embeddedGraphqlTags to [] or other values.

Handlebars

`embeddedHandlebarsComments`

Type: string[]
Default: ["handlebars", "hbs"]
Description: Block comments that identify embedded Handlebars in template literals. Requires the @poliklot/prettier-plugin-handlebars plugin.

`embeddedHandlebarsTags`

Type: string[]
Default: ["handlebars", "hbs"]
Description: Tags that identify embedded Handlebars in template literals. Requires the @poliklot/prettier-plugin-handlebars plugin.

Formatting embedded Handlebars requires the @poliklot/prettier-plugin-handlebars plugin to be installed and loaded. Its options control the embedded formatting behavior.

HTML

`embeddedHtmlComments`

Type: string[]
Default: ["html", "xhtml"]
Description: Block comments that make their subsequent template literals be identified as embedded HTML language.

`embeddedHtmlTags`

Type: string[]
Default: ["html", "xhtml"]
Description: Tags that make their subsequent template literals be identified as embedded HTML language.

`embeddedHtmlParser`

Type: "html" | "vue" | "angular" | "lwc"
Default: "html"
Description: The parser used to parse the embedded HTML language.

Embedded HTML uses the parsers and printers included with Prettier.

This can override the native formatting behavior for embedded HTML language. If you want to keep the native behavior, set embeddedHtmlComments or embeddedHtmlTags to [] or other values.

If you want to specify different parsers for different comments or tags, check embeddedOverrides.

Hugo

`embeddedHugoComments`

Type: string[]
Default: ["hugo", "hugoPost"]
Description: Block comments that identify embedded Hugo in template literals. Requires the @htnabe/prettier-plugin-hugo-post plugin.

`embeddedHugoTags`

Type: string[]
Default: ["hugo", "hugoPost"]
Description: Tags that identify embedded Hugo in template literals. Requires the @htnabe/prettier-plugin-hugo-post plugin.

Formatting embedded Hugo requires the @htnabe/prettier-plugin-hugo-post plugin to be installed and loaded. Its options control the embedded formatting behavior.

INI

`embeddedIniComments`

Type: string[]
Default: ["ini", "cfg", "pro"]
Description: Block comments that make their subsequent template literals be identified as embedded INI language. This option requires the prettier-plugin-ini plugin.

`embeddedIniTags`

Type: string[]
Default: ["ini", "cfg", "pro"]
Description: Tags that make their subsequent template literals be identified as embedded INI language. This option requires the prettier-plugin-ini plugin.

Formatting embedded INI language requires the prettier-plugin-ini plugin to be loaded as well. And options supported by prettier-plugin-ini can therefore be used to further control the formatting behavior.

Java

`embeddedJavaComments`

Type: string[]
Default: ["java"]
Description: Block comments that make their subsequent template literals be identified as embedded Java language. This option requires the prettier-plugin-java plugin.

`embeddedJavaTags`

Type: string[]
Default: ["java"]
Description: Tags that make their subsequent template literals be identified as embedded Java language. This option requires the prettier-plugin-java plugin.

Formatting embedded Java language requires the prettier-plugin-java plugin to be loaded as well. And options supported by prettier-plugin-java can therefore be used to further control the formatting behavior.

Jinja

`embeddedJinjaComments`

Type: string[]
Default: ["jinja", "jinja2", "j2"]
Description: Block comments that identify embedded Jinja in template literals. Requires the prettier-plugin-jinja-template plugin.

`embeddedJinjaTags`

Type: string[]
Default: ["jinja", "jinja2", "j2"]
Description: Tags that identify embedded Jinja in template literals. Requires the prettier-plugin-jinja-template plugin.

Formatting embedded Jinja requires the prettier-plugin-jinja-template plugin to be installed and loaded. Its options control the embedded formatting behavior.

The formatter uses the source block's line breaks to choose its layout. Write block bodies across lines for consistent formatting when their content wraps.

JSON

`embeddedJsonComments`

Type: string[]
Default: ["json", "jsonl"]
Description: Block comments that make their subsequent template literals be identified as embedded JSON language.

`embeddedJsonTags`

Type: string[]
Default: ["json", "jsonl"]
Description: Tags that make their subsequent template literals be identified as embedded JSON language.

`embeddedJsonParser`

Type: "json" | "json5" | "jsonc" | "json-stringify"
Default: "json"
Description: The parser used to parse the embedded JSON language.

Embedded JSON uses the parsers and printers included with Prettier.

If you want to specify different parsers for different comments or tags, check embeddedOverrides.

JSONata

`embeddedJsonataComments`

Type: string[]
Default: ["jsonata"]
Description: Block comments that make their subsequent template literals be identified as embedded JSONata language. This option requires the @stedi/prettier-plugin-jsonata plugin.

`embeddedJsonataTags`

Type: string[]
Default: ["jsonata"]
Description: Tags that make their subsequent template literals be identified as embedded JSONata language. This option requires the @stedi/prettier-plugin-jsonata plugin.

Formatting embedded JSONata language requires the @stedi/prettier-plugin-jsonata plugin to be loaded as well.

JTE

`embeddedJteComments`

Type: string[]
Default: ["jte"]
Description: Block comments that identify embedded JTE in template literals. Requires the prettier-plugin-jte plugin.

`embeddedJteTags`

Type: string[]
Default: ["jte"]
Description: Tags that identify embedded JTE in template literals. Requires the prettier-plugin-jte plugin.

Formatting embedded JTE requires the prettier-plugin-jte plugin to be installed and loaded. Its options control the embedded formatting behavior.

LaTeX

`embeddedLatexComments`

Type: string[]
Default: ["latex", "tex", "aux", "cls", "bbl", "bib", "toc", "sty"]
Description: Block comments that make their subsequent template literals be identified as embedded LaTeX language. This option requires the prettier-plugin-latex plugin.

`embeddedLatexTags`

Type: string[]
Default: ["latex", "tex", "aux", "cls", "bbl", "bib", "toc", "sty"]
Description: Tags that make their subsequent template literals be identified as embedded LaTeX language. This option requires the prettier-plugin-latex plugin.

Formatting embedded LaTeX language requires the prettier-plugin-latex plugin to be loaded as well.

Liquid

`embeddedLiquidComments`

Type: string[]
Default: ["liquid"]
Description: Block comments that identify embedded Liquid in template literals. Requires the @shopify/prettier-plugin-liquid plugin.

`embeddedLiquidTags`

Type: string[]
Default: ["liquid"]
Description: Tags that identify embedded Liquid in template literals. Requires the @shopify/prettier-plugin-liquid plugin.

Formatting embedded Liquid requires the @shopify/prettier-plugin-liquid plugin to be installed and loaded. Its options control the embedded formatting behavior.

Markdown

`embeddedMarkdownComments`

Type: string[]
Default: ["md", "markdown"]
Description: Block comments that make their subsequent template literals be identified as embedded Markdown language.

`embeddedMarkdownTags`

Type: string[]
Default: ["md", "markdown"]
Description: Tags that make their subsequent template literals be identified as embedded Markdown language.

`embeddedMarkdownParser`

Type: "markdown" | "mdx" | "remark"
Default: "markdown"
Description: The parser used to parse the embedded Markdown language.

Embedded Markdown uses the parsers and printers included with Prettier.

This can override the native formatting for embedded Markdown language. If you want to keep the native behavior, set embeddedMarkdownComments or embeddedMarkdownTags to [] or other values.

If you want to specify different parsers for different comments or tags, check embeddedOverrides.

The remark parser is an alias of the markdown parser.

Marko

`embeddedMarkoComments`

Type: string[]
Default: ["marko"]
Description: Block comments that identify embedded Marko in template literals. Requires the prettier-plugin-marko plugin.

`embeddedMarkoTags`

Type: string[]
Default: ["marko"]
Description: Tags that identify embedded Marko in template literals. Requires the prettier-plugin-marko plugin.

Formatting embedded Marko requires the prettier-plugin-marko plugin to be installed and loaded. Its options control the embedded formatting behavior.

Motoko

`embeddedMotokoComments`

Type: string[]
Default: ["motoko", "mo"]
Description: Block comments that identify embedded Motoko in template literals. Requires the prettier-plugin-motoko plugin.

`embeddedMotokoTags`

Type: string[]
Default: ["motoko", "mo"]
Description: Tags that identify embedded Motoko in template literals. Requires the prettier-plugin-motoko plugin.

Formatting embedded Motoko requires the prettier-plugin-motoko plugin to be installed and loaded. Its options control the embedded formatting behavior.

Mustache

`embeddedMustacheComments`

Type: string[]
Default: ["mustache"]
Description: Block comments that identify embedded Mustache in template literals. Requires the prettier-plugin-mustache plugin.

`embeddedMustacheTags`

Type: string[]
Default: ["mustache"]
Description: Tags that identify embedded Mustache in template literals. Requires the prettier-plugin-mustache plugin.

Formatting embedded Mustache requires the prettier-plugin-mustache plugin to be installed and loaded. Its options control the embedded formatting behavior.

NGINX

`embeddedNginxComments`

Type: string[]
Default: ["nginx"]
Description: Block comments that make their subsequent template literals be identified as embedded NGINX language. This option requires the prettier-plugin-nginx plugin.

`embeddedNginxTags`

Type: string[]
Default: ["nginx"]
Description: Tags that make their subsequent template literals be identified as embedded NGINX language. This option requires the prettier-plugin-nginx plugin.

Formatting embedded NGINX language requires the prettier-plugin-nginx plugin to be loaded as well. And options supported by prettier-plugin-nginx can therefore be used to further control the formatting behavior.

Nunjucks

`embeddedNunjucksComments`

Type: string[]
Default: ["nunjucks", "njk"]
Description: Block comments that identify embedded Nunjucks in template literals. Requires the prettier-plugin-nunjucks plugin.

`embeddedNunjucksTags`

Type: string[]
Default: ["nunjucks", "njk"]
Description: Tags that identify embedded Nunjucks in template literals. Requires the prettier-plugin-nunjucks plugin.

Formatting embedded Nunjucks requires the prettier-plugin-nunjucks plugin to be installed and loaded. Its options control the embedded formatting behavior.

Pegjs

`embeddedPegjsComments`

Type: string[]
Default: ["pegjs", "peggy", "peg"]
Description: Block comments that make their subsequent template literals be identified as embedded Pegjs language. This option requires the prettier-plugin-pegjs plugin.

`embeddedPegjsTags`

Type: string[]
Default: ["pegjs", "peggy", "peg"]
Description: Tags that make their subsequent template literals be identified as embedded Pegjs language. This option requires the prettier-plugin-pegjs plugin.

Formatting embedded Pegjs language requires the prettier-plugin-pegjs plugin to be loaded as well. And options supported by prettier-plugin-pegjs can therefore be used to further control the formatting behavior.

Note that prettier-plugin-pegjs supports different parsers for the action blocks and they are specified by the actionParser option. If you want to specify different action parsers for different comments or tags, check embeddedOverrides.

PHP

`embeddedPhpComments`

Type: string[]
Default: ["php", "php5"]
Description: Block comments that make their subsequent template literals be identified as embedded PHP language. This option requires the @prettier/plugin-php plugin.

`embeddedPhpTags`

Type: string[]
Default: ["php", "php5"]
Description: Tags that make their subsequent template literals be identified as embedded PHP language. This option requires the @prettier/plugin-php plugin.

Formatting embedded PHP language requires the @prettier/plugin-php plugin to be loaded as well. And options supported by @prettier/plugin-php can therefore be used to further control the formatting behavior.

PowerShell

`embeddedPowerShellComments`

Type: string[]
Default: ["powershell", "ps1"]
Description: Block comments that identify embedded PowerShell in template literals. Requires the prettier-plugin-powershell plugin.

`embeddedPowerShellTags`

Type: string[]
Default: ["powershell", "ps1"]
Description: Tags that identify embedded PowerShell in template literals. Requires the prettier-plugin-powershell plugin.

Formatting embedded PowerShell requires the prettier-plugin-powershell plugin to be installed and loaded. Its options control the embedded formatting behavior.

Prisma

`embeddedPrismaComments`

Type: string[]
Default: ["prisma"]
Description: Block comments that make their subsequent template literals be identified as embedded Prisma language. This option requires the prettier-plugin-prisma plugin.

`embeddedPrismaTags`

Type: string[]
Default: ["prisma"]
Description: Tags that make their subsequent template literals be identified as embedded Prisma language. This option requires the prettier-plugin-prisma plugin.

Formatting embedded Prisma language requires the prettier-plugin-prisma plugin to be loaded as well.

Properties

`embeddedPropertiesComments`

Type: string[]
Default: ["properties"]
Description: Block comments that make their subsequent template literals be identified as embedded Properties language. This option requires the prettier-plugin-properties plugin.

`embeddedPropertiesTags`

Type: string[]
Default: ["properties"]
Description: Tags that make their subsequent template literals be identified as embedded Properties language. This option requires the prettier-plugin-properties plugin.

Formatting embedded Properties language requires the prettier-plugin-properties plugin to be loaded as well. And options supported by prettier-plugin-properties can therefore be used to further control the formatting behavior.

Pug

`embeddedPugComments`

Type: string[]
Default: ["pug", "jade"]
Description: Block comments that make their subsequent template literals be identified as embedded Pug language. This option requires the @prettier/plugin-pug plugin.

`embeddedPugTags`

Type: string[]
Default: ["pug", "jade"]
Description: Tags that make their subsequent template literals be identified as embedded Pug language. This option requires the @prettier/plugin-pug plugin.

Formatting embedded Pug language requires the @prettier/plugin-pug plugin to be loaded as well. And options supported by @prettier/plugin-pug can therefore be used to further control the formatting behavior.

Ruby

`embeddedRubyComments`

Type: string[]
Default: ["ruby"]
Description: Block comments that make their subsequent template literals be identified as embedded Ruby language. This option requires the @prettier/plugin-ruby plugin.

`embeddedRubyTags`

Type: string[]
Default: ["ruby"]
Description: Tags that make their subsequent template literals be identified as embedded Ruby language. This option requires the @prettier/plugin-ruby plugin.

`embeddedRubyParser`

Type: "ruby" | "rbs" | "haml"
Default: "ruby"
Description: The parser used to parse the embedded Ruby language. This option requires the @prettier/plugin-ruby plugin.

Formatting embedded Ruby language requires the @prettier/plugin-ruby to be loaded and its dependencies to be installed as well. And options supported by @prettier/plugin-ruby can therefore be used to further control the formatting behavior.

If you want to specify different parsers for different comments or tags, check embeddedOverrides.

Sh (Shell)

`embeddedShComments`

Type: string[]
Default: ["sh"]
Description: Block comments that make their subsequent template literals be identified as embedded Shell language. This option requires the prettier-plugin-sh plugin.

`embeddedShTags`

Type: string[]
Default: ["sh"]
Description: Tags that make their subsequent template literals be identified as embedded Shell language. This option requires the prettier-plugin-sh plugin.

Formatting embedded Shell language requires the prettier-plugin-sh plugin to be loaded as well. And options supported by prettier-plugin-sh can therefore be used to further control the formatting behavior.

Note that prettier-plugin-sh supports different variants of shell syntaxes and they are specified by the variant option. If you want to specify different variants for different comments or tags, check embeddedOverrides.

Solidity

`embeddedSolidityComments`

Type: string[]
Default: ["solidity", "sol"]
Description: Block comments that identify embedded Solidity in template literals. Requires the prettier-plugin-solidity plugin.

`embeddedSolidityTags`

Type: string[]
Default: ["solidity", "sol"]
Description: Tags that identify embedded Solidity in template literals. Requires the prettier-plugin-solidity plugin.

`embeddedSolidityParser`

Type: "slang" | "antlr" | "solidity-parse"
Default: "slang"
Description: The parser used to format embedded Solidity.

Formatting embedded Solidity requires the prettier-plugin-solidity plugin to be installed and loaded. Its options control the embedded formatting behavior.

Choose "slang" or "antlr" with current formatter versions. Formatter versions exposing "solidity-parse" use embeddedSolidityParser: "solidity-parse".

SQL

`embeddedSqlComments`

Type: string[]
Default: ["sql"]
Description: Block comments that make their subsequent template literals be identified as embedded SQL language. This option requires the prettier-plugin-sql plugin or the prettier-plugin-sql-cst plugin.

`embeddedSqlTags`

Type: string[]
Default: ["sql"]
Description: Tags that make their subsequent template literals be identified as embedded SQL language. This option requires the prettier-plugin-sql plugin or the prettier-plugin-sql-cst plugin.

`embeddedSqlPlugin`

Type: "prettier-plugin-sql" | "prettier-plugin-sql-cst"
Default: "prettier-plugin-sql"
Description: The plugin used to format the embedded SQL language. This option requires the prettier-plugin-sql plugin or the prettier-plugin-sql-cst plugin.

`embeddedSqlParser`

Type: "sqlite" | "bigquery" | "mysql" | "mariadb" | "postgresql"
Default: "sqlite"
Description: Specify the embedded SQL language parser. This option is only needed with the prettier-plugin-sql-cst plugin.

Formatting embedded SQL language requires the prettier-plugin-sql plugin or the prettier-plugin-sql-cst plugin to be loaded as well. And options supported by prettier-plugin-sql, or options supported by prettier-plugin-sql-cst can therefore be used to further control the formatting behavior.

Note that prettier-plugin-sql supports many different SQL dialects which are specified by the language, database or dialect option. And prettier-plugin-sql-cst also supports various parsers as shown above. If you want to specify different dialects or parsers for different comments or tags, check embeddedOverrides.

Svelte

`embeddedSvelteComments`

Type: string[]
Default: ["svelte"]
Description: Block comments that identify embedded Svelte in template literals. Requires the prettier-plugin-svelte plugin.

`embeddedSvelteTags`

Type: string[]
Default: ["svelte"]
Description: Tags that identify embedded Svelte in template literals. Requires the prettier-plugin-svelte plugin.

Formatting embedded Svelte requires the prettier-plugin-svelte plugin to be installed and loaded. Its options control the embedded formatting behavior.

Supply the svelte compiler alongside the formatter plugin, using versions compatible with the project's Svelte version.

TOML

`embeddedTomlComments`

Type: string[]
Default: ["toml"]
Description: Block comments that make their subsequent template literals be identified as embedded TOML language. This option requires the prettier-plugin-toml plugin.

`embeddedTomlTags`

Type: string[]
Default: ["toml"]
Description: Tags that make their subsequent template literals be identified as embedded TOML language. This option requires the prettier-plugin-toml plugin.

Formatting embedded TOML language requires the prettier-plugin-toml plugin to be loaded as well. And options supported by prettier-plugin-toml can therefore be used to further control the formatting behavior.

prettier-plugin-toml 4 requires Node.js 20 or later and its platform-specific optional native dependency. Keep optional dependencies enabled when installing it. Use version 3 for Node.js 18.

TS (TypeScript)

`embeddedTsComments`

Type: string[]
Default: ["ts", "tsx", "cts", "mts", "typescript"]
Description: Block comments that make their subsequent template literals be identified as embedded TypeScript language.

`embeddedTsTags`

Type: string[]
Default: ["ts", "tsx", "cts", "mts", "typescript"]
Description: Tags that make their subsequent template literals be identified as embedded TypeScript language.

`embeddedTsParser`

Type: "typescript" | "babel-ts"
Default: "typescript"
Description: The parser used to parse the embedded TypeScript language.

Embedded TypeScript uses the parsers and printers included with Prettier.

If you want to specify different parsers for different comments or tags, check embeddedOverrides.

XML

`embeddedXmlComments`

Type: string[]
Default: ["xml", "opml", "rss", "svg"]
Description: Block comments that make their subsequent template literals be identified as embedded XML language. This option requires the @prettier/plugin-xml plugin.

`embeddedXmlTags`

Type: string[]
Default: ["xml", "opml", "rss", "svg"]
Description: Tags that make their subsequent template literals be identified as embedded XML language. This option requires the @prettier/plugin-xml plugin.

Embedded XML uses the parser provided by @prettier/plugin-xml, which must be loaded when XML formatting is enabled. Its options control the XML formatting behavior.

Use version 3 or later with Prettier 3. Version 2 uses the older Prettier 2 embed API and is incompatible.

XQuery

`embeddedXQueryComments`

Type: string[]
Default: ["xquery", "xq"]
Description: Block comments that identify embedded XQuery in template literals. Requires the prettier-plugin-xquery plugin.

`embeddedXQueryTags`

Type: string[]
Default: ["xquery", "xq"]
Description: Tags that identify embedded XQuery in template literals. Requires the prettier-plugin-xquery plugin.

`embeddedXQueryParser`

Type: "xquery" | "xquery4"
Default: "xquery"
Description: The parser used to format embedded XQuery.

Formatting embedded XQuery requires the prettier-plugin-xquery plugin to be installed and loaded. Its options control the embedded formatting behavior.

The default "xquery" parser formats XQuery 3.1. Select "xquery4" for the XQuery 4 syntax supported by the installed formatter version.

YAML

`embeddedYamlComments`

Type: string[]
Default: ["yaml", "yml"]
Description: Block comments that make their subsequent template literals be identified as embedded YAML language.

`embeddedYamlTags`

Type: string[]
Default: ["yaml", "yml"]
Description: Tags that make their subsequent template literals be identified as embedded YAML language.

Embedded YAML uses the parsers and printers included with Prettier.

Language-Agnostic Options

Language-Agnostic

`preserveEmbeddedExteriorWhitespaces`

Type: string[]
Default: []
Description: Preserves leading and trailing whitespaces in the formatting results for the specified comments or tags.

This preserves the original exterior whitespace characters, including their indentation. Without this option, whitespace-sensitive markup such as HTML and Jinja preserves whether boundary whitespace exists and allows its indentation to be formatted.

Preserved multiline boundary indentation also sets the margin for subsequent content lines. No extra template indentation is added, including when this option is combined with noEmbeddedMultiLineIndentation. If content starts on the same line as the opening backtick, its preserved margin is zero. Content indentation, such as the four spaces of a Markdown code block, belongs to the content rather than to exterior whitespace.

`noEmbeddedMultiLineIndentation`

Type: string[]
Default: []
Description: Turns off auto indentation in the formatting results for the specified comments or tags when they are formatted to span multi lines.

This prints embedded content from the current document root without inheriting the surrounding JavaScript or TypeScript indentation. Indentation within the embedded language is still formatted. For example, "noEmbeddedMultiLineIndentation": ["html", "jinja"] disables automatic template indentation for both tags and comments. It can be combined with preserveEmbeddedExteriorWhitespaces, which takes precedence and uses the original boundary margin.

Markdown retains its root-aligned behavior, so headings inside deeply nested JavaScript do not become indented code blocks. Other languages now follow the same rule. This option affects output layout only; it does not change how the embedded source is parsed or remove its lists, code blocks, or other meaningful indentation. YAML content uses spaces for its internal indentation even when the host uses tabs.

Before parsing, the plugin removes only the exact whitespace prefix shared by every nonempty content line. A column-zero content line makes that prefix empty. This template margin is determined before trimming boundary whitespace, and tabs and spaces are compared literally. The remaining indentation is passed to the language formatter. This convention applies equally to tags and comments and to both indentation options. It treats a common prefix as template framing; Markdown consisting entirely of indented code can use a fenced code block to make its intent explicit.

The plugin formats template source and does not insert a runtime dedent operation. For raw whitespace-sensitive values, author content without a common source margin and enable noEmbeddedMultiLineIndentation to keep automatic host indentation out of the string value.

`embeddedOverrides`

Type: string
Default: undefined
Description: Option overrides for the specified comments or tags. It should either be a stringified JSON or an absolute filepath to the option overrides file. See below for a detailed explanation.

`embeddedOverrides`

This option is provided for users to override certain options based on comments or tags. Due to the lack of support for using objects in prettier plugin options (https://github.com/prettier/prettier/issues/14671), it accepts a stringified json string, or a file path with an extension of .json, .jsonc, .js, .cjs, .mjs, .ts, .cts or .mts as its value. If no extension is provided, it will be treated as a .json/.jsonc file. For relative paths, it will automatically figure out the prettier config location and use that as the base path.

TypeScript override files (.ts, .mts and .cts) are loaded with the active runtime's import(). Node.js with native type stripping enabled can load erasable TypeScript, and Bun provides native TypeScript loading. The runtime determines module semantics: .mts uses ES modules, .cts uses CommonJS, and .ts follows the package's module type.

Consumers can enable a compatible loader through Node.js startup options, such as node --import tsx node_modules/prettier/bin/prettier.cjs . --write. Override files are evaluated in workers, which inherit the runtime's startup preloads. Enable synchronous module hooks through a --import or --require preload so they are available in those workers. When the runtime reports unsupported module loading or TypeScript transformation, the plugin can use the consumer project's optional tsx 4.19+ installation as a fallback. This fallback uses Node.js's module.register() API, introduced in Node.js 18.19 and 20.6. Configuration errors include their original diagnostics.

The Prettier VS Code extension uses its bundled Node.js runtime; JavaScript override files provide the simplest editor setup.

Each override module load uses a fresh worker and module cache, so edits to the override file and its imported modules are reflected in subsequent formatting calls. Workers are released after the configuration has been read. Relative paths follow Prettier's configuration discovery and its clearConfigCache() API.

The resolved value should be an array of objects. Each object in the array must have 2 fields: comments and options, or tags and options. The options are considered overrides that will be applied to the global options of prettier for those comments and tags only. It's like the overrides of prettier, but it is comment/tag-based instead of file-based.

Per-tag overrides refer to the matching entry from embedded<Language>Tags, including the pattern string when a regular expression matches. The first matching override applies. For example, this JavaScript configuration gives embedded JavaScript selected by query its own quote style:

export default {
  plugins: ["prettier-plugin-embed"],
  embeddedEsTags: ["/^query$/"],
  embeddedOverrides: JSON.stringify([
    { tags: ["/^query$/"], options: { singleQuote: true } },
  ]),
};

Embedded parsers receive the override options. The resulting document is laid out with the surrounding JavaScript or TypeScript document, using the outer Prettier printWidth.

In a json file, the root is the array of objects. In a JavaScript/TypeScript file, the array of objects should be a default export, or a named export with the name embeddedOverrides.

An example .json/.jsonc file is:

[
  {
    "comments": ["sql"],
    "options": {
      "keywordCase": "lower"
    }
  },
  {
    "tags": ["mysql"],
    "options": {
      "keywordCase": "upper"
    }
  }
]

[!CAUTION]
embeddedOverrides supports options applied during parsing and document generation. Options applied during final document printing, such as tabWidth, are configured globally. The EmbeddedOverride interface lists the supported override options.

Typed Options

There're several ways to use the typed options provided by this plugin. Taking the embedded SQL language as an example:

Augment the Options type from Prettier to use plugin-specific options

/// <reference types="prettier-plugin-embed/plugin-embed" />

/// <reference types="prettier-plugin-embed/embedded/sql/plugin-sql" />

Other embedded languages share the same pattern:

/// <reference types="prettier-plugin-embed/embedded/<language>/<(no prettier or scope) plugin name>" />

Import plugin-specific options
Import options from prettier-plugin-embed (this plugin):
```
import type { PluginEmbedOptions } from "prettier-plugin-embed";
```
Import options from prettier-plugin-sql:
```
import type { PluginSqlOptions } from "prettier-plugin-embed/embedded/sql/plugin-sql-types";
```
NOTE: You can also import the types from the prettier-plugin-sql plugin directly. However, not all of the plugins provide types, or provide them in a predictable way, so this plugin exports them in a more unified manner.
Other embedded languages share the same pattern:
```
import type { Plugin<Language>Options } from "prettier-plugin-embed/embedded/<language>/<(no prettier or scope) plugin name>-types";
```

Use JSDoc in JavaScript files

/**
 * @type {import("prettier-plugin-embed").PluginEmbedOptions}
 */
const pluginEmbedOptions = {
  embeddedSqlTags: ["sql"],
};

/**
 * @type {import("prettier-plugin-embed/embedded/sql/plugin-sql-types").PluginSqlOptions}
 */
const pluginSqlOptions = {
  language: "postgresql",
  keywordCase: "upper",
};

Contributing

Bug fixes, new language support and tests are welcome. Please have a look at the project structure before getting started. Feel free to leave questions or suggestions.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Prettier Plugin Embed

Introduction

What?

Why?

How?

Features

Installation

Usage

Playground

Getting Started

CLI:

API:

Configuration File:

Quick Start Config Examples

An Overview of the Philosophy

Language-Specific Options

NOOP

embeddedNoopComments

embeddedNoopTags

Astro

embeddedAstroComments

embeddedAstroTags

CSS

embeddedCssComments

embeddedCssTags

embeddedCssParser

Dockerfile

embeddedDockerfileComments

embeddedDockerfileTags

ES (ECMAScript/JavaScript)

embeddedEsComments

embeddedEsTags

embeddedEsParser

Gherkin

embeddedGherkinComments

embeddedGherkinTags

GLSL

embeddedGlslComments

embeddedGlslTags

Go Template

embeddedGoTemplateComments

embeddedGoTemplateTags

GraphQL

embeddedGraphqlComments

embeddedGraphqlTags

Handlebars

embeddedHandlebarsComments

embeddedHandlebarsTags

HTML

embeddedHtmlComments

embeddedHtmlTags

embeddedHtmlParser

Hugo

embeddedHugoComments

embeddedHugoTags

INI

embeddedIniComments

embeddedIniTags

Java

embeddedJavaComments

embeddedJavaTags

Jinja

embeddedJinjaComments

embeddedJinjaTags

JSON

embeddedJsonComments

embeddedJsonTags

embeddedJsonParser

JSONata

embeddedJsonataComments

embeddedJsonataTags

JTE

embeddedJteComments

embeddedJteTags

`embeddedNoopComments`

`embeddedNoopTags`

`embeddedAstroComments`

`embeddedAstroTags`

`embeddedCssComments`

`embeddedCssTags`

`embeddedCssParser`

`embeddedDockerfileComments`

`embeddedDockerfileTags`

`embeddedEsComments`

`embeddedEsTags`

`embeddedEsParser`

`embeddedGherkinComments`

`embeddedGherkinTags`

`embeddedGlslComments`

`embeddedGlslTags`

`embeddedGoTemplateComments`

`embeddedGoTemplateTags`

`embeddedGraphqlComments`

`embeddedGraphqlTags`

`embeddedHandlebarsComments`

`embeddedHandlebarsTags`

`embeddedHtmlComments`

`embeddedHtmlTags`

`embeddedHtmlParser`

`embeddedHugoComments`

`embeddedHugoTags`

`embeddedIniComments`

`embeddedIniTags`

`embeddedJavaComments`

`embeddedJavaTags`

`embeddedJinjaComments`

`embeddedJinjaTags`

`embeddedJsonComments`

`embeddedJsonTags`

`embeddedJsonParser`

`embeddedJsonataComments`

`embeddedJsonataTags`

`embeddedJteComments`

`embeddedJteTags`

`embeddedLatexComments`

`embeddedLatexTags`

`embeddedLiquidComments`

`embeddedLiquidTags`

`embeddedMarkdownComments`

`embeddedMarkdownTags`

`embeddedMarkdownParser`

`embeddedMarkoComments`

`embeddedMarkoTags`

`embeddedMotokoComments`

`embeddedMotokoTags`

`embeddedMustacheComments`

`embeddedMustacheTags`

`embeddedNginxComments`

`embeddedNginxTags`

`embeddedNunjucksComments`

`embeddedNunjucksTags`

`embeddedPegjsComments`

`embeddedPegjsTags`

`embeddedPhpComments`

`embeddedPhpTags`

`embeddedPowerShellComments`

`embeddedPowerShellTags`

`embeddedPrismaComments`

`embeddedPrismaTags`

`embeddedPropertiesComments`