Syntax Preference Rule

The syntax-preference rule enforces consistent CSS syntax choice between string-based (template literals) and object-based styles throughout your codebase.

Capabilities

CSS Syntax Enforcement

Enforces consistent usage of either string-based or object-based CSS syntax in emotion.

/**
 * Rule for enforcing consistent CSS syntax preference
 * Supports 'string' or 'object' preference configuration
 */
interface SyntaxPreferenceRuleConfig {
  name: "syntax-preference";
  fixable: false; // Reports violations, no auto-fix
  schema: [('string' | 'object')?];
  messages: {
    preferStringStyle: string;
    preferObjectStyle: string;
    preferWrappingWithCSS: string;
    emptyCssProp: string;
  };
}

type RuleOptions = [('string' | 'object')?];

Rule Behavior

Based on configuration preference:

Object Preference ("object"):

• Reports string-based styles (template literals, css strings)
• Encourages object syntax: { color: 'red' }
• Validates JSX css props and styled component usage
• Handles nested expressions and arrays

String Preference ("string"):

• Reports object-based styles
• Encourages template literal syntax: css\color: red;``
• Validates consistent string-based approach
• Suggests css tagged templates over plain strings

Usage Examples

Configuration for Object Preference

{
  "rules": {
    "@emotion/syntax-preference": ["error", "object"]
  }
}

Configuration for String Preference

{
  "rules": {
    "@emotion/syntax-preference": ["error", "string"] 
  }
}

Code Examples

Object Preference

Incorrect (when configured for objects):

import styled from '@emotion/styled';

const Button = styled.button`
  color: hotpink;
  background: white;
`;

// Also incorrect
const styles = css`
  padding: 10px;
  margin: 5px;
`;

Correct (when configured for objects):

import styled from '@emotion/styled';

const Button = styled.button({
  color: 'hotpink',
  background: 'white'
});

// Also correct
const styles = css({
  padding: '10px',
  margin: '5px'
});

String Preference

Incorrect (when configured for strings):

const Button = styled.button({
  color: 'hotpink',
  background: 'white'
});

Correct (when configured for strings):

const Button = styled.button`
  color: hotpink;
  background: white;
`;

JSX CSS Prop Validation

The rule also validates JSX css prop usage:

Object preference examples:

// Incorrect
<div css="color: red;" />
<div css={`color: red;`} />

// Correct  
<div css={{ color: 'red' }} />
<div css={css({ color: 'red' })} />

String preference examples:

// Incorrect
<div css={{ color: 'red' }} />

// Correct
<div css={css`color: red;`} />

Error Messages

• preferStringStyle: "Styles should be written using strings."
• preferObjectStyle: "Styles should be written using objects."
• preferWrappingWithCSS: "Prefer wrapping your string styles with `css` call."
• emptyCssProp: "Empty `css` prop is not valid."

Advanced Usage

Nested Structure Handling

The rule handles complex nested structures:

// Array of styles (object preference)
const multipleStyles = [
  { color: 'red' },    // Correct
  `color: blue;`,      // Incorrect - reports violation
  { padding: '10px' }  // Correct
];

Template Literal vs CSS Tagged Templates

With string preference, the rule distinguishes:

Plain strings (discouraged):

<div css="color: red;" />          // Reports: prefer wrapping with css

CSS tagged templates (preferred):

<div css={css`color: red;`} />     // Correct

When Not To Use

Disable this rule if:

• Your team doesn't have a consistent preference
• You're migrating between syntaxes and need both temporarily
• Different parts of your codebase require different approaches
• You're using third-party libraries that dictate syntax choice

Best Practices

1. Choose consistently: Pick one syntax and stick with it project-wide
2. Team agreement: Ensure all team members agree on the chosen syntax
3. Migration strategy: If changing syntax, update all files systematically
4. Performance considerations: Both syntaxes have similar performance characteristics