Resolving JSX File Extension Restrictions in ESLint Configuration: An In-Depth Analysis of the react/jsx-filename-extension Rule

Problem Background and Error Analysis

When using eslint-config-airbnb to configure ESLint, developers frequently encounter a common yet confusing error: error JSX not allowed in files with extension '.js' react/jsx-filename-extension. This error originates from the jsx-filename-extension rule in the eslint-plugin-react plugin, which by default only permits JSX syntax in files with the .jsx extension.

eslint-config-airbnb, as the official configuration package for Airbnb's JavaScript style guide, does pre-configure React support, including JSX syntax checking. However, its default settings adhere to the best practice of placing JSX code in .jsx files, which triggers rule violations when JSX is used in .js files.

Solution One: Modify File Extensions

The most straightforward solution is to follow the rule's design intent by changing file extensions from .js to .jsx for files containing JSX code. This approach fully complies with the default behavior of the jsx-filename-extension rule without requiring any configuration changes. For example, renaming App.js to App.jsx will prevent ESLint from reporting this error.

The advantage of this method is that it enforces a clear file naming convention, making the project structure more standardized. In large projects, being able to quickly identify which files contain JSX code by their extensions enhances code maintainability. However, if a project has already established a convention of using .js extensions or needs compatibility with existing toolchains, this approach may lack flexibility.

Solution Two: Adjust ESLint Configuration

For projects that wish to continue using .js extensions, the ESLint configuration can be modified to allow .js files to contain JSX code. This requires overriding the default settings of the react/jsx-filename-extension rule.

Add the following configuration to the rules section of the .eslintrc configuration file:

"rules": {
  "react/jsx-filename-extension": [1, { "extensions": [".js", ".jsx"] }],
}

This configuration uses the standard syntactic structure of ESLint rules:

• The first parameter 1 sets the rule severity level to warning, not error. This allows developers to ignore warnings when necessary while maintaining flexibility in code checking.
• The second parameter is a configuration object where the extensions array specifies the file extensions allowed to contain JSX. By default, this array only includes ".jsx"; adding ".js" extends the permitted range.

For stricter checking, the severity level can be changed to 2 (error), causing any violation to fail the build:

"react/jsx-filename-extension": [2, { "extensions": [".js", ".jsx"] }]

Configuration Details and Best Practices

Understanding the configuration options of the jsx-filename-extension rule is crucial for developing a strategy suitable for the project. Beyond the extensions array, the rule supports other options, but controlling allowed file extensions is the most commonly used.

In practical projects, the choice of solution should consider the following factors:

1. Project Scale and Team Conventions: Large teams may prefer uniform file extension norms, while small projects might prioritize configuration flexibility.
2. Build Tool Compatibility: Some build tools or module resolvers may have specific requirements for file extensions, necessitating compatibility with the toolchain.
3. Code Readability: Using .jsx extensions can visually distinguish pure JavaScript files from those containing JSX, which is particularly useful in complex projects.

Regardless of the chosen method, the rationale should be clearly documented in the project's ESLint configuration to ensure team members understand and follow consistent code standards.

Collaboration with Other ESLint Rules

When adjusting the jsx-filename-extension rule, attention must also be paid to its interaction with other ESLint rules. For instance, if the import/extensions rule (which controls file extensions in module imports) is also used, its configuration may need adjustment to avoid conflicts.

A complete configuration example is as follows:

{
  "extends": "eslint-config-airbnb",
  "rules": {
    "react/jsx-filename-extension": [1, { "extensions": [".js", ".jsx"] }],
    "import/extensions": ["error", "ignorePackages", {
      "js": "never",
      "jsx": "never"
    }]
  }
}

Such a configuration ensures consistency in file extension handling across the codebase.

Conclusion

By deeply understanding the design principles and configuration methods of the react/jsx-filename-extension rule, developers can flexibly resolve the 'JSX not allowed in files with extension '.js'' error. Whether through modifying file extensions or adjusting ESLint configuration, the key is to choose the most appropriate strategy based on project needs and establish clear code standards within the team. The default configuration provided by eslint-config-airbnb serves as a good starting point, but with proper customization, it can better adapt to specific development workflows.