template-indent.md

template-indent

📝 Fix whitespace-insensitive template indentation.

💼🚫 This rule is enabled in the ✅ recommended config. This rule is disabled in the ☑️ unopinionated config.

🔧 This rule is automatically fixable by the --fix CLI option.

Tagged templates often look ugly/jarring because their indentation doesn't match the code they're found in. In many cases, whitespace is insignificant, or a library like strip-indent is used to remove the margin. See proposal-string-dedent (stage 1 at the time of writing) for a proposal on fixing this in JavaScript.

This rule will automatically fix the indentation of multiline string templates, to keep them in alignment with the code they are found in. A configurable whitelist is used to ensure no whitespace-sensitive strings are edited.

Multiline templates with non-whitespace text or interpolations on the opening line are ignored to avoid changing their value. Start the content on the next line to enable indentation checks.

Examples

// ❌
function foo() {
	const sqlQuery = sql`
select *
from students
where first_name = ${x}
and last_name = ${y}
	`;

	const gqlQuery = gql`
									query user(id: 5) {
										firstName
										lastName
									}
								`;

	const html = /* HTML */ `
				<div>
						<span>hello</span>
				</div>
	`;
}

The above will auto-fix to:

// ✅
function foo() {
	const sqlQuery = sql`
		select *
		from students
		where first_name = ${x}
		and last_name = ${y}
	`;

	const gqlQuery = gql`
		query user(id: 5) {
			firstName
			lastName
		}
	`;

	const html = /* HTML */ `
		<div>
				<span>hello</span>
		</div>
	`;
}

Under the hood, strip-indent is used to determine how the template "should" look. Then a common indent is added to each line based on the margin of the line the template started at. This rule will not alter the relative whitespace between significant lines, it will only shift the content right or left so that it aligns sensibly with the surrounding code.

Options

The rule accepts lists of tags, functions, selectors and comments to match template literals. tags are tagged template literal identifiers or member expression paths, functions are names or member expression paths of utility functions like stripIndent, selectors can be any ESLint selector, and comments are /* block-commented */ strings.

Default configuration:

{
	'unicorn/template-indent': [
		'warn',
		{
			tags: [
				'outdent',
				'dedent',
				'gql',
				'sql',
				'html',
				'styled'
			],
			functions: [
				'dedent',
				'stripIndent'
			],
			selectors: [],
			comments: [
				'HTML',
				'indent'
			]
		}
	]
}

You can use a selector for custom use-cases, like indenting all template literals, even those without template tags or function callers:

{
	'unicorn/template-indent': [
		'warn',
		{
			tags: [],
			functions: [],
			selectors: [
				'TemplateLiteral'
			]
		}
	]
}

Indentation is inferred from the surrounding source code. If there is no surrounding indentation signal, a template literal at the root of the file uses the indentation of its content, and other template literals use tabs or spaces depending on the line of code that the template literal starts at. You can override this by supplying an indent, which should be either a number (of spaces) or a string consisting only of whitespace characters:

{
	'unicorn/template-indent': [
		'warn', {
			indent: 8,
		}
	]
}

{
	'unicorn/template-indent': [
		'warn',
		{
			indent: '\t\t'
		}
	]
}