The Shopify Liquid Prettier Plugin is an opinionated code formatter for enforcing a consistent style in Liquid and HTML code.

## Installation

You can install the Shopify Liquid Prettier Plugin using either npm or Yarn.

```bash?title:'npm'
npm install --save-dev prettier @shopify/prettier-plugin-liquid
```

```bash?title:'Yarn'
yarn add --dev prettier @shopify/prettier-plugin-liquid
```


For Prettier version 3 and above, the plugin must also be declared in the [configuration](https://prettier.io/docs/en/configuration.html).

```
{
  "plugins": ["@shopify/prettier-plugin-liquid"]
}
```


## Configuration

The Shopify Liquid Prettier Plugin supports the following configuration options:

| Name | Default value | Description |
| --- | --- | --- |
| `printWidth` | `120` | The number of characters allowed on a line before wrapping.<br><br>To learn more about the `printWidth` option, refer to the [Prettier documentation](https://prettier.io/docs/en/options.html#print-width). |
| `tabWidth` | `2` | The number of spaces included in each indentation level.<br><br>To learn more about the `tabWidth` option, refer to the [Prettier documentation](https://prettier.io/docs/en/options.html#tab-width). |
| `useTabs` | `false` | Whether to indent lines with tabs or spaces.<br><br>To learn more about the `useTabs` option, refer to the [Prettier documentation](https://prettier.io/docs/en/options.html#tabs). |
| `singleQuote` | `false` | Whether to use single or double quotes.<br><br>To learn more about the `singleQuote` option, refer to the [Prettier documentation](https://prettier.io/docs/en/options.html#quotes). |
| `liquidSingleQuote` | `true` | Whether to use single quotes instead of double quotes in Liquid tags and objects. |
| `embeddedSingleQuote` | `true` | Whether to use single quotes instead of double quotes in embedded languages (JavaScript, CSS, TypeScript inside `<script>`, `<style>` or Liquid equivalent). |
| `htmlWhitespaceSensitivity` | `css` | The HTML whitespace sensitivity.<br><br>To learn more about the `htmlWhitespaceSensitivity` option, refer to the [Prettier documentation](https://prettier.io/docs/en/options.html#html-whitespace-sensitivity). |
| `singleLineLinkTags` | `false` | Whether to print `<link>` tags on a single line. |
| `indentSchema` | `false` | Whether to indent the contents of `{% schema %}` tags. |

## Usage

You can use the Shopify Liquid Prettier Plugin in the following environments:

- [Terminal](#use-the-plugin-in-the-terminal)
- [Browser](#use-the-plugin-in-the-browser)
- [Editor](#use-the-plugin-in-an-editor)


You can also use the plugin as a [pre-commit hook](#use-the-plugin-as-a-pre-commit-hook) or [with a bundler](#use-the-plugin-with-a-bundler).

## Use the plugin in the terminal

You can use Prettier in the terminal as either a [local](#local-dependency) or [global](#global-dependency) dependency.

### Local dependency

To use Prettier as a local dependency, you can add it as a script in your `package.json` file:

```json
...
{
  "scripts": {
    "prettier": "prettier"
  }
}
...
```


Then you can run it using either npm or Yarn:

```bash?title:'npm'
npm run prettier -- path/to/file.liquid --write
```

```bash?title:'Yarn'
yarn run prettier path/to/file.liquid --write
```


### Global dependency

If you install Prettier as a global dependency, then you can run it with the following command:

```bash
prettier path/to/file.liquid --write
```


## Use the plugin in the browser

The Shopify Liquid Prettier Plugin exposes a `standalone.js` file that can be used alongside Prettier's own `standalone.js` file.

To use Prettier and the Shopify Liquid Prettier Plugin in the browser, include both `standalone` files using an npm CDN, such as [UNPKG](https://unpkg.com/).

```html
<script src="https://unpkg.com/prettier/standalone.js"></script>
<script src="https://unpkg.com/@shopify/prettier-plugin-liquid/standalone.js"></script>
```

With the `standalone` scripts included, you can format code like the following:

```js
prettier.format(YOUR_CODE, {
  plugins: [prettierPluginLiquid],
  parser: 'liquid-html',
});
```

## Use the plugin in an editor

You can use the Shopify Liquid Prettier Plugin in the following editors:

- [Visual Studio Code](#visual-studio-code)
- [Vim](#vim)
- [WebStorm](#webstorm)

### Visual Studio Code

You can use the Shopify Liquid Prettier Plugin in Visual Studio Code through one of the following extensions:

- [Shopify Liquid](#the-shopify-liquid-extension)
- [Prettier](#the-prettier-extension)

#### The Shopify Liquid extension

The [Shopify Liquid](https://marketplace.visualstudio.com/items?itemName=Shopify.theme-check-vscode) extension includes the Shopify Liquid Prettier Plugin by default.

If you'd like to activate format-on-save, then you can add the following setting:

```json
{
  "[liquid]": {
    "editor.defaultFormatter": "Shopify.theme-check-vscode",
    "editor.formatOnSave": true
  },
}
```


To learn about how to format files with Prettier in Visual Studio Code, refer to the [documentation for the Prettier extension](https://github.com/prettier/prettier-vscode#usage).

#### The Prettier extension

Using the Shopify Liquid Prettier Plugin with the Prettier extension requires the following steps:

1. Install the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode).
2. [Install the Shopify Liquid Prettier Plugin](#installation) locally in your repository.

To learn about how to format files with Prettier in Visual Studio Code, refer to the [documentation for the Prettier extension](https://github.com/prettier/prettier-vscode#usage).

### Vim

Using the Shopify Liquid Prettier Plugin in Vim requires the following steps:

1. Install [vim-plug](https://github.com/junegunn/vim-plug).
2. Install [vim-prettier](https://github.com/prettier/vim-prettier).
3. [Install the Shopify Liquid Prettier Plugin](#installation) locally in your repository.

To learn about how to format files with Prettier in Vim, refer to the [documentation for vim-prettier](https://github.com/prettier/vim-prettier#usage).

### WebStorm

Using the Shopify Liquid Prettier Plugin in WebStorm requires the following steps:

1. Install the [Prettier plugin](https://plugins.jetbrains.com/plugin/10456-prettier).
2. [Install the Shopify Liquid Prettier Plugin](#installation) locally in your repository.
3. Restart WebStorm.
4. Search for **Prettier** in the WebStorm preferences and update **Run for files** to include `liquid`.
    - You can also tick the **On save** checkbox to format-on-save.
5. Click **Ok** to save your settings.

To learn about how to format files with Prettier in WebStorm, refer to [the WebStorm documentation](https://www.jetbrains.com/help/webstorm/prettier.html#ws_prettier_reformat_code).



## Use the plugin as a pre-commit hook

You can use Prettier with a pre-commit tool. Pre-commit tools can reformat your "staged" files before you commit them.

> Tip:
> To learn about pre-commit tools that are compatible with Prettier and how to install them, refer to [Prettier's documentation](https://prettier.io/docs/en/precommit.html).


## Use the plugin with a bundler

The Shopify Liquid Prettier Plugin exposes a `standalone.js` file that can be used alongside Prettier's own `standalone.js` file.

To use Prettier and the Shopify Liquid Prettier Plugin with bundlers, such as webpack, Rollup, or Browserify, import both `standalone` files.

```js
import prettier from 'prettier/standalone';
import liquidPlugin from '@shopify/prettier-plugin-liquid/standalone';
```

With the `standalone` files imported, you can format code like the following:

```js
prettier.format(YOUR_CODE, {
  plugins: [liquidPlugin],
  parser: 'liquid-html',
});
```

## Contributing to the Shopify Liquid Prettier Plugin

The Shopify Liquid Prettier Plugin is open source.

- Learn how to contribute to the [prettier-plugin-liquid repository](https://github.com/Shopify/theme-tools/blob/main/packages/prettier-plugin-liquid/CONTRIBUTING.md)
- [Report an issue](https://github.com/Shopify/prettier-plugin-liquid/issues/new/choose)