prettier-plugin-embed

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?

Although Prettier has introduced the embedded-language-formatting option for formatting embedded languages, it only supports two modes: auto and off. Therefore it doesn't allow for individual formatting adjustments for specific languages, nor does it support customizing the languages that require formatting and identifiers for identification. These limitations restrict the usability of this feature. For more detailed discussions, refer to: https://github.com/prettier/prettier/issues/4424 and https://github.com/prettier/prettier/issues/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 tags identifier`...` or comments /* identifier */ `...` preceding the template literals.

• Customizable Language Identifiers: Customize the identifiers used for identifying the embedded languages.

• Formatting Opt-out Mechanism: Offer the capability to deactivate formatting for certain identifiers, including the default 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 when employing the Prettier API in TypeScript.

• Easy Integration: Integrate with the existing Prettier setup seamlessly, requiring minimal configuration to get started.

Installation

npm i -D prettier-plugin-embed

Peer dependecies are automatically installed by default if you're using npm v7 or higher versions. The peer dependencies of this plugin are mainly packages to support parsing and formatting for different languages. If you only plan to use this plugin for a very specific language and don't want to bloat your node modules folder, you can omit the peer dependencies by changing the installation command to either:

npm i -D --legacy-peer-deps prettier-plugin-embed

or:

npm i -D --omit=peer prettier-plugin-embed

For other package managers, refer to their documents on how to achieve the same result.

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"]
}

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. Instead, ideally, it makes use of existing Prettier plugins for those languages and only adds 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 code, 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 tags identifier`...` or block comments /* identifier */ `...`. This plugin comes pre-configured with a built-in set of identifiers for identifying various embedded languages. For instance, using identifiers like xml or svg will trigger automatic formatting for the embedded XML code. You can specify an alternative list of identifiers using the embeddedXmlIdentifiers option. The naming convention for these options follows the pattern of embedded<Language>Identifiers 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 identifiers from being identified, including the default ones supported by the embedded-language-formatting option, add them to the list of the embeddedNoopIdentifiers option. Any matching identifiers listed in this option will take precedence over other embedded<Language>Identifiers options, effectively disabling their formatting.

Language-Specific Options

Click Here

NOOP

Option	Default	Description
embeddedNoopIdentifiers	[]	Tag or comment identifiers that prevent their subsequent template literals from being identified as embedded languages and from being formatted

This 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 specific language identifiers.

CSS

Option	Default	Description
embeddedCssIdentifiers	[...]	Tag or comment identifiers that make their subsequent template literals be identified as CSS code

Formatting embedded CSS code doesn't require other plugins and uses the parsers and printers provided by Prettier natively. This can override the native embedded language formatting for CSS code.

ES

Option	Default	Description
embeddedEsIdentifiers	[...]	Tag or comment identifiers that make their subsequent template literals be identified as ECMAScript (JavaScript) code
embeddedEsParser	"babel"	The parser used to parse the ECMASCript (JavaScript) code

Formatting embedded ECMAScript code doesn't require other plugins and uses the parsers and printers provided by Prettier natively. This can override the native embedded language formatting for ECMAScript code.

HTML

Option	Default	Description
embeddedHtmlIdentifiers	[...]	Tag or comment identifiers that make their subsequent template literals be identified as HTML code

Formatting embedded HTML code doesn't require other plugins and uses the parsers and printers provided by Prettier natively. This can override the native embedded language formatting for HTML code.

Markdown

Option	Default	Description
embeddedMarkdownIdentifiers	[...]	Tag or comment identifiers that make their subsequent template literals be identified as Markdown code

Formatting embedded Markdown code doesn't require other plugins and uses the parsers and printers provided by Prettier natively. This can override the native embedded language formatting for Markdown code.

PHP

Option	Default	Description
embeddedPhpIdentifiers	[...]	Tag or comment identifiers that make their subsequent template literals be identified as PHP code

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

Ruby

Option	Default	Description
embeddedRubyIdentifiers	[...]	Tag or comment identifiers that make their subsequent template literals be identified as Ruby code

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

SQL

Option	Default	Description
embeddedSqlIdentifiers	[...]	Tag or comment identifiers that make their subsequent template literals be identified as SQL code

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

Note that prettier-plugin-sql supports many different SQL dialects, and there's a one-to-one correspondence between the dialects and the identifiers. To support custom identifiers for a specific dialect, put the identifiers after that specific dialect in the identifier list in option embeddedSqlIdentifiers.

TS

Option	Default	Description
embeddedTsIdentifiers	[...]	Tag or comment identifiers that make their subsequent template literals be identified as TypeScript code
embeddedTsParser	"typescript"	The parser used to parse the TypeScript code

Formatting embedded TypeScript code doesn't require other plugins and uses the parsers and printers provided by Prettier natively. This can override the native embedded language formatting for TypeScript code.

XML

Option	Default	Description
embeddedXmlIdentifiers	[...]	Tag or comment identifiers that make their subsequent template literals be identified as XML code

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

Language-Agnostic Options

Option	Default	Description
noEmbeddedIdentificationByComment	[]	Turns off /* identifier */ `...` comment-based language identification for the specified identifiers
noEmbeddedIdentificationByTag	[]	Turns off identifier`...` tag-based language identification for the specified identifiers
preserveEmbeddedExteriorWhitespaces	[]	Preserves leading and trailing whitespaces in the formatting results for the specified identifiers
noEmbeddedMultiLineIndentation	[]	Turns off auto indentation in the formatting results when they are formatted to span multi lines for the specified identifiers

Demos

TBD.

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.

License

MIT