@hero-design/eslint-plugin

Overview

Hero Design's ESLint plugin that ensures correct usage and deprecation of Hero Design packages. The plugin is used across many repositories to enforce best practices, prevent deprecated API usage, and maintain consistency across projects using @hero-design/rn, @hero-design/react, and @hero-design/colors.

Key features:

• Enforces proper component prop usage and prevents deprecated APIs
• Prevents direct color palette access in favor of semantic tokens
• Ensures text content is properly wrapped in Typography components
• Blocks not recommended imports with helpful migration messages
• Provides pre-configured rule sets for React Native and React web projects

We strongly recommend all consumers to use this plugin with our predefined recommendedRn or recommendedReact configs.

Installation

Prerequisites:

• Node.js >= 14.17.0 (or >= 20.0.0 recommended)
• ESLint >= 7.0.0

Install ESLint (if not already installed):

yarn add -D eslint

Install @hero-design/eslint-plugin:

yarn add -D @hero-design/eslint-plugin

Usage

Add @hero-design to the plugins section of your ESLint configuration (.eslintrc). You can omit the eslint-plugin postfix:

{
  "plugins": ["@hero-design"]
}

Recommended Configurations

For React Native Projects

Use the recommendedRn config, which includes rules for deprecated props, theme keys, and not recommended imports:

{
  "extends": ["plugin:@hero-design/recommendedRn"]
}

For React Web Projects

Use the recommendedReact config, which includes rules for color palette access and typography:

{
  "extends": ["plugin:@hero-design/recommendedReact"]
}

For Internal Teams (Next Version Migration)

Use the internalRn config to prepare for upcoming breaking changes:

{
  "extends": ["plugin:@hero-design/internalRn"]
}

Manual Rule Configuration

You can also configure individual rules manually, though this approach should be avoided unless you have specific needs:

{
  "rules": {
    "@hero-design/no-deprecated-component-prop": "error",
    "@hero-design/no-direct-color-palette-access": "warn"
  }
}

Examples

Basic Setup

// .eslintrc.json
{
  "extends": [
    "eslint:recommended",
    "plugin:@hero-design/recommendedRn"
  ],
  "plugins": ["@hero-design"]
}

React Native Component Usage

The plugin will catch deprecated props and suggest alternatives:

// ❌ Incorrect - will be flagged
import { Card } from '@hero-design/rn';
<Card variant="outlined" />

// ✅ Correct
<Card appearance="outlined" />

Color Usage

// ❌ Incorrect - direct palette access
const color = theme.colors.palette.redLight30;

// ✅ Correct - semantic color tokens
const color = theme.colors.text.primary;

Typography Usage (React Web)

// ❌ Incorrect - raw HTML text elements
<div>
  <p>Some text</p>
</div>

// ✅ Correct - Typography component
<div>
  <Typography tagName="p">Some text</Typography>
</div>

Supported Rules

| Rule | Description | Config | |------|-------------|--------| | @hero-design/banning-snowflake-approve-comment | Disallow Snowflake Guard approval comments | - | | @hero-design/no-deprecated-component-prop | Disallow deprecated component props | - | | @hero-design/no-deprecated-component-prop-next | Disallow props deprecated in next version | internalRn | | @hero-design/no-deprecated-component-prop-value | Disallow deprecated component prop values | - | | @hero-design/no-deprecated-theme-key | Disallow deprecated theme keys | - | | @hero-design/no-direct-color-palette-access | Disallow direct color palette access | recommendedReact | | @hero-design/not-recommended-import | Disallow not recommended imports | recommendedRn | | @hero-design/react-no-text-outside-typography | Require text inside Typography component | recommendedReact |

For detailed documentation on each rule, see the docs/rules directory.

Contributing

To contribute to this plugin:

1. Add a new rule: Create a new rule file in lib/rules/ following the existing pattern
2. Add tests: Create corresponding test files in tests/lib/rules/
3. Add documentation: Create a markdown file in docs/rules/ explaining the rule
4. Update configs: Add the rule to appropriate configs in lib/index.js
5. Run tests: Execute yarn test to ensure all tests pass
6. Run linter: Execute yarn lint to check code quality

See the existing rules for examples of the expected structure and patterns.