Using Prettier with Twig in VS Code

I've been formatting code by hand in VSCode for months because the twig auto-formatting was completely broken. Here's how I got it working at last!

Posted 8th July 2020 • #development

UPDATED July 2024

The Prettier for Melody plugin has been forked to work with Prettier 3. This means that auto-formatting and Tailwind class sorting works again!

You can find a working example of these articles in my boilerplate Craft site repository.

This article is about how to get code formatting working for Twig in Visual Studio Code. You'll need these:

If you're managing your project with npm, you can add these lines to package.json, then run npm install from the command line to install them in your project.

The trivago/prettier-plugin-twig-melody repository is abandoned, so this uses the @zackad/prettier-plugin-twig-melody fork, which adds support for Prettier 3 (and therefore is compatible with Tailwind's class sorting plugin.

"devDependencies": {
  "prettier": "^3.2.5",
  "@zackad/prettier-plugin-twig-melody": "^0.6.0",
},

The first thing you'll want to do is define how Prettier should format your code. You'll do this by adding a .prettierrc.json file in the root of your project. The Melody plugin also adds some useful options for Twig files:

{
	"useTabs": true,
	"tabWidth": 3,
	"semi": false,
	"singleQuote": true,
	"twigSingleQuote": true,

	"twigMultiTags": [
		"nav,endnav",
		"switch,case,default,endswitch",
		"ifchildren,endifchildren",
		"cache,endcache",
		"js,endjs"
	],

	"plugins": [
		"@zackad/prettier-plugin-twig-melody",
		"prettier-plugin-tailwindcss"
	]
}

You can also specify ignore rules by creating a .prettierignore file in the root of your project, which uses the gitignore syntax. These only take effect if you're running Prettier from the command line to format your whole project at once.

# COMPOSER
/vendor

# CRAFT STORAGE
/storage/*

# Document root
/web/*

# BUILD FILES
/bower_components/*
/node_modules/*
/build/*
/yarn-error.log

You should also set up VS Code to format files on save, set the default formatter, and add some default configuration.

{
	// Make VS Code format files when you save them automatically
	"editor.formatOnSave": true,

	// ?  FORMATTERS
	"editor.defaultFormatter": "esbenp.prettier-vscode",
	"[twig]": {
		"editor.defaultFormatter": "esbenp.prettier-vscode"
	},

	// Set up some defaults
	"prettier.disableLanguages": ["html"],
	"prettier.tabWidth": 3,
	"prettier.useTabs": true,
	"prettier.singleQuote": true,
}

And that's it! Your twig files will now be automatically formatted when you save them.

If you want to format everything at once, you can also run Prettier on the whole template directory by running npx prettier --write "templates/**/*.twig"

If you run into parser errors, you may find it's because the plugin doesn't support inline{% if %} statements within HTML tags. To get around this, you'll need to use the ternary conditional syntax within html tags. See this GitHub issue for more info.

There are still some things that don't get formatted correctly with this setup. Notably, using things like Craft's JavaScript tag in twig files using {% js %} will format the JavaScript incorrectly and probably break it (especially if there are comments in it). The Melody plugin comes with a useful feature for dealing with this; and lets you wrap any code you don't want to format with two comments:

{# prettier-ignore-start #} and {# prettier-ignore-end #}

Doing that will ignore the section inside those comments, but still format everything else correctly on save.

Want to know more?

I hope you found this useful. If you've got any questions about how this all works or would like to work together, I'd love to hear from you!

Get in touch