prettier-plugin-embed
v0.4.15
Published
A configurable Prettier plugin to format embedded languages in JS/TS files.
Downloads
108,795
Maintainers
Readme
Prettier Plugin Embed
A configurable Prettier plugin to format embedded languages in JS/TS Files.
npm i -D prettier-plugin-embed
Introduction
What?
This Prettier plugin (namely prettier-plugin-embed
) provides a configurable solution for formatting embedded languages in the form of template literals within JavaScript or TypeScript files.
Why?
Prettier has introduced an option for formatting embedded languages, named embedded-language-formatting
. However, this option only offers two modes: auto
and off
. This limits its functionality, as it does not permit individual formatting adjustments for specific languages. Additionally, it lacks support for customizing which languages require formatting, as well as specifying block comments or tags for embedded language identification. These constraints hinder the feature's overall usability. For in-depth discussions on this matter, see the GitHub issues: prettier/prettier#4424 and prettier/prettier#5588.
How?
By leveraging Prettier's plugin system, this plugin overrides the default embed
function of the estree
printer, so varieties of new languages can be hooked in through this function. Check this file to get an idea of how this is accomplished.
Features
Support for Additional Languages: Extend the embedded language formatting capability to include languages such as XML, SQL, PHP, and more.
Dual Identification Modes: Identify embedded languages by block comments
/* comment */ `...`
or tagstag`...`
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 theembedded-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-plugin-embed
Usage
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"]
}
Quick Start Config Examples
Here're some quick start config examples to use this plugin for various embedded languages. Check beblow for a detailed explanation of all the available options.
An Overview of the Philosophy
To use this plugin, embedded-language-formatting
option must be set to auto
(which is the default setting as of now), because this option serves as the main switch for activating embedded language formatting.
This plugin does not aim to implement parsers or printers to support every newly added embedded language. Rather, it aims to leverage existing Prettier plugins for those languages, and only adds a thin layer of formatting support when they are embedded in template literals.
Therefore, to enable formatting for a specific embedded language, the corresponding Prettier plugin for that language must also be loaded. For example, if you wish to format embedded XML language, you will need to load both this plugin and @prettier/plugin-xml
. To find out which other plugins are required when using this plugin, please refer to the Language-Specific Options section below.
Embedded languages to be formatted are required to be enclosed in the template literals, and are identified by the preceding block comments /* comment */ `...`
or tags tag`...`
. This plugin comes pre-configured with a built-in set of comments and tags for identifying various embedded languages. For instance, using comments like /* xml */
or /* svg */
or tags like xml
or svg
will trigger automatic formatting for the embedded XML language. You can specify an alternative list of comments or tags using the embeddedXmlComments
option or the embeddedXmlTags
option, respectively. The naming convention for these options follows the pattern of embedded<Language>Comments
and embedded<Language>Tags
for other languages as well. Further details on these options and how to configure them are also available in the Language-Specific Options section.
To exclude certain comments or tags from being identified, like the default ones supported by the embedded-language-formatting
option, add them to the list of the embeddedNoopComments
/embeddedNoopTags
options. Any matching comments or tags listed in these options will take precedence over other embedded<Language>Comments
and embedded<Language>Tags
options, effectively disabling their formatting.
[!IMPORTANT]
Until this notice is removed, always specify comments or tags explicitly and do not rely on the built-in defaults, as they may be subject to change.
Language-Specific Options
Supported embedded languages are:
- CSS
- ES (ECMAScript/JavaScript)
- GLSL
- GraphQL
- HTML
- INI
- Java
- JSON
- JSONata
- LaTeX
- Markdown
- NGINX
- Pegjs
- PHP
- Prisma
- Properties
- Pug
- Ruby
- Sh (Shell)
- SQL
- TOML
- TS (TypeScript)
- XML
- YAML
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.
~~embeddedNoopIdentifiers
~~
- Type:
string[]
- Default:
[]
- Description: Comment or tag identifiers that prevent their subsequent template literals from being identified as embedded languages and thus from being formatted.
Please use embeddedNoopComments
or embeddedNoopTags
.
This "language" doesn't require other plugins and can override the native embedded language formatting. It serves as a way to turn off embedded language formatting for the specified language comments or tags.
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.
~~embeddedCssIdentifiers
~~
- Type:
string[]
- Default:
["css"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded CSS language.
Please use embeddedCssComments
or embeddedCssTags
.
embeddedCssParser
- Type:
"css" | "less" | "scss"
- Default:
"scss"
- Description: The parser used to parse the embedded CSS language.
Formatting embedded CSS language doesn't require other plugins and uses the parsers and printers provided by Prettier natively.
This can override the native formatting bahavior 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
.
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.
~~embeddedEsIdentifiers
~~
- Type:
string[]
- Default:
["js", "jsx", "es", "es6", "mjs", "cjs", "pac", "javascript"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded ECMAScript/JavaScript language.
Please use embeddedEsComments
or embeddedEsTags
.
embeddedEsParser
- Type:
"babel" | "babel-flow" | "acorn" | "espree" | "flow" | "meriyah"
- Default:
"babel"
- Description: The parser used to parse the embedded ECMASCript/JavaScript language.
Formatting embedded ECMAScript/JavaScript language doesn't require other plugins and uses the parsers and printers provided by Prettier natively.
If you want to specify different parsers for different comments or tags, check embeddedOverrides
.
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.
~~embeddedGlslIdentifiers
~~
- Type:
string[]
- Default:
["glsl", "shader"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded GLSL language. This option requires the
prettier-plugin-glsl
plugin.
Please use embeddedGlslComments
or embeddedGlslTags
.
Formatting embedded GLSL language requires the prettier-plugin-glsl
plugin to be loaded as well.
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.
~~embeddedGraphqlIdentifiers
~~
- Type:
string[]
- Default:
["graphql", "gql"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded GraphQL language.
Please use embeddedGraphqlComments
or embeddedGraphqlTags
.
Formatting embedded GraphQL language doesn't require other plugins and uses the parsers and printers provided by Prettier natively.
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.
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.
~~embeddedHtmlIdentifiers
~~
- Type:
string[]
- Default:
["html", "xhtml"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded HTML language.
Please use embeddedHtmlComments
or embeddedHtmlTags
.
embeddedHtmlParser
- Type:
"html" | "vue" | "angular" | "lwc"
- Default:
"html"
- Description: The parser used to parse the embedded HTML language.
Formatting embedded HTML language doesn't require other plugins and uses the parsers and printers provided by Prettier natively.
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
.
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.
~~embeddedIniIdentifiers
~~
- Type:
string[]
- Default:
["ini", "cfg", "pro"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded INI language. This option requires the
prettier-plugin-ini
plugin.
Please use embeddedIniComments
or embeddedIniTags
.
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.
~~embeddedJavaIdentifiers
~~
- Type:
string[]
- Default:
["java"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded Java language. This option requires the
prettier-plugin-java
plugin.
Please use embeddedJavaComments
or embeddedJavaTags
.
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.
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.
~~embeddedJsonIdentifiers
~~
- Type:
string[]
- Default:
["json", "jsonl"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded JSON language.
Please use embeddedJsonComments
or embeddedJsonTags
.
embeddedJsonParser
- Type:
"json" | "json5" | "jsonc" | "json-stringify"
- Default:
"json"
- Description: The parser used to parse the embedded JSON language.
Formatting embedded JSON language doesn't require other plugins and uses the parsers and printers provided by Prettier natively.
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.
~~embeddedJsonataIdentifiers
~~
- Type:
string[]
- Default:
["jsonata"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded JSONata language. This option requires the
@stedi/prettier-plugin-jsonata
plugin.
Please use embeddedJsonataComments
or embeddedJsonataTags
.
Formatting embedded JSONata language requires the @stedi/prettier-plugin-jsonata
plugin to be loaded as well.
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.
~~embeddedLatexIdentifiers
~~
- Type:
string[]
- Default:
["latex", "tex", "aux", "cls", "bbl", "bib", "toc", "sty"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded LaTeX language. This option requires the
prettier-plugin-latex
plugin.
Please use embeddedLatexComments
or embeddedLatexTags
.
Formatting embedded LaTeX language requires the prettier-plugin-latex
plugin to be loaded as well.
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.
~~embeddedMarkdownIdentifiers
~~
- Type:
string[]
- Default:
["md", "markdown"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded Markdown language.
Please use embeddedMarkdownComments
or embeddedMarkdownTags
.
embeddedMarkdownParser
- Type:
"markdown" | "mdx" | "remark"
- Default:
"markdown"
- Description: The parser used to parse the embedded Markdown language.
Formatting embedded Markdown language doesn't require other plugins and uses the parsers and printers provided by Prettier natively.
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.
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.
~~embeddedNginxIdentifiers
~~
- Type:
string[]
- Default:
["nginx"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded NGINX language. This option requires the
prettier-plugin-nginx
plugin.
Please use embeddedNginxComments
or embeddedNginxTags
.
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.
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.
~~embeddedPegjsIdentifiers
~~
- Type:
string[]
- Default:
["pegjs", "peggy", "peg"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded Pegjs language. This option requires the
prettier-plugin-pegjs
plugin.
Please use embeddedPegjsComments
or embeddedPegjsTags
.
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.
~~embeddedPhpIdentifiers
~~
- Type:
string[]
- Default:
["php", "php5"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded PHP language. This option requires the
@prettier/plugin-php
plugin.
Please use embeddedPhpComments
or embeddedPhpTags
.
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.
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.
~~embeddedPrismaIdentifiers
~~
- Type:
string[]
- Default:
["prisma"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded Prisma language. This option requires the
prettier-plugin-prisma
plugin.
Please use embeddedPrismaComments
or embeddedPrismaTags
.
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.
~~embeddedPropertiesIdentifiers
~~
- Type:
string[]
- Default:
["properties"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded Properties language. This option requires the
prettier-plugin-properties
plugin.
Please use embeddedPropertiesComments
or embeddedPropertiesTags
.
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.
~~embeddedPugIdentifiers
~~
- Type:
string[]
- Default:
["pug", "jade"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded Pug language. This option requires the
@prettier/plugin-pug
plugin.
Please use embeddedPugComments
or embeddedPugTags
.
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.
~~embeddedRubyIdentifiers
~~
- Type:
string[]
- Default:
["ruby"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded Ruby language. This option requires the
@prettier/plugin-ruby
plugin.
Please use embeddedRubyComments
or embeddedRubyTags
.
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.
~~embeddedShIdentifiers
~~
- Type:
string[]
- Default:
["sh"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded Shell language. This option requires the
prettier-plugin-sh
plugin.
Please use embeddedShComments
or embeddedShTags
.
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
.
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 theprettier-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 theprettier-plugin-sql-cst
plugin.
~~embeddedSqlIdentifiers
~~
- Type:
string[]
- Default:
["sql"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded SQL language. This option requires the
prettier-plugin-sql
plugin or theprettier-plugin-sql-cst
plugin.
Please use embeddedSqlComments
or embeddedSqlTags
.
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 theprettier-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
.
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.
~~embeddedTomlIdentifiers
~~
- Type:
string[]
- Default:
["toml"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded TOML language. This option requires the
prettier-plugin-toml
plugin.
Please use embeddedTomlComments
or embeddedTomlTags
.
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.
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.
~~embeddedTsIdentifiers
~~
- Type:
string[]
- Default:
["ts", "tsx", "cts", "mts", "typescript"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded TypeScript language.
Please use embeddedTsComments
or embeddedTsTags
.
embeddedTsParser
- Type:
"typescript" | "babel-ts"
- Default:
"typescript"
- Description: The parser used to parse the embedded TypeScript language.
Formatting embedded TypeScript language doesn't require other plugins and uses the parsers and printers provided by Prettier natively.
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.
~~embeddedXmlIdentifiers
~~
- Type:
string[]
- Default:
["xml", "opml", "rss", "svg"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded XML language. This option requires the
@prettier/plugin-xml
plugin.
Please use embeddedXmlComments
or embeddedXmlTags
.
Formatting embedded XML language requires the @prettier/plugin-xml
plugin to be loaded as well. And options supported by @prettier/plugin-xml
can therefore be used to further control the formatting behavior.
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.
~~embeddedYamlIdentifiers
~~
- Type:
string[]
- Default:
["yaml", "yml"]
- Description: Comment or tag identifiers that make their subsequent template literals be identified as embedded YAML language.
Please use embeddedYamlComments
or embeddedYamlTags
.
Formatting embedded YAML language doesn't require other plugins and uses the parsers and printers provided by Prettier natively.
Language-Agnostic Options
Language-Agnostic
~~noEmbeddedIdentificationByComment
~~
- Type:
string[]
- Default:
[]
- Description: Turns off
/* comment */ `...`
comment-based embedded language identification for the specified identifiers.
Please use embedded<Language>Comments
or embedded<Language>Tags
to configure each embedded language, and you won't need this option anymore.
~~noEmbeddedIdentificationByTag
~~
- Type:
string[]
- Default:
[]
- Description: Turns off
tag`...`
tag-based embedded language identification for the specified identifiers.
Please use embedded<Language>Comments
or embedded<Language>Tags
to configure each embedded language, and you won't need this option anymore.
preserveEmbeddedExteriorWhitespaces
- Type:
string[]
- Default:
[]
- Description: Preserves leading and trailing whitespaces in the formatting results for the specified comments or tags.
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.
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.
[!NOTE]
The support for using
.ts
,.mts
or.cts
files forembeddedOverrides
requires a minimalnode
version of 18.19.0, andtsx
as a dependency in your project. And it currently doesn't work with the Prettier VSCode extension.
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 considerred 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.
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]
Please note that not every option is supported to override. That largely depends on at which phase those options will kick in and take effect. For example, you can't override
tabWidth
inembeddedOverrides
because this option is used in theprintDocToString
phase, whereprettier-plugin-embed
cannot override this option for only a set of specified comments or tags. To find the list of unsupported options, please check the interface definition ofEmbeddedOverride
in the source code.
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 fromPrettier
to use plugin-specific optionsRegister options from
prettier-plugin-embed
(this plugin):/// <reference types="prettier-plugin-embed/plugin-embed" />
Register options from
prettier-plugin-sql
:/// <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.
Contributors
License
MIT