Add rule to enforce importing components with sx prop from @primer/styled-react

[jonrohan]

Closes https://github.com/github/primer/issues/5613

use-styled-react-import

💼 This rule is disabled in the ✅ recommended config.

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

Enforce importing components that use sx prop from @primer/styled-react instead of @primer/react, and vice versa.

Rule Details

This rule detects when certain Primer React components are used with the sx prop and ensures they are imported from the temporary @primer/styled-react package instead of @primer/react. When the same components are used without the sx prop, it ensures they are imported from @primer/react instead of @primer/styled-react.

When a component is used both with and without the sx prop in the same file, the rule will import the styled version with an alias (e.g., StyledButton) and update the JSX usage accordingly to avoid naming conflicts.

It also moves certain types and utilities to the styled-react package.

Components that should be imported from @primer/styled-react when used with sx:

• ActionList
• ActionMenu
• Box
• Breadcrumbs
• Button
• Flash
• FormControl
• Heading
• IconButton
• Label
• Link
• LinkButton
• PageLayout
• Text
• TextInput
• Truncate
• Octicon
• Dialog

Types and utilities that should always be imported from @primer/styled-react:

• BoxProps (type)
• SxProp (type)
• BetterSystemStyleObject (type)
• sx (utility)

Examples

❌ Incorrect

import {Button, Link} from '@primer/react'

const Component = () => <Button sx={{color: 'red'}}>Click me</Button>

import {Box} from '@primer/react'

const Component = () => <Box sx={{padding: 2}}>Content</Box>

import {sx} from '@primer/react'

import {Button} from '@primer/styled-react'

const Component = () => <Button>Click me</Button>

import {Button} from '@primer/react'

const Component1 = () => <Button>Click me</Button>
const Component2 = () => <Button sx={{color: 'red'}}>Styled me</Button>

✅ Correct

import {Link} from '@primer/react'
import {Button} from '@primer/styled-react'

const Component = () => <Button sx={{color: 'red'}}>Click me</Button>

import {Box} from '@primer/styled-react'

const Component = () => <Box sx={{padding: 2}}>Content</Box>

import {sx} from '@primer/styled-react'

// Components without sx prop can stay in @primer/react
import {Button} from '@primer/react'

const Component = () => <Button>Click me</Button>

// Components imported from styled-react but used without sx prop should be moved back
import {Button} from '@primer/react'

const Component = () => <Button>Click me</Button>

// When a component is used both ways, use an alias for the styled version
import {Button} from '@primer/react'
import {Button as StyledButton} from '@primer/styled-react'

const Component1 = () => <Button>Click me</Button>
const Component2 = () => <StyledButton sx={{color: 'red'}}>Styled me</StyledButton>

Options

This rule has no options.

When Not To Use It

This rule is specifically for migrating components that use the sx prop to the temporary @primer/styled-react package. If you're not using the sx prop or not participating in this migration, you can disable this rule.

[changeset-bot]

🦋 Changeset detected

Latest commit: 2dcde64

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
eslint-plugin-primer-react	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jonrohan]

I did a test migration on github here https://github.com/github/github/pull/395613

[Copilot]

Pull Request Overview

This PR adds a new ESLint rule use-styled-react-import that enforces correct import locations for Primer React components based on whether they use the sx prop. The rule ensures components using sx are imported from @primer/styled-react while components without sx remain in @primer/react.

• Implements automatic fixing for import statements and JSX element names
• Handles complex scenarios like alias imports when components are used both with and without sx props
• Provides comprehensive test coverage for various import patterns and edge cases

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/rules/use-styled-react-import.js	Core rule implementation with logic for tracking component usage and automatically fixing imports
src/rules/__tests__/use-styled-react-import.test.js	Comprehensive test suite covering valid/invalid cases and auto-fix behavior
src/index.js	Exports the new rule making it available to consumers
docs/rules/use-styled-react-import.md	Documentation explaining rule purpose, examples, and usage guidelines
.changeset/smart-rocks-fail.md	Changeset file for release management

[Copilot]

The type prefix is added for TypeScript type imports, but the rule doesn't check if the file is TypeScript or if the import was originally a type import. This could break JavaScript files or incorrectly convert regular imports to type imports.

Suggested change

	const prefix = styledTypes.has(importName) ? 'type ' : ''
	const isTypeScript = isTypeScriptFile(context.getFilename());
	const isTypeImport = specifier.importKind === 'type';
	const prefix = (isTypeScript && isTypeImport) ? 'type ' : '';

[Copilot]

Same issue as above - the type prefix is unconditionally added for type imports without checking the original import syntax or file type.

Suggested change

	const prefix = styledTypes.has(importName) ? 'type ' : ''
	const isTypeImport = specifier.importKind === 'type'
	const isTSFile = context.getFilename().endsWith('.ts') || context.getFilename().endsWith('.tsx')
	const prefix = isTypeImport && isTSFile ? 'type ' : ''

[Copilot]

This logic for determining the 'first component' is complex and fragile. The condition checks different arrays and could lead to multiple fixes being applied for the same import node. Consider using a more explicit flag or state tracking mechanism.

Suggested change

	}
	// Only apply the fix once per import node using an explicit flag
	if (changes.fixed) {
	return null
	}
	changes.fixed = true;

[Copilot]

This simpler version of the 'first component' check is inconsistent with the more complex version above (lines 185-188). The inconsistency makes the code harder to understand and maintain.

Suggested change

	const isFirstComponent = changes.toMove[0] === componentName
	const isFirstComponent = changes.toMove.find(name => name === componentName) === changes.toMove[0]