prettier-plugin-embed
Advanced tools
A configurable Prettier plugin to format embedded languages in JS/TS files.
A configurable Prettier plugin to format embedded languages in JS/TS Files.
npm i -D prettier-plugin-embed
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.
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.
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.
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 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.
npm i -D prettier-plugin-embed
This is a Prettier plugin, which follows the standard usage pattern of many other Prettier plugins:
Via --plugin:
prettier --write main.ts --plugin=prettier-plugin-embed
Via the plugins options:
await prettier.format(code, {
filepath: "main.ts",
plugins: ["prettier-plugin-embed"],
});
{
"plugins": ["prettier-plugin-embed"]
}
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.
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.
Supported embedded languages are:
embeddedNoopCommentsstring[][]embeddedNoopTagsstring[][]embeddedNoopIdentifiersstring[][]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.
embeddedCssCommentsstring[]["css"]embeddedCssTagsstring[]["css"]embeddedCssIdentifiersstring[]["css"]Please use embeddedCssComments or embeddedCssTags.
embeddedCssParser"css" | "less" | "scss""scss"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.
embeddedEsCommentsstring[]["js", "jsx", "es", "es6", "mjs", "cjs", "pac", "javascript"]embeddedEsTagsstring[]["js", "jsx", "es", "es6", "mjs", "cjs", "pac", "javascript"]embeddedEsIdentifiersstring[]["js", "jsx", "es", "es6", "mjs", "cjs", "pac", "javascript"]Please use embeddedEsComments or embeddedEsTags.
embeddedEsParser"babel" | "babel-flow" | "acorn" | "espree" | "flow" | "meriyah""babel"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.
embeddedGlslCommentsstring[]["glsl", "shader"]prettier-plugin-glsl plugin.embeddedGlslTagsstring[]["glsl", "shader"]prettier-plugin-glsl plugin.embeddedGlslIdentifiersstring[]["glsl", "shader"]prettier-plugin-glsl plugin.Please use embeddedGlslComments or embeddedGlslTags.
Formatting embedded GLSL language requires the prettier-plugin-glsl plugin to be loaded as well.
embeddedGraphqlCommentsstring[]["graphql", "gql"]embeddedGraphqlTagsstring[]["graphql", "gql"]embeddedGraphqlIdentifiersstring[]["graphql", "gql"]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.
embeddedHtmlCommentsstring[]["html", "xhtml"]embeddedHtmlTagsstring[]["html", "xhtml"]embeddedHtmlIdentifiersstring[]["html", "xhtml"]Please use embeddedHtmlComments or embeddedHtmlTags.
embeddedHtmlParser"html" | "vue" | "angular" | "lwc""html"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.
embeddedIniCommentsstring[]["ini", "cfg", "pro"]prettier-plugin-ini plugin.embeddedIniTagsstring[]["ini", "cfg", "pro"]prettier-plugin-ini plugin.embeddedIniIdentifiersstring[]["ini", "cfg", "pro"]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.
embeddedJavaCommentsstring[]["java"]prettier-plugin-java plugin.embeddedJavaTagsstring[]["java"]prettier-plugin-java plugin.embeddedJavaIdentifiersstring[]["java"]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.
embeddedJsonCommentsstring[]["json", "jsonl"]embeddedJsonTagsstring[]["json", "jsonl"]embeddedJsonIdentifiersstring[]["json", "jsonl"]Please use embeddedJsonComments or embeddedJsonTags.
embeddedJsonParser"json" | "json5" | "jsonc" | "json-stringify""json"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.
embeddedJsonataCommentsstring[]["jsonata"]@stedi/prettier-plugin-jsonata plugin.embeddedJsonataTagsstring[]["jsonata"]@stedi/prettier-plugin-jsonata plugin.embeddedJsonataIdentifiersstring[]["jsonata"]@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.
embeddedLatexCommentsstring[]["latex", "tex", "aux", "cls", "bbl", "bib", "toc", "sty"]prettier-plugin-latex plugin.embeddedLatexTagsstring[]["latex", "tex", "aux", "cls", "bbl", "bib", "toc", "sty"]prettier-plugin-latex plugin.embeddedLatexIdentifiersstring[]["latex", "tex", "aux", "cls", "bbl", "bib", "toc", "sty"]prettier-plugin-latex plugin.Please use embeddedLatexComments or embeddedLatexTags.
Formatting embedded LaTeX language requires the prettier-plugin-latex plugin to be loaded as well.
embeddedMarkdownCommentsstring[]["md", "markdown"]embeddedMarkdownTagsstring[]["md", "markdown"]embeddedMarkdownIdentifiersstring[]["md", "markdown"]Please use embeddedMarkdownComments or embeddedMarkdownTags.
embeddedMarkdownParser"markdown" | "mdx" | "remark""markdown"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.
embeddedNginxCommentsstring[]["nginx"]prettier-plugin-nginx plugin.embeddedNginxTagsstring[]["nginx"]prettier-plugin-nginx plugin.embeddedNginxIdentifiersstring[]["nginx"]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.
embeddedPegjsCommentsstring[]["pegjs", "peggy", "peg"]prettier-plugin-pegjs plugin.embeddedPegjsTagsstring[]["pegjs", "peggy", "peg"]prettier-plugin-pegjs plugin.embeddedPegjsIdentifiersstring[]["pegjs", "peggy", "peg"]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.
embeddedPhpCommentsstring[]["php", "php5"]@prettier/plugin-php plugin.embeddedPhpTagsstring[]["php", "php5"]@prettier/plugin-php plugin.embeddedPhpIdentifiersstring[]["php", "php5"]@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.
embeddedPrismaCommentsstring[]["prisma"]prettier-plugin-prisma plugin.embeddedPrismaTagsstring[]["prisma"]prettier-plugin-prisma plugin.embeddedPrismaIdentifiersstring[]["prisma"]prettier-plugin-prisma plugin.Please use embeddedPrismaComments or embeddedPrismaTags.
Formatting embedded Prisma language requires the prettier-plugin-prisma plugin to be loaded as well.
embeddedPropertiesCommentsstring[]["properties"]prettier-plugin-properties plugin.embeddedPropertiesTagsstring[]["properties"]prettier-plugin-properties plugin.embeddedPropertiesIdentifiersstring[]["properties"]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.
embeddedPugCommentsstring[]["pug", "jade"]@prettier/plugin-pug plugin.embeddedPugTagsstring[]["pug", "jade"]@prettier/plugin-pug plugin.embeddedPugIdentifiersstring[]["pug", "jade"]@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.
embeddedRubyCommentsstring[]["ruby"]@prettier/plugin-ruby plugin.embeddedRubyTagsstring[]["ruby"]@prettier/plugin-ruby plugin.embeddedRubyIdentifiersstring[]["ruby"]@prettier/plugin-ruby plugin.Please use embeddedRubyComments or embeddedRubyTags.
embeddedRubyParser"ruby" | "rbs" | "haml""ruby"@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.
embeddedShCommentsstring[]["sh"]prettier-plugin-sh plugin.embeddedShTagsstring[]["sh"]prettier-plugin-sh plugin.embeddedShIdentifiersstring[]["sh"]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.
embeddedSqlCommentsstring[]["sql"]prettier-plugin-sql plugin or the prettier-plugin-sql-cst plugin.embeddedSqlTagsstring[]["sql"]prettier-plugin-sql plugin or the prettier-plugin-sql-cst plugin.embeddedSqlIdentifiersstring[]["sql"]prettier-plugin-sql plugin or the prettier-plugin-sql-cst plugin.Please use embeddedSqlComments or embeddedSqlTags.
embeddedSqlPlugin"prettier-plugin-sql" | "prettier-plugin-sql-cst""prettier-plugin-sql"prettier-plugin-sql plugin or the prettier-plugin-sql-cst plugin.embeddedSqlParser"sqlite" | "bigquery" | "mysql" | "mariadb" | "postgresql" "sqlite"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.
embeddedTomlCommentsstring[]["toml"]prettier-plugin-toml plugin.embeddedTomlTagsstring[]["toml"]prettier-plugin-toml plugin.embeddedTomlIdentifiersstring[]["toml"]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.
embeddedTsCommentsstring[]["ts", "tsx", "cts", "mts", "typescript"]embeddedTsTagsstring[]["ts", "tsx", "cts", "mts", "typescript"]embeddedTsIdentifiersstring[]["ts", "tsx", "cts", "mts", "typescript"]Please use embeddedTsComments or embeddedTsTags.
embeddedTsParser"typescript" | "babel-ts""typescript"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.
embeddedXmlCommentsstring[]["xml", "opml", "rss", "svg"]@prettier/plugin-xml plugin.embeddedXmlTagsstring[]["xml", "opml", "rss", "svg"]@prettier/plugin-xml plugin.embeddedXmlIdentifiersstring[]["xml", "opml", "rss", "svg"]@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.
embeddedYamlCommentsstring[]["yaml", "yml"]embeddedYamlTagsstring[]["yaml", "yml"]embeddedYamlIdentifiersstring[]["yaml", "yml"]Please use embeddedYamlComments or embeddedYamlTags.
Formatting embedded YAML language doesn't require other plugins and uses the parsers and printers provided by Prettier natively.
noEmbeddedIdentificationByCommentstring[][]/* 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.
noEmbeddedIdentificationByTagstring[][]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.
preserveEmbeddedExteriorWhitespacesstring[][]noEmbeddedMultiLineIndentationstring[][]embeddedOverridesstringundefinedembeddedOverridesThis 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,.mtsor.ctsfiles forembeddedOverridesrequires a minimalnodeversion of 18.19.0, andtsxas 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
tabWidthinembeddedOverridesbecause this option is used in theprintDocToStringphase, whereprettier-plugin-embedcannot override this option for only a set of specified comments or tags. To find the list of unsupported options, please check the interface definition ofEmbeddedOverridein the source code.
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
Register 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",
};
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.
 Karl Horky 💻 📖 |
MIT
0.4.13
FAQs
A configurable Prettier plugin to format embedded languages in JS/TS files.
The npm package prettier-plugin-embed receives a total of 23,388 weekly downloads. As such, prettier-plugin-embed popularity was classified as popular.
We found that prettier-plugin-embed demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.