Prettier Plugin Embed

0.5.1 verified Sat Apr 25 auth: no javascript

A configurable Prettier plugin for formatting embedded languages (SQL, XML, PHP, markdown, CSS, etc.) in JavaScript/TypeScript template literals. Version 0.5.1, active development with frequent releases. Unlike Prettier's built-in 'auto' mode, it allows per-language control, custom block comments/tags for language detection, and opt-out per tag. Ships TypeScript types. Supports additional languages beyond Prettier defaults, with options for indentation and formatting behavior.

Common errors

error Error: Plugin parse error: Cannot find module 'prettier-plugin-sql' ↓

cause Missing underlying Prettier parser for an embedded language (e.g., SQL).

fix

Install the required parser, e.g., npm i -D prettier-plugin-sql

error [WARNING] Ignored unknown option: embeddedLanguageFormatting ↓

cause Using a Prettier version that doesn't support the option, or option is misspelled.

fix

Ensure Prettier version >= 2.3.0. Use 'embeddedLanguageFormatting' (not 'embeddedLanguageFormat').

error TypeError: prettierPluginEmbed is not a function ↓

cause Importing the plugin as a function instead of an object.

fix

Use 'import prettierPluginEmbed from 'prettier-plugin-embed'' and add to 'plugins' array as a member.

Warnings

breaking In v0.4.14, throwIfPluginIsNotFound option was removed; language plugin checks now silently skip missing plugins. ↓

fix Remove any usage of throwIfPluginIsNotFound from your Prettier config.

gotcha If using Prettier's built-in embedded language formatting ('auto'), this plugin may interfere. Disable built-in with 'embeddedLanguageFormatting: off'. ↓

fix Set embeddedLanguageFormatting: 'off' in Prettier config to avoid conflicts.

gotcha The plugin only formats template literals that are tagged with a recognized tag or preceded by a block comment. Untagged template literals are not formatted. ↓

fix Ensure your template literals have a tag (e.g., sql`...`) or a block comment (/* sql */ `...`).

deprecated In v0.4.14, the 'throwIfPluginIsNotFound' option was removed; using it will cause an error. ↓

fix Remove the option from your Prettier config.

breaking In v0.5.0, support for CallExpression as shorthand tag was added; existing configs for non-shorthand tags might need adjustment. ↓

fix Review tag configuration; if using tags in options, they are now matched by identifier name as well as call expressions.

Install

npm install prettier-plugin-embed

yarn add prettier-plugin-embed

pnpm add prettier-plugin-embed

Imports

prettier-plugin-embed

wrong

const prettierPluginEmbed = require('prettier-plugin-embed')

correct

import prettierPluginEmbed from 'prettier-plugin-embed'

Default import is the plugin itself. Use with Prettier's 'plugins' array.

EmbedOptions

wrong

import { EmbedOptions } from 'prettier-plugin-embed'

correct

import type { EmbedOptions } from 'prettier-plugin-embed'

EmbedOptions is a TypeScript type; use 'import type' in TS projects.

options
wrong
```
plugins: ['prettier-plugin-embed']
```
correct
```
plugins: [prettierPluginEmbed]
```
Use the imported module, not a string, when using Prettier API programmatically.

Quickstart

Shows basic setup: install plugin, add to Prettier config, enable formatting for SQL template literals tagged with 'sql'.

// .prettierrc.js
module.exports = {
  plugins: [require('prettier-plugin-embed')],
  // Optional: configure embedded languages
  embeddedLanguageFormatting: 'off', // disable built-in to avoid conflicts
  embed: {
    // Enable SQL formatting in template literals tagged with sql
    tags: ['sql'],
    // Or use comments: /** sql */ `SELECT * FROM users`
    comments: ['sql'],
  },
};

// Example file: example.js
const sql = 'SELECT * FROM users WHERE id = 1';
// After formatting, SQL in template literals tagged with sql is formatted
const query = sql`SELECT * FROM users WHERE id = 1`;