feat 🥁: add ESLint v9 extends field support and document 8.57.0 compatibility

- confirm compatibility with ESLint 8.57.0
- add support for ESLint v9 extends field in flat config
- maintain backward compatibility with existing usage patterns
- update docs with configuration examples

This commit enhances the plugin's configuration options for ESLint v9 users while
ensuring backward compatibility. Users can now use the familiar extends syntax
with flat config, simplifying integration into existing projects. Documentation
has been updated to demonstrate proper usage with both ESLint 8 and 9.

CHANGELOG.md

@@ -2,8 +2,15 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.10.0] - 2025-04-19
+
+- confirm compatibility with ESLint 8.57.0
+- add support for ESLint v9 extends field in flat config
+- maintain backward compatibility with existing usage patterns
+- update [README.md](README.md#usage) with configuration examples for both ESLint 8 and ESLint 9
 
 ## [1.9.0] - 2025-04-16
 
@@ -12,7 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Handles all vanilla-extract APIs, including style, recipe, fontFace, and keyframes
   - Ignores valid units in special contexts (e.g., CSS functions, custom properties)
   - Supports nested objects, media queries, and pseudo-selectors
-  - No autofix is provided because replacing or removing unknown units may result in unintended or invalid CSS; manual developer review is required
+  - No autofix is provided because replacing or removing unknown units may result in unintended or invalid CSS; manual
+    developer review is required
 
 ## [1.8.0] - 2025-04-12
 
@@ -25,7 +33,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [1.7.0] - 2025-04-07
 
-- add a recommended configuration preset that enables concentric-order and no-empty-style-blocks rules with error severity.
+- add a recommended configuration preset that enables concentric-order and no-empty-style-blocks rules with error
+  severity.
   - Fix plugin configuration structure to work properly
   - Set concentric-order and no-empty-style-blocks as recommended rules
   - Use error severity for recommended rules to enforce best practices

README.md

@@ -1,8 +1,15 @@
 # @antebudimir/eslint-plugin-vanilla-extract
 
-[![CI](https://github.com/antebudimir/eslint-plugin-vanilla-extract/actions/workflows/ci.yml/badge.svg)](https://github.com/antebudimir/eslint-plugin-vanilla-extract/actions/workflows/ci.yml)    [![Coverage Status](https://coveralls.io/repos/github/antebudimir/eslint-plugin-vanilla-extract/badge.svg?branch=main)](https://coveralls.io/github/antebudimir/eslint-plugin-vanilla-extract?branch=main)  [![npm version](https://img.shields.io/npm/v/@antebudimir/eslint-plugin-vanilla-extract.svg)](https://www.npmjs.com/package/@antebudimir/eslint-plugin-vanilla-extract)  ![NPM Downloads](https://img.shields.io/npm/d18m/%40antebudimir%2Feslint-plugin-vanilla-extract)
+[![CI](https://github.com/antebudimir/eslint-plugin-vanilla-extract/actions/workflows/ci.yml/badge.svg)](https://github.com/antebudimir/eslint-plugin-vanilla-extract/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/antebudimir/eslint-plugin-vanilla-extract/badge.svg?branch=main)](https://coveralls.io/github/antebudimir/eslint-plugin-vanilla-extract?branch=main)
+[![npm version](https://img.shields.io/npm/v/@antebudimir/eslint-plugin-vanilla-extract.svg)](https://www.npmjs.com/package/@antebudimir/eslint-plugin-vanilla-extract)
+![NPM Downloads](https://img.shields.io/npm/d18m/%40antebudimir%2Feslint-plugin-vanilla-extract)
 
-An ESLint plugin for enforcing best practices in [vanilla-extract](https://github.com/vanilla-extract-css/vanilla-extract) CSS styles, including CSS property ordering and additional linting rules. Available presets are for alphabetical and [concentric](https://rhodesmill.org/brandon/2011/concentric-css/) CSS ordering. The plugin also supports a custom group ordering option based on groups available in [concentric CSS](src/css-rules/concentric-order/concentric-groups.ts).
+An ESLint plugin for enforcing best practices in
+[vanilla-extract](https://github.com/vanilla-extract-css/vanilla-extract) CSS styles, including CSS property ordering
+and additional linting rules. Available presets are for alphabetical and
+[concentric](https://rhodesmill.org/brandon/2011/concentric-css/) CSS ordering. The plugin also supports a custom group
+ordering option based on groups available in [concentric CSS](src/css-rules/concentric-order/concentric-groups.ts).
 
 ## Demo
 
@@ -14,7 +21,7 @@ An ESLint plugin for enforcing best practices in [vanilla-extract](https://githu
   - Alphabetical ordering for clean, predictable style organization
   - Concentric ordering for logical, outside-in property arrangement
 - Custom group ordering option for more fine-grained control
-- Built for ESLint 9 flat config system
+- Compatible with ESLint 8.57.0+ and fully optimized for ESLint 9's flat config system
 - Provides auto-fix capability to automatically sort properties
 - Handles multiple vanilla-extract APIs (style, styleVariants, recipe, globalStyle, etc.)
 - Handles complex cases like nested objects, arrays of styles, and pseudo selectors
@@ -23,9 +30,12 @@ An ESLint plugin for enforcing best practices in [vanilla-extract](https://githu
 
 ## Requirements
 
-- ESLint 9.0.0 or higher
+- ESLint 8.57.0 or higher
 - Node.js 18.18.0 or higher
 - ESM (ECMAScript Modules) only
+- Flat config system using either:
+  - `eslint.config.mjs` (recommended, always works with ESM plugins)
+  - `eslint.config.js` (only if your package.json has `"type": "module"`)
 
 ## Installation
 
@@ -38,21 +48,47 @@ yarn add --dev @antebudimir/eslint-plugin-vanilla-extract
 
 # Using pnpm
 pnpm add -D @antebudimir/eslint-plugin-vanilla-extract
+
+# For ESLint 8.57.0 with flat config, you'll also need:
+npm install --save-dev @eslint/eslintrc @eslint/js
+yarn add --dev @eslint/eslintrc @eslint/js
+pnpm add -D @eslint/eslintrc @eslint/js
 ```
 
 ## Usage
 
 **Note: This plugin is ESM-only.** It must be used with ESM configurations and can't be used with CommonJS `require()`.
 
-### ESLint Flat Config (ESLint 9+)
+### Configuration Options
 
-Create or update your `eslint.config.js` or `eslint.config.mjs` file:
+There are two main ways to configure this plugin in your ESLint flat config:
+
+### Option 1: Using extends (recommended, available from v1.10.0)
+
+The simplest way to apply the recommended ruleset:
 
 ```typescript
+import { defineConfig } from 'eslint/config';
 import vanillaExtract from '@antebudimir/eslint-plugin-vanilla-extract';
 
-// Using the recommended configuration
+export default defineConfig([
-export default [
+  {
+    files: ['**/*.css.ts'],
+    ignores: ['src/**/theme-contract.css.ts'],
+    extends: [vanillaExtract.configs.recommended],
+  },
+];
+```
+
+### Option 2: Using plugins with explicit rule configuration
+
+This approach gives you more control over individual rules:
+
+```typescript
+import { defineConfig } from 'eslint/config';
+import vanillaExtract from '@antebudimir/eslint-plugin-vanilla-extract';
+
+export default defineConfig([
   {
     files: ['**/*.css.ts'],
     ignores: ['src/**/theme-contract.css.ts'],
@@ -75,6 +111,80 @@ export default [
 ];
 ```
 
+### Using with FlatCompat (for ESLint 8.57.0 & 8.57.1)
+
+If you're migrating from legacy ESLint configurations, you can use the `FlatCompat` utility to convert them while adding
+vanilla-extract support:
+
+```typescript
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { FlatCompat } from '@eslint/eslintrc';
+import js from '@eslint/js';
+import vanillaExtract from '@antebudimir/eslint-plugin-vanilla-extract';
+
+// Mimic CommonJS variables
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Create a compatibility layer instance
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended,
+});
+
+export default [
+  // Convert your existing ESLint configs
+  ...compat.config({
+    extends: [
+      'eslint:recommended',
+      'plugin:@typescript-eslint/recommended',
+      // etc
+    ],
+  }),
+
+  // Add vanilla-extract by using explicit rule config
+  {
+    files: ['**/*.css.ts'],
+    ignores: ['src/**/theme-contract.css.ts'],
+    plugins: {
+      'vanilla-extract': vanillaExtract,
+    },
+    rules: {
+      // Apply all recommended rules
+      ...vanillaExtract.configs.recommended.rules,
+      // or specify rule by rule as described above
+    },
+  },
+];
+```
+
+#### Common Issues with FlatCompat
+
+1. **Error: "Unexpected top-level property 'files'"**
+
+   - Solution: When using `compat.config()`, use `overrides` instead of `files` at the top level.
+
+2. **Error: "Missing parameter 'recommendedConfig' in FlatCompat constructor"**
+
+   - Solution: Import `js` from `@eslint/js` and add `recommendedConfig: js.configs.recommended` to the FlatCompat
+     constructor.
+
+3. **Error: "Unexpected undefined config at user-defined index 0"**
+   - Solution: Make sure you're using a default export for your configuration array.
+
+### VS Code Integration
+
+For VS Code users, add these settings to your `.vscode/settings.json`:
+
+```json
+{
+  "eslint.useFlatConfig": true,
+  "eslint.experimental.useFlatConfig": true,
+  "eslint.validate": ["javascript", "typescript", "typescriptreact"]
+}
+```
+
 ### Recommended Configuration
 
 The recommended configuration enables the following rules with error severity:
@@ -181,20 +291,27 @@ export const myStyle = style({
 
 ### vanilla-extract/custom-order
 
-The `vanilla-extract/custom-order` rule enables you to enforce a custom ordering of CSS properties in your vanilla-extract styles. You can specify an array of property groups in your preferred order, and the rule will ensure that properties within these groups are sorted according to their position in the concentric CSS model.
+The `vanilla-extract/custom-order` rule enables you to enforce a custom ordering of CSS properties in your
+vanilla-extract styles. You can specify an array of property groups in your preferred order, and the rule will ensure
+that properties within these groups are sorted according to their position in the concentric CSS model.
 
 Key features of this rule include:
 
 1. Custom group ordering: Define your preferred order of CSS property groups.
-2. Handling of unspecified groups: All groups not included in the custom array will have their properties sorted after the last specified group.
+2. Handling of unspecified groups: All groups not included in the custom array will have their properties sorted after
-3. Flexible sorting options: You can choose to sort remaining properties either alphabetically or following the concentric CSS order by setting the `sortRemainingProperties` option to 'alphabetical' or 'concentric' respectively.
+   the last specified group.
+3. Flexible sorting options: You can choose to sort remaining properties either alphabetically or following the
+   concentric CSS order by setting the `sortRemainingProperties` option to 'alphabetical' or 'concentric' respectively.
 
 Default behavior:
 
 - If not set, `sortRemainingProperties` defaults to 'alphabetical'.
-- If no `groupOrder` is specified or an empty array is provided, the rule will default to sorting all properties alphabetically, and `sortRemainingProperties` will be ignored even if set.
+- If no `groupOrder` is specified or an empty array is provided, the rule will default to sorting all properties
+  alphabetically, and `sortRemainingProperties` will be ignored even if set.
 
-To configure the rule, add it to your ESLint configuration file with your desired options. You can customize the `groups` array to include any number of available CSS property groups you want to enforce, with a minimum of one group required.
+To configure the rule, add it to your ESLint configuration file with your desired options. You can customize the
+`groups` array to include any number of available CSS property groups you want to enforce, with a minimum of one group
+required.
 
 ```typescript
 // ❌ Incorrect (Unordered)
@@ -237,7 +354,8 @@ export const myStyle = style({
 
 ### vanilla-extract/no-empty-style-blocks
 
-This rule detects and prevents empty style blocks in vanilla-extract stylesheets. It helps maintain cleaner codebases by eliminating empty style definitions that often result from incomplete refactoring or forgotten implementations.
+This rule detects and prevents empty style blocks in vanilla-extract stylesheets. It helps maintain cleaner codebases by
+eliminating empty style definitions that often result from incomplete refactoring or forgotten implementations.
 
 ```typescript
 // ❌ Incorrect
@@ -273,23 +391,24 @@ export const recipeWithEmptyVariants = recipe({
 
 ## vanilla-extract/no-unknown-unit
 
-This rule enforces the use of valid CSS units in vanilla-extract style objects. It prevents typos and non-standard units that could cause styling issues or browser compatibility problems.
+This rule enforces the use of valid CSS units in vanilla-extract style objects. It prevents typos and non-standard units
+that could cause styling issues or browser compatibility problems.
 
 ```typescript
 // ❌ Incorrect
 import { style, globalStyle, recipe } from '@vanilla-extract/css';
 
 export const invalidStyle = style({
-  margin: '5abc',   // Non-existent unit
+  margin: '5abc', // Non-existent unit
   fontSize: '1.5rems', // Typo in unit
 });
 
 export const myRecipe = recipe({
   variants: {
     size: {
-      large: { padding: '4xm' } // Invalid unit
+      large: { padding: '4xm' }, // Invalid unit
-    }
+    },
-  }
+  },
 });
 
 // ✅ Correct
@@ -303,15 +422,16 @@ export const validStyle = style({
 export const myRecipe = recipe({
   variants: {
     size: {
-      large: { padding: '4em' }
+      large: { padding: '4em' },
-    }
+    },
-  }
+  },
 });
 ```
 
 ## vanilla-extract/no-zero-unit
 
-This rule enforces the removal of unnecessary units for zero values in vanilla-extract style objects. It helps maintain cleaner and more consistent CSS by eliminating redundant units when the value is zero.
+This rule enforces the removal of unnecessary units for zero values in vanilla-extract style objects. It helps maintain
+cleaner and more consistent CSS by eliminating redundant units when the value is zero.
 
 ```typescript
 // ❌ Incorrect
@@ -339,7 +459,8 @@ export const myStyle = style({
 
 ## Font Face Declarations
 
-For `fontFace` and `globalFontFace` API calls, all three ordering rules (alphabetical, concentric, and custom) enforce the same special ordering:
+For `fontFace` and `globalFontFace` API calls, all three ordering rules (alphabetical, concentric, and custom) enforce
+the same special ordering:
 
 1. The `src` property always appears first
 2. All remaining properties are sorted alphabetically
@@ -367,7 +488,8 @@ Opinionated, but it is what it is. If someone has a suggestion for a better orde
 
 ## Concentric CSS Model
 
-Here's a list of all available groups from the provided [concentricGroups](src/css-rules/concentric-order/concentric-groups.ts) array:
+Here's a list of all available groups from the provided
+[concentricGroups](src/css-rules/concentric-order/concentric-groups.ts) array:
 
 1. boxSizing
 2. position
@@ -399,7 +521,8 @@ Here's a list of all available groups from the provided [concentricGroups](src/c
 28. counters
 29. breaks
 
-These groups represent different categories of CSS properties, organized in a concentric order from outside to inside. Each group contains related CSS properties that affect specific aspects of an element's styling and layout.
+These groups represent different categories of CSS properties, organized in a concentric order from outside to inside.
+Each group contains related CSS properties that affect specific aspects of an element's styling and layout.
 
 ## Roadmap
 
@@ -414,21 +537,24 @@ The roadmap outlines the project's current status and future plans:
 - Recommended ESLint configuration for the plugin.
 - `no-zero-unit` rule to disallow units when the value is zero.
 - `no-unknown-unit` rule to disallow unknown units.
+- Support for using the plugin’s recommended config via the extends field (as discussed in
+  [issue #3](https://github.com/antebudimir/eslint-plugin-vanilla-extract/issues/3))
 - Comprehensive rule testing.
 
 ### Current Work
 
-- Support for using the plugin’s recommended config via the extends field (as discussed in [issue #3](https://github.com/antebudimir/eslint-plugin-vanilla-extract/issues/3))
+- `no-number-trailing-zero` rule to disallow trailing zeros in numbers.
 
 ### Upcoming Features
 
-- `no-number-trailing-zero` rule to disallow trailing zeros in numbers.
 - `no-px-unit` rule to disallow use of `px` units with configurable whitelist.
 - `prefer-logical-properties` rule to enforce use of logical properties.
 - `prefer-theme-tokens` rule to enforce use of theme tokens instead of hard-coded values when available.
 - `no-global-style` rule to disallow use of `globalStyle` function.
-- `property-unit-match` rule to enforce valid units per CSS property specs. **Note**: This feature will only be implemented if there's sufficient interest from the community.
+- `property-unit-match` rule to enforce valid units per CSS property specs. **Note**: This feature will only be
-- Option to sort properties within user-defined concentric groups alphabetically instead of following the concentric order. **Note**: This feature will only be implemented if there's sufficient interest from the community.
+  implemented if there's sufficient interest from the community.
+- Option to sort properties within user-defined concentric groups alphabetically instead of following the concentric
+  order. **Note**: This feature will only be implemented if there's sufficient interest from the community.
 
 ## Contributing
 

eslint.config.mjs

@@ -1,22 +1,10 @@
-import path from 'path';
-import { fileURLToPath } from 'url';
-import { FlatCompat } from '@eslint/eslintrc';
 import eslintPluginESLintPlugin from 'eslint-plugin-eslint-plugin';
 import importPlugin from 'eslint-plugin-import';
+import { defineConfig } from 'eslint/config';
+import prettierConfig from 'eslint-config-prettier';
 import * as tseslint from 'typescript-eslint';
 
-// mimic CommonJS variables
+export default defineConfig([
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const compat = new FlatCompat({
-  baseDirectory: __dirname,
-});
-
-export default [
-  // mimic ESLintRC-style extends
-  // Prettier always must be last to override other style rules
-  ...compat.extends('prettier'),
   {
     files: ['**/*.js', '**/*.ts', '**/*.cjs', '**/*.mjs'],
     plugins: {
@@ -74,6 +62,7 @@ export default [
       'import/export': 'error',
     },
   },
+
   ...tseslint.configs.recommended,
 
   {
@@ -103,4 +92,6 @@ export default [
       'no-unused-vars': 'off',
     },
   },
-];
+
+  prettierConfig,
+]);

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antebudimir/eslint-plugin-vanilla-extract",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "ESLint plugin for enforcing best practices in vanilla-extract CSS styles, including CSS property ordering and additional linting rules.",
   "author": "Ante Budimir",
   "license": "MIT",
@@ -63,7 +63,7 @@
     ]
   },
   "peerDependencies": {
-    "eslint": ">=9.0.0"
+    "eslint": ">=8.57.0"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.0",

src/index.ts

@@ -5,10 +5,10 @@ import noEmptyStyleBlocksRule from './css-rules/no-empty-blocks/rule-definition.
 import noUnknownUnitRule from './css-rules/no-unknown-unit/rule-definition.js';
 import noZeroUnitRule from './css-rules/no-zero-unit/rule-definition.js';
 
-export const vanillaExtract = {
+const vanillaExtract = {
   meta: {
     name: '@antebudimir/eslint-plugin-vanilla-extract',
-    version: '1.9.0',
+    version: '1.10.0',
   },
   rules: {
     'alphabetical-order': alphabeticalOrderRule,
@@ -18,17 +18,21 @@ export const vanillaExtract = {
     'no-unknown-unit': noUnknownUnitRule,
     'no-zero-unit': noZeroUnitRule,
   },
-  configs: {
+  configs: {},
-    recommended: {
-      plugins: ['vanilla-extract'],
-      rules: {
-        'vanilla-extract/concentric-order': 'error',
-        'vanilla-extract/no-empty-style-blocks': 'error',
-        'vanilla-extract/no-unknown-unit': 'error',
-        'vanilla-extract/no-zero-unit': 'error',
-      },
-    },
-  },
 };
 
+Object.assign(vanillaExtract.configs, {
+  recommended: {
+    plugins: {
+      'vanilla-extract': vanillaExtract,
+    },
+    rules: {
+      'vanilla-extract/concentric-order': 'error',
+      'vanilla-extract/no-empty-style-blocks': 'error',
+      'vanilla-extract/no-unknown-unit': 'error',
+      'vanilla-extract/no-zero-unit': 'error',
+    },
+  },
+});
+
 export default vanillaExtract;