@edarioq/eslint-plugin-prop-ordering

# eslint-plugin-react-props-sort A comprehensive ESLint plugin that enforces consistent ordering of React component props and TypeScript interface/type properties. This plugin helps maintain clean, readable, and predictable code structure across your React and TypeScript projects. ## Features - **Destructured Props Sorting**: Automatically sorts destructured props in React component parameters - **TypeScript Interface Sorting**: Sorts properties in TypeScript interfaces and type literals - **Intelligent Callback Detection**: Recognizes callbacks by common patterns (`onClick`, `onSubmit`, `setData`, `handleClick`, etc.) - **Reserved Props Prioritization**: Ensures important props like `id`, `key`, `ref` appear first - **Flexible Configuration**: Customize sorting behavior to match your team's preferences - **Auto-fix Support**: Automatically reorder properties with ESLint's `--fix` option ## Installation ```bash npm install --save-dev eslint-plugin-react-props-sort ``` ## Usage Add the plugin to your ESLint configuration: ```json { "plugins": ["react-props-sort"], "rules": { "react-props-sort/sort-destructured-props": "warn", "react-props-sort/sort-interface-props": "warn" } } ``` ## Rules ### `sort-destructured-props` Sorts destructured props in React component function parameters to match a consistent order. **Before:** ```jsx function UserProfile({ onClick, id, name, email, isActive, onSubmit }) { return <div>...</div>; } ``` **After:** ```jsx function UserProfile({ id, email, isActive, name, onClick, onSubmit }) { return <div>...</div>; } ``` ### `sort-interface-props` Sorts properties in TypeScript interfaces and type literals according to the same ordering logic. **Before:** ```typescript interface UserProps { onClick: () => void; id: string; name: string; email?: string; isActive: boolean; onSubmit: (data: any) => void; } ``` **After:** ```typescript interface UserProps { id: string; email?: string; isActive: boolean; name: string; onClick: () => void; onSubmit: (data: any) => void; } ``` ## Configuration Options Both rules accept the same configuration options: ```json { "react-props-sort/sort-destructured-props": [ "warn", { "callbacksLast": true, "shorthandFirst": false, "noSortAlphabetically": false, "reservedFirst": true, "reservedPropsNames": ["id", "key", "ref", "name", "type"] } ] } ``` ### Options | Option | Type | Default | Description | | ---------------------- | -------- | -------------------------------------- | ------------------------------------------------ | | `callbacksLast` | boolean | `true` | Move callback functions to the end | | `shorthandFirst` | boolean | `false` | Move optional properties first (TypeScript only) | | `noSortAlphabetically` | boolean | `false` | Disable alphabetical sorting | | `reservedFirst` | boolean | `true` | Move reserved props to the beginning | | `reservedPropsNames` | string[] | `["id", "key", "ref", "name", "type"]` | List of props considered "reserved" | ## Sorting Logic The plugin applies the following sorting order: 1. **Reserved props first** (if `reservedFirst: true`) - Props like `id`, `key`, `ref`, `name`, `type` 2. **Optional properties first** (if `shorthandFirst: true`, TypeScript only) - Properties marked with `?` 3. **Regular properties** (alphabetically sorted if `noSortAlphabetically: false`) - All other properties in alphabetical order 4. **Callbacks last** (if `callbacksLast: true`) - Properties starting with `on` + capital letter (`onClick`, `onSubmit`) - Properties starting with `set` + capital letter (`setData`, `setUser`) - Properties ending with `Callback` or `Handler` - Properties starting with `handle` 5. **Rest elements always last** - Spread operators (`...rest`) remain at the end ## Smart Component Detection The `sort-destructured-props` rule intelligently detects React components by: - **PascalCase naming**: Functions with names starting with uppercase letters - **JSX returns**: Functions that return JSX elements or fragments - **First parameter destructuring**: Only processes the first parameter if it's object destructuring This ensures the rule only applies to actual React components and doesn't interfere with regular JavaScript functions. ## Callback Detection Patterns The plugin recognizes callbacks using these patterns: - `on` + PascalCase: `onClick`, `onSubmit`, `onDataChange` - `set` + PascalCase: `setData`, `setUser`, `setIsLoading` - Ending with `Callback`: `submitCallback`, `errorCallback` - Ending with `Handler`: `clickHandler`, `submitHandler` - Starting with `handle`: `handleClick`, `handleSubmit` ## Examples ### Basic Component Sorting ```jsx // ❌ Before function Button({ onClick, disabled, children, id, type = "button" }) { return ( <button id={id} type={type} disabled={disabled} onClick={onClick}> {children} </button> ); } // ✅ After function Button({ id, type = "button", children, disabled, onClick }) { return ( <button id={id} type={type} disabled={disabled} onClick={onClick}> {children} </button> ); } ``` ### TypeScript Interface Sorting ```typescript // ❌ Before interface FormProps { onSubmit: (data: FormData) => void; title: string; id: string; description?: string; isLoading: boolean; onCancel: () => void; } // ✅ After interface FormProps { id: string; description?: string; isLoading: boolean; title: string; onCancel: () => void; onSubmit: (data: FormData) => void; } ``` ### Complex Component with All Options ```jsx // ❌ Before function UserCard({ onEdit, avatar, id, email, name, isOnline, onClick, ...rest }) { return <div {...rest}>...</div>; } // ✅ After (with default settings) function UserCard({ id, avatar, email, isOnline, name, onEdit, onClick, ...rest }) { return <div {...rest}>...</div>; } ``` ## Why Use This Plugin? ### Consistency Maintains consistent prop ordering across your entire codebase, making it easier for team members to read and understand component interfaces. ### Readability Places the most important props (like `id` and `key`) first, and groups related functionality together. ### Maintenance Reduces cognitive load when working with components by establishing predictable patterns. ### Code Reviews Eliminates discussions about prop ordering during code reviews, allowing teams to focus on logic and functionality. ## Integration with Existing Tools This plugin works seamlessly with: - **Prettier**: Handles formatting while this plugin handles ordering - **TypeScript**: Full support for TypeScript interfaces and type literals - **React**: Detects React components automatically - **ESLint**: Standard ESLint plugin architecture with auto-fix support ## Contributing We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details. ## License MIT License - see [LICENSE](LICENSE) file for details. ## Related - [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) - React specific linting rules - [eslint-plugin-simple-import-sort](https://github.com/lydell/eslint-plugin-simple-import-sort) - Import statement sorting - [@typescript-eslint](https://typescript-eslint.io/) - TypeScript ESLint rules