@vijayhardaha/dev-config 2.3.1 → 2.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vijayhardaha/dev-config",
-  "version": "2.3.1",
+  "version": "2.4.1",
   "description": "Reusable development configurations for Next.js + TypeScript projects",
   "scripts": {
     "lint": "eslint .",
@@ -66,31 +66,34 @@
     "typescript"
   ],
   "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@commitlint/cli": "^21.2.1",
-    "@commitlint/config-conventional": "^21.2.0",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
     "@commitlint/types": "^21.2.0",
-    "@typescript-eslint/parser": "^8.66.0",
-    "@typescript-eslint/eslint-plugin": "^8.66.0",
-    "@vitest/coverage-v8": "^4.1.10",
-    "eslint": "^10.8.0",
-    "eslint-config-next": "^16.3.0",
+    "@eslint/js": "^10.0.1",
+    "@prettier/plugin-xml": "^3.4.2",
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.67.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10.9.0",
+    "eslint-config-next": "^16.3.2",
     "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-better-tailwindcss": "^4.7.0",
     "eslint-plugin-import-x": "^4.17.1",
     "eslint-plugin-jsdoc": "^63.3.3",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-prettier": "^5.5.6",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
-    "globals": "^17.9.0",
+    "eslint-plugin-tailwindcss": "^4.4.0",
+    "globals": "^17.11.0",
     "husky": "^9.1.7",
-    "next": "^16.3.0",
+    "next": "^16.3.2",
     "prettier": "^3.9.6",
-    "@prettier/plugin-xml": "^3.4.2",
-    "release-it": "^21.0.1",
+    "release-it": "^21.0.2",
+    "tailwindcss": "^4.3.3",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.66.0",
-    "vitest": "^4.1.10"
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.1.11"
   },
   "peerDependencies": {
     "@commitlint/cli": ">=21",
@@ -106,22 +109,24 @@
     "eslint-config-next": ">=16",
     "eslint-config-prettier": ">=10",
     "eslint-import-resolver-typescript": ">=4",
+    "eslint-plugin-better-tailwindcss": ">=4",
     "eslint-plugin-import-x": ">=4",
-    "eslint-plugin-jsdoc": ">=62",
+    "eslint-plugin-jsdoc": ">=63",
     "eslint-plugin-jsx-a11y": ">=6",
     "eslint-plugin-prettier": ">=5",
     "eslint-plugin-react": ">=7",
-    "eslint-plugin-react-hooks": ">=5",
+    "eslint-plugin-react-hooks": ">=7",
+    "eslint-plugin-tailwindcss": ">=4",
     "globals": ">=17",
     "husky": ">=9",
-    "next-sitemap": ">=4",
     "next": ">=16",
+    "next-sitemap": ">=4",
     "prettier": ">=3",
     "stylelint": ">=17",
     "stylelint-config-property-sort-order-smacss": ">=11",
     "stylelint-config-standard-scss": ">=17",
     "stylelint-order": ">=8",
-    "typescript": ">=5",
+    "typescript": ">=6",
     "typescript-eslint": ">=8"
   },
   "peerDependenciesMeta": {
@@ -149,6 +154,9 @@
     "eslint-import-resolver-typescript": {
       "optional": true
     },
+    "eslint-plugin-better-tailwindcss": {
+      "optional": true
+    },
     "eslint-plugin-jsx-a11y": {
       "optional": true
     },
@@ -158,6 +166,9 @@
     "eslint-plugin-react-hooks": {
       "optional": true
     },
+    "eslint-plugin-tailwindcss": {
+      "optional": true
+    },
     "husky": {
       "optional": true
     },

package/src/eslint/__tests__/next.test.js

@@ -28,4 +28,58 @@ describe('eslint/next.js', () => {
 
     expect(configObject.files).toContain('custom/**/*.tsx');
   });
+
+  // Test that Tailwind plugins are registered on the main config by default.
+  it('should register Tailwind plugins by default', async () => {
+    const module = await import('../next.js');
+    const result = module.createConfig();
+    const configObject = result.at(-1);
+
+    // Verify that the better-tailwindcss plugin is centrally registered.
+    expect(configObject.plugins['better-tailwindcss']).toBeDefined();
+
+    // Verify that the tailwindcss plugin is centrally registered.
+    expect(configObject.plugins.tailwindcss).toBeDefined();
+
+    // Verify that the Tailwind canonicalization rule is enabled.
+    expect(configObject.rules['better-tailwindcss/enforce-canonical-classes']).toBe('warn');
+
+    // Verify that the arbitrary value replacement rule is enabled.
+    expect(configObject.rules['tailwindcss/no-unnecessary-arbitrary-value']).toBe('warn');
+  });
+
+  // Test that Tailwind plugins, rules, and settings are omitted when disabled.
+  it('should omit Tailwind plugins and rules when tailwind option is false', async () => {
+    const module = await import('../next.js');
+    const result = module.createConfig({ tailwind: false });
+    const configObject = result.at(-1);
+
+    // Verify that no Tailwind plugins are centrally registered.
+    expect(configObject.plugins['better-tailwindcss']).toBeUndefined();
+    expect(configObject.plugins.tailwindcss).toBeUndefined();
+
+    // Verify that no Tailwind rules are present in the config.
+    expect(Object.keys(configObject.rules).filter((rule) => rule.startsWith('better-tailwindcss/'))).toHaveLength(0);
+    expect(Object.keys(configObject.rules).filter((rule) => rule.startsWith('tailwindcss/'))).toHaveLength(0);
+
+    // Verify that no Tailwind settings are present in the config.
+    expect(configObject.settings.tailwindcss).toBeUndefined();
+    expect(configObject.settings['better-tailwindcss']).toBeUndefined();
+  });
+
+  // Test that user settings override the generated Tailwind settings.
+  it('should let user settings override Tailwind settings', async () => {
+    const module = await import('../next.js');
+    const result = module.createConfig({
+      settings: {
+        'better-tailwindcss': { entryPoint: 'styles/site.css' },
+        tailwindcss: { cssConfigPath: 'styles/site.css' },
+      },
+    });
+    const configObject = result.at(-1);
+
+    // Verify that the user entry point wins over the auto-detected one.
+    expect(configObject.settings['better-tailwindcss'].entryPoint).toBe('styles/site.css');
+    expect(configObject.settings.tailwindcss.cssConfigPath).toBe('styles/site.css');
+  });
 });

package/src/eslint/__tests__/react.test.js

@@ -28,4 +28,42 @@ describe('eslint/react.js', () => {
 
     expect(configObject.files).toContain('custom/**/*.tsx');
   });
+
+  // Test that Tailwind plugins are registered on the main config by default.
+  it('should register Tailwind plugins by default', async () => {
+    const module = await import('../react.js');
+    const result = module.createConfig();
+    const configObject = result.at(-1);
+
+    // Verify that the better-tailwindcss plugin is centrally registered.
+    expect(configObject.plugins['better-tailwindcss']).toBeDefined();
+
+    // Verify that the tailwindcss plugin is centrally registered.
+    expect(configObject.plugins.tailwindcss).toBeDefined();
+
+    // Verify that the Tailwind canonicalization rule is enabled.
+    expect(configObject.rules['better-tailwindcss/enforce-canonical-classes']).toBe('warn');
+
+    // Verify that the arbitrary value replacement rule is enabled.
+    expect(configObject.rules['tailwindcss/no-unnecessary-arbitrary-value']).toBe('warn');
+  });
+
+  // Test that Tailwind plugins, rules, and settings are omitted when disabled.
+  it('should omit Tailwind plugins and rules when tailwind option is false', async () => {
+    const module = await import('../react.js');
+    const result = module.createConfig({ tailwind: false });
+    const configObject = result.at(-1);
+
+    // Verify that no Tailwind plugins are centrally registered.
+    expect(configObject.plugins['better-tailwindcss']).toBeUndefined();
+    expect(configObject.plugins.tailwindcss).toBeUndefined();
+
+    // Verify that no Tailwind rules are present in the config.
+    expect(Object.keys(configObject.rules).filter((rule) => rule.startsWith('better-tailwindcss/'))).toHaveLength(0);
+    expect(Object.keys(configObject.rules).filter((rule) => rule.startsWith('tailwindcss/'))).toHaveLength(0);
+
+    // Verify that no Tailwind settings are present in the config.
+    expect(configObject.settings.tailwindcss).toBeUndefined();
+    expect(configObject.settings['better-tailwindcss']).toBeUndefined();
+  });
 });

package/src/eslint/__tests__/tailwind.test.js

@@ -0,0 +1,123 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { ESLint } from 'eslint';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+
+/**
+ * Lints and fixes a TSX snippet against the Next.js config inside the temp
+ * fixture project.
+ *
+ * @param {object} projectDir - Fixture project root.
+ * @param {object} module - Imported next.js module.
+ * @param {string} code - TSX source code to lint.
+ * @param {object} [options] - createConfig options.
+ *
+ * @returns {Promise<object>} The single lint result for the snippet.
+ */
+const lintAndFix = async (projectDir, module, code, options = {}) => {
+  const config = module.createConfig({
+    settings: {
+      'better-tailwindcss': { entryPoint: 'src/app/globals.css' },
+      tailwindcss: { cssConfigPath: 'src/app/globals.css' },
+    },
+    ...options,
+  });
+  const eslint = new ESLint({ cwd: projectDir, overrideConfigFile: true, overrideConfig: config, fix: true });
+
+  const [result] = await eslint.lintText(code, { filePath: path.join(projectDir, 'src/Button.tsx') });
+
+  return result;
+};
+
+// Test suite for Tailwind autofix behavior through the shared config pipeline.
+describe('eslint tailwind autofix', () => {
+  let projectDir;
+  let nextModule;
+
+  beforeAll(async () => {
+    nextModule = await import('../next.js');
+
+    // Create an isolated fixture project that mimics a Next.js app layout.
+    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dev-config-tailwind-'));
+    fs.writeFileSync(
+      path.join(projectDir, 'package.json'),
+      JSON.stringify({ name: 'tailwind-fixture', private: true, type: 'module' })
+    );
+    fs.mkdirSync(path.join(projectDir, 'src/app'), { recursive: true });
+    fs.writeFileSync(path.join(projectDir, 'src/app/globals.css'), '@import "tailwindcss";\n');
+    fs.symlinkSync(path.resolve(process.cwd(), 'node_modules'), path.join(projectDir, 'node_modules'), 'dir');
+  });
+
+  afterAll(() => {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  // Test that arbitrary values with theme scale equivalents are replaced.
+  it('should replace arbitrary values with theme scale utilities', async () => {
+    const code = [
+      'const Button = () => (',
+      '  <div className="aspect-[3/4] max-w-[280px] p-[16px]">Button</div>',
+      ');',
+      '',
+    ].join('\n');
+
+    const result = await lintAndFix(projectDir, nextModule, code);
+
+    expect(result.output).toContain('aspect-3/4');
+    expect(result.output).toContain('max-w-70');
+    expect(result.output).toContain('p-4');
+  }, 60_000);
+
+  // Test that cn() classes keep their variant prefixes after conversion.
+  it('should convert cn() classes while preserving variant prefixes', async () => {
+    const code = [
+      'const Button = ({ side }) => (',
+      `  <div className={cn("data-[side=bottom]:translate-y-[2.5rem]", "dark:hover:translate-x-[-2.5rem]")}>`,
+      '    Button',
+      '  </div>',
+      ');',
+      '',
+    ].join('\n');
+
+    const result = await lintAndFix(projectDir, nextModule, code, { rules: { 'import-x/order': 'off' } });
+
+    expect(result.output).toContain('data-[side=bottom]:translate-y-10');
+    expect(result.output).toContain('dark:hover:-translate-x-10');
+  }, 60_000);
+
+  // Test that long class strings are wrapped into readable multi-line groups.
+  it('should wrap long class strings into multi-line groups', async () => {
+    const longClasses =
+      'flex flex-col items-start justify-between gap-6 rounded-xl border border-slate-200 bg-white p-8 shadow-sm '
+      + 'transition-all hover:-translate-y-1 hover:shadow-lg dark:border-slate-800 dark:bg-slate-900';
+    const code = ['const Card = () => (', `  <div className="${longClasses}">Card</div>`, ');', ''].join('\n');
+
+    const result = await lintAndFix(projectDir, nextModule, code);
+
+    expect(result.output).toMatch(/className="\n\s+flex/);
+  }, 60_000);
+
+  // Test that disabling the tailwind option leaves class strings untouched.
+  it('should not touch class strings when tailwind option is false', async () => {
+    const code = [
+      'const Button = () => (',
+      '  <div className="aspect-[3/4] max-w-[280px] p-[16px]">Button</div>',
+      ');',
+      '',
+    ].join('\n');
+
+    const result = await lintAndFix(projectDir, nextModule, code, { tailwind: false });
+
+    // Verify that no fixes were applied and the arbitrary classes remain.
+    expect(result.output).toBeUndefined();
+    expect(result.source).toContain('aspect-[3/4]');
+
+    // Verify that no Tailwind rule contributed messages.
+    const tailwindMessages = result.messages.filter(
+      (message) => message.ruleId?.startsWith('better-tailwindcss/') || message.ruleId?.startsWith('tailwindcss/')
+    );
+    expect(tailwindMessages).toHaveLength(0);
+  }, 60_000);
+});

package/src/eslint/lib/__tests__/build-config.branches.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// Hide the project .gitignore from the builder so the absent-gitignore
+// fallback branches execute during config assembly.
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal();
+  return { ...actual, existsSync: (path) => (String(path).endsWith('.gitignore') ? false : actual.existsSync(path)) };
+});
+
+describe('eslint/lib/build-config.js branch paths', () => {
+  it('omits gitignore config when .gitignore is absent', async () => {
+    // Import after the mock is in place.
+    const buildConfigModule = await import('../build-config.js');
+
+    // Build a config without extra inputs.
+    const result = buildConfigModule.buildConfig({ files: ['**/*.js'] });
+
+    // Verify that the config array still ends with the main object.
+    expect(Array.isArray(result)).toBe(true);
+    expect(result.at(-1).files).toContain('**/*.js');
+  });
+
+  it('merges user globalIgnores with defaults', async () => {
+    // Import after the mock is in place.
+    const buildConfigModule = await import('../build-config.js');
+
+    // Build a config with user-provided global ignore patterns.
+    const result = buildConfigModule.buildConfig({
+      files: ['**/*.js'],
+      options: { globalIgnores: ['**/.cache-custom/'] },
+    });
+
+    // Verify that the user pattern lands alongside the defaults.
+    const ignoreConfig = result.find((cfg) => Array.isArray(cfg.ignores));
+    expect(ignoreConfig.ignores).toContain('**/.cache-custom/');
+    expect(ignoreConfig.ignores).toContain('**/node_modules/');
+  });
+
+  it('leaves ignores off the main object when none provided', async () => {
+    // Import after the mock is in place.
+    const buildConfigModule = await import('../build-config.js');
+
+    // Build a config without ignore overrides.
+    const result = buildConfigModule.buildConfig({ files: ['**/*.js'] });
+
+    // Verify that the main object carries no ignores property.
+    expect(result.at(-1).ignores).toBeUndefined();
+  });
+
+  it('spreads provided ignores onto the main object', async () => {
+    // Import after the mock is in place.
+    const buildConfigModule = await import('../build-config.js');
+
+    // Build a config with user-provided ignore patterns on the main object.
+    const result = buildConfigModule.buildConfig({ files: ['**/*.js'], options: { ignores: ['**/generated/'] } });
+
+    // Verify that only the provided patterns land on the main object.
+    expect(result.at(-1).ignores).toEqual(['**/generated/']);
+  });
+});

package/src/eslint/lib/__tests__/build-config.optional-deps.test.js

@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// Simulate the optional TypeScript import resolver being absent so the
+// top-level fallback branch and its debug logging execute at load time.
+vi.mock('eslint-import-resolver-typescript', () => {
+  throw new Error('simulated missing dependency');
+});
+
+describe('eslint/lib/build-config.js with missing optional resolver', () => {
+  it('falls back gracefully when eslint-import-resolver-typescript is missing', async () => {
+    // Enable debug logging before the module is evaluated so the fallback
+    // branch emits its install hint.
+    process.env.DEBUG = '*';
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+
+    // Import after the mock and DEBUG are in place.
+    const buildConfigModule = await import('../build-config.js');
+
+    // Verify that config building still works without the optional resolver.
+    expect(typeof buildConfigModule.buildConfig).toBe('function');
+    expect(debugSpy).toHaveBeenCalledWith(expect.stringContaining('eslint-import-resolver-typescript'));
+
+    // Verify that import resolution falls back to the node resolver alone.
+    const result = buildConfigModule.buildConfig({ files: ['**/*.js'] });
+    expect(result.at(-1).settings['import-x/resolver-next']).toHaveLength(1);
+
+    delete process.env.DEBUG;
+  });
+
+  it('stays silent without DEBUG when the resolver is missing', async () => {
+    // Drop DEBUG so the fallback logging condition evaluates to false.
+    delete process.env.DEBUG;
+    vi.resetModules();
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    debugSpy.mockClear();
+
+    // Re-import so top-level fallback branches run again under this env.
+    const buildConfigModule = await import('../build-config.js');
+
+    // Verify that no install hint is logged without DEBUG.
+    expect(debugSpy).not.toHaveBeenCalled();
+    expect(typeof buildConfigModule.buildConfig).toBe('function');
+  });
+});

package/src/eslint/lib/__tests__/rules.optional-deps.test.js

@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// Simulate both Tailwind plugins being absent so the lazy import catch
+// branches and their debug logging execute during module evaluation.
+vi.mock('eslint-plugin-better-tailwindcss', () => {
+  throw new Error('simulated missing dependency');
+});
+
+vi.mock('eslint-plugin-tailwindcss', () => {
+  throw new Error('simulated missing dependency');
+});
+
+// Report every probed entry point as existing so tailwindSettings takes the
+// found-entry-point branch without touching the filesystem.
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal();
+  return { ...actual, existsSync: () => true };
+});
+
+describe('eslint/lib/rules.js with missing optional plugins', () => {
+  const debugCalls = [];
+  let rules;
+
+  it('registers no central plugins, emits no rules, and logs install hints', async () => {
+    // Enable debug logging before the module is evaluated so each missing
+    // plugin emits its install hint.
+    process.env.DEBUG = 'eslint';
+    vi.spyOn(console, 'debug').mockImplementation((...args) => debugCalls.push(args.join(' ')));
+
+    // Import after mocks and DEBUG are in place so top-level awaits hit the
+    // catch branches.
+    rules = await import('../rules.js');
+
+    // Verify that no Tailwind plugins are registered when both are missing.
+    expect(rules.getTailwindCentralPlugins()).toEqual({});
+
+    // Verify that no Tailwind rules are emitted without better-tailwindcss.
+    expect(rules.tailwindRules()).toEqual({});
+
+    // Verify that install hints are logged for both missing plugins.
+    expect(debugCalls.some((message) => message.includes('eslint-plugin-better-tailwindcss'))).toBe(true);
+    expect(debugCalls.some((message) => message.includes('eslint-plugin-tailwindcss'))).toBe(true);
+
+    delete process.env.DEBUG;
+  });
+
+  it('resolves settings from the first candidate entry point', async () => {
+    // Reuse the module loaded with plugins absent; entry point probing is
+    // unaffected by their absence.
+    rules ??= await import('../rules.js');
+
+    // Verify that settings point at the first probed candidate path.
+    expect(rules.tailwindSettings()).toEqual({
+      tailwindcss: { cssConfigPath: 'src/app/globals.css' },
+      'better-tailwindcss': { entryPoint: 'src/app/globals.css' },
+    });
+  });
+
+  it('skips debug logging when DEBUG is unset', async () => {
+    // Drop DEBUG so both logging conditions evaluate to false.
+    delete process.env.DEBUG;
+    vi.resetModules();
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    debugSpy.mockClear();
+
+    // Re-import so top-level catch branches run again under this env.
+    await import('../rules.js');
+
+    // Verify that no install hints are logged without DEBUG.
+    expect(debugSpy).not.toHaveBeenCalled();
+  });
+
+  it('logs install hints under wildcard DEBUG', async () => {
+    // Wildcard DEBUG skips the substring check and enables logging.
+    process.env.DEBUG = '*';
+    vi.resetModules();
+    const debugCalls = [];
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation((...args) => debugCalls.push(args.join(' ')));
+    debugSpy.mockClear();
+
+    // Re-import so top-level catch branches run again under this env.
+    await import('../rules.js');
+
+    // Verify that install hints are logged for both missing plugins.
+    expect(debugCalls.some((message) => message.includes('eslint-plugin-better-tailwindcss'))).toBe(true);
+    expect(debugCalls.some((message) => message.includes('eslint-plugin-tailwindcss'))).toBe(true);
+  });
+});

package/src/eslint/lib/__tests__/rules.prettier-interop.test.js

@@ -0,0 +1,76 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// Shared handle to stub prettier.resolveConfig before modules evaluate.
+const mockResolveConfig = vi.hoisted(() => vi.fn());
+
+// Intercept prettier so entry-point detection can be simulated without
+// touching real consumer configs on disk.
+vi.mock('prettier', async (importOriginal) => {
+  const actual = await importOriginal();
+  return { ...actual, resolveConfig: mockResolveConfig };
+});
+
+describe('eslint/lib/rules.js with prettier-plugin-tailwindcss', () => {
+  it('drops ordering and wrapping rules when prettier-plugin-tailwindcss is active', async () => {
+    // Simulate a consumer Prettier config that enables the Tailwind plugin.
+    mockResolveConfig.mockResolvedValue({ plugins: ['prettier-plugin-tailwindcss'] });
+
+    const rules = await import('../rules.js');
+    const result = rules.tailwindRules();
+
+    // Verify formatter-owned concerns are left to Prettier.
+    expect(result['better-tailwindcss/enforce-consistent-class-order']).toBeUndefined();
+    expect(result['better-tailwindcss/enforce-consistent-line-wrapping']).toBeUndefined();
+
+    // Verify lint-only concerns stay enabled.
+    expect(result['better-tailwindcss/enforce-canonical-classes']).toBe('warn');
+    expect(result['better-tailwindcss/no-unnecessary-whitespace']).toBe('warn');
+    expect(result['tailwindcss/no-unnecessary-arbitrary-value']).toBe('warn');
+  });
+
+  it('keeps ordering and wrapping rules without the prettier plugin', async () => {
+    // Simulate a consumer Prettier config without the Tailwind plugin.
+    mockResolveConfig.mockResolvedValue({});
+
+    vi.resetModules();
+    const rules = await import('../rules.js');
+    const result = rules.tailwindRules();
+
+    // Verify all four better-tailwindcss rules remain enabled.
+    expect(result['better-tailwindcss/enforce-consistent-class-order']).toBe('warn');
+    expect(result['better-tailwindcss/enforce-consistent-line-wrapping']).toEqual(['warn', { printWidth: 120 }]);
+    expect(result['better-tailwindcss/enforce-canonical-classes']).toBe('warn');
+    expect(result['better-tailwindcss/no-unnecessary-whitespace']).toBe('warn');
+  });
+
+  it('falls back to full rules when prettier config resolution fails', async () => {
+    // Simulate prettier being unusable during config evaluation.
+    mockResolveConfig.mockRejectedValue(new Error('simulated resolution failure'));
+
+    vi.resetModules();
+    const rules = await import('../rules.js');
+    const result = rules.tailwindRules();
+
+    // Verify ordering and wrapping rules stay enabled on failure.
+    expect(result['better-tailwindcss/enforce-consistent-class-order']).toBe('warn');
+    expect(result['better-tailwindcss/enforce-consistent-line-wrapping']).toEqual(['warn', { printWidth: 120 }]);
+  });
+
+  it('logs an interop notice under DEBUG when the prettier plugin is active', async () => {
+    // Enable debug logging and simulate the active Tailwind Prettier plugin.
+    process.env.DEBUG = 'eslint';
+    mockResolveConfig.mockResolvedValue({ plugins: ['prettier-plugin-tailwindcss'] });
+    vi.resetModules();
+    const debugCalls = [];
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation((...args) => debugCalls.push(args.join(' ')));
+    debugSpy.mockClear();
+
+    // Re-import so top-level detection runs again under this env.
+    await import('../rules.js');
+
+    // Verify that the interop decision is logged.
+    expect(debugCalls.some((message) => message.includes('left to Prettier'))).toBe(true);
+
+    delete process.env.DEBUG;
+  });
+});

package/src/eslint/lib/__tests__/rules.test.js

@@ -60,4 +60,43 @@ describe('eslint/lib/rules.js', () => {
     // Verify that the jsdoc/require-jsdoc rule is present in the config.
     expect(result['jsdoc/require-jsdoc']).toBeDefined();
   });
+
+  // Test that Tailwind rules are included when tailwind option is true.
+  it('should include Tailwind rules when tailwind is true', () => {
+    // Call commonRules with tailwind option enabled.
+    const result = commonRules({ tailwind: true });
+
+    // Verify that the Tailwind canonicalization rule is present in the config.
+    expect(result['better-tailwindcss/enforce-canonical-classes']).toBeDefined();
+
+    // Verify that the Tailwind whitespace cleanup rule is present in the config.
+    expect(result['better-tailwindcss/no-unnecessary-whitespace']).toBeDefined();
+
+    // Verify that the Tailwind ordering rule is present in the config.
+    expect(result['better-tailwindcss/enforce-consistent-class-order']).toBeDefined();
+
+    // Verify that the Tailwind arbitrary value replacement rule is present in the config.
+    expect(result['tailwindcss/no-unnecessary-arbitrary-value']).toBeDefined();
+  });
+
+  // Test that line wrapping aligns with the shared Prettier print width.
+  it('should configure line wrapping with the shared Prettier print width', () => {
+    // Call commonRules with tailwind option enabled.
+    const result = commonRules({ tailwind: true });
+
+    // Verify that the wrapping rule uses the shared print width constant.
+    expect(result['better-tailwindcss/enforce-consistent-line-wrapping']).toEqual(['warn', { printWidth: 120 }]);
+  });
+
+  // Test that Tailwind rules are excluded when tailwind option is false.
+  it('should exclude Tailwind rules when tailwind is false', () => {
+    // Call commonRules with tailwind option disabled.
+    const result = commonRules({ tailwind: false });
+
+    // Verify that no better-tailwindcss rules are present in the config.
+    expect(Object.keys(result).filter((rule) => rule.startsWith('better-tailwindcss/'))).toHaveLength(0);
+
+    // Verify that no tailwindcss rules are present in the config.
+    expect(Object.keys(result).filter((rule) => rule.startsWith('tailwindcss/'))).toHaveLength(0);
+  });
 });

package/src/eslint/lib/build-config.js

@@ -10,7 +10,7 @@ import prettierRecommended from 'eslint-plugin-prettier/recommended';
 import { globalIgnores } from './ignores.js';
 import { commonLanguageOptions } from './language-options.js';
 import { getEnabledPlugins, flattenPlugins, fixupPlugins, stripPlugins, stripParser } from './plugin-helpers/index.js';
-import { commonRules } from './rules.js';
+import { commonRules, tailwindSettings } from './rules.js';
 import { commonParser } from './setup.js';
 
 let createTypeScriptImportResolver;
@@ -66,6 +66,16 @@ const buildConfigObject = ({
 }) => {
   const { ignores, rules, settings, extend } = opts;
 
+  // Resolve feature flags up front so downstream wiring stays readable.
+  const importOrderEnabled = Boolean(opts.importOrder);
+  const jsdocEnabled = Boolean(opts.jsdoc);
+  const prettierEnabled = Boolean(opts.prettier);
+  const typescriptEnabled = Boolean(typescript);
+
+  // Tailwind is opt-out (enabled by default) but only applies to configs that
+  // register the Tailwind plugins centrally, so JS/TS-only configs stay clean.
+  const tailwindEnabled = Boolean(opts.tailwind) && 'better-tailwindcss' in centralPlugins;
+
   return {
     files: [...filePatterns],
     ...(ignores && { ignores }),
@@ -74,23 +84,30 @@ const buildConfigObject = ({
     ),
     languageOptions: {
       ...commonLanguageOptions,
-      ...(typescript && commonParser),
+      ...(typescriptEnabled && commonParser),
       ...extraLanguageOptions,
-      ...(typescript && { parserOptions: { tsconfigRootDir: process.cwd(), ...parserOptions } }),
+      ...(typescriptEnabled && { parserOptions: { tsconfigRootDir: process.cwd(), ...parserOptions } }),
     },
     settings: {
-      ...(opts.importOrder && {
+      ...(importOrderEnabled && {
         'import-x/resolver-next': [
           createNodeResolver(),
           ...(createTypeScriptImportResolver ? [createTypeScriptImportResolver()] : []),
         ],
       }),
-      ...(opts.jsdoc && { jsdoc: { mode: 'typescript' } }),
+      ...(jsdocEnabled && { jsdoc: { mode: 'typescript' } }),
+      ...(tailwindEnabled && tailwindSettings()),
       ...extraSettings,
       ...settings,
     },
     rules: {
-      ...commonRules({ prettier: opts.prettier, importOrder: opts.importOrder, typescript, jsdoc: opts.jsdoc }),
+      ...commonRules({
+        prettier: prettierEnabled,
+        importOrder: importOrderEnabled,
+        typescript: typescriptEnabled,
+        jsdoc: jsdocEnabled,
+        tailwind: tailwindEnabled,
+      }),
       ...extraRules,
       ...rules,
     },
@@ -110,7 +127,7 @@ const buildConfigObject = ({
  * @param {object} [config.parserOptions] - Parser options.
  * @param {object} [config.settings] - Settings object.
  * @param {object} [config.rules] - Additional rules.
- * @param {object} [config.options] - User-provided options.
+ * @param {object} [config.options] - User-provided options. Tailwind rules are enabled by default and can be disabled with `tailwind: false`.
  * @param {boolean} [config.typescript] - Enable TypeScript support.
  *
  * @returns {import('eslint').Linter.Config[]} ESLint configuration array.
@@ -127,7 +144,7 @@ export const buildConfig = ({
   options = {},
   typescript = false,
 }) => {
-  const opts = { prettier: true, importOrder: true, jsdoc: true, ...options };
+  const opts = { prettier: true, importOrder: true, jsdoc: true, tailwind: true, ...options };
 
   const conditionalPluginList = getEnabledPlugins(conditionalPlugins, opts);
 

package/src/eslint/lib/index.js

@@ -1,2 +1,3 @@
 export { files } from './files.js';
 export { buildConfig } from './build-config.js';
+export { getTailwindCentralPlugins } from './rules.js';

package/src/eslint/lib/rules.js

@@ -1,5 +1,159 @@
 // ---- JSDoc Rules: enforce documentation on public/exported APIs ----
 
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { PRETTIER } from '../../config-constants.js';
+
+// ---- Optional Tailwind Plugins ----------------------------------------------------------
+// Both plugins are optional peers. They are loaded lazily so projects without
+// Tailwind tooling can still use this package. When a plugin is missing, its
+// rules are omitted instead of failing config resolution.
+
+let betterTailwindcssPlugin = null;
+try {
+  betterTailwindcssPlugin = (await import('eslint-plugin-better-tailwindcss')).default;
+} catch {
+  betterTailwindcssPlugin = null;
+  // Debug logging for optional dependency failure
+  if (process.env.DEBUG?.includes('eslint') || process.env.DEBUG === '*') {
+    console.debug(
+      '[ESLint Config] Optional dependency "eslint-plugin-better-tailwindcss" not found. '
+        + 'Tailwind class wrapping, ordering, and canonicalization rules will be disabled. '
+        + 'Install it with: npm install --save-dev eslint-plugin-better-tailwindcss'
+    );
+  }
+}
+
+let tailwindCssEslintPlugin = null;
+try {
+  tailwindCssEslintPlugin = (await import('eslint-plugin-tailwindcss')).default;
+} catch {
+  tailwindCssEslintPlugin = null;
+  // Debug logging for optional dependency failure
+  if (process.env.DEBUG?.includes('eslint') || process.env.DEBUG === '*') {
+    console.debug(
+      '[ESLint Config] Optional dependency "eslint-plugin-tailwindcss" not found. '
+        + 'Arbitrary value scale replacement will be disabled. '
+        + 'Install it with: npm install --save-dev eslint-plugin-tailwindcss'
+    );
+  }
+}
+
+/**
+ * Indicates whether the consumer Prettier config enables the Tailwind
+ * Prettier plugin. When present, class ordering and line wrapping belong to
+ * the formatter, and enforcing them here too would cause circular fixes.
+ *
+ * @type {boolean}
+ */
+let prettierTailwindPluginDetected = false;
+try {
+  const prettierModule = await import('prettier');
+  const resolvedPrettierConfig = await prettierModule.resolveConfig(path.join(process.cwd(), 'package.json'));
+  prettierTailwindPluginDetected = Boolean(
+    Array.isArray(resolvedPrettierConfig?.plugins)
+    && resolvedPrettierConfig.plugins.includes('prettier-plugin-tailwindcss')
+  );
+  if (prettierTailwindPluginDetected && (process.env.DEBUG?.includes('eslint') || process.env.DEBUG === '*')) {
+    console.debug(
+      '[ESLint Config] Detected "prettier-plugin-tailwindcss" in the consumer Prettier config. '
+        + 'Class ordering and line wrapping rules are left to Prettier.'
+    );
+  }
+} catch {
+  // Detection is best-effort; without a resolvable config, lint rules stay active.
+}
+
+/**
+ * Candidate paths probed (relative to the consumer project root) for the main
+ * Tailwind CSS v4 entry stylesheet used for theme resolution.
+ *
+ * @type {string[]}
+ */
+const TAILWIND_ENTRY_POINT_CANDIDATES = [
+  'src/app/globals.css',
+  'app/globals.css',
+  'src/styles/globals.css',
+  'styles/globals.css',
+  'src/input.css',
+  'input.css',
+];
+
+/**
+ * Returns centrally-registered Tailwind plugins that are installed in the
+ * consuming project. Missing plugins are omitted so ESLint does not fail on
+ * unresolved plugin definitions.
+ *
+ * @returns {object} Map of plugin names to plugin objects (may be empty).
+ */
+export const getTailwindCentralPlugins = () => ({
+  ...(betterTailwindcssPlugin && { 'better-tailwindcss': betterTailwindcssPlugin }),
+  ...(tailwindCssEslintPlugin && { tailwindcss: tailwindCssEslintPlugin }),
+});
+
+/**
+ * Resolves the Tailwind CSS entry stylesheet used for theme resolution by
+ * probing known locations relative to the project root.
+ *
+ * @returns {string|null} Relative entry point path, or null when none exists.
+ */
+export const resolveTailwindEntryPoint = () =>
+  TAILWIND_ENTRY_POINT_CANDIDATES.find((candidate) => existsSync(path.resolve(process.cwd(), candidate))) ?? null;
+
+/**
+ * Creates shared settings consumed by the Tailwind ESLint plugins. Returns an
+ * empty object when no entry stylesheet is found so plugins fall back to their
+ * own discovery. Users can override any value through `options.settings`.
+ *
+ * @returns {object} Tailwind-related ESLint shared settings.
+ */
+export const tailwindSettings = () => {
+  const entryPoint = resolveTailwindEntryPoint();
+
+  if (!entryPoint) {
+    return {};
+  }
+
+  return { tailwindcss: { cssConfigPath: entryPoint }, 'better-tailwindcss': { entryPoint } };
+};
+
+/**
+ * Creates Tailwind class rules covering canonical class names, whitespace,
+ * ordering, line wrapping, and arbitrary value scale replacement. Rules rely
+ * on plugins registered separately via `getTailwindCentralPlugins`. When the
+ * consumer enables `prettier-plugin-tailwindcss`, ordering and wrapping are
+ * omitted so the formatter owns those concerns without circular fixes.
+ *
+ * @returns {object} Tailwind-related ESLint rules (may be partial when plugins are missing).
+ */
+export const tailwindRules = () => {
+  if (!betterTailwindcssPlugin) {
+    return {};
+  }
+
+  return {
+    // Convert classes to their canonical form (e.g. `aspect-[3/4]` to `aspect-3/4`).
+    'better-tailwindcss/enforce-canonical-classes': 'warn',
+
+    // Collapse redundant whitespace inside class strings.
+    'better-tailwindcss/no-unnecessary-whitespace': 'warn',
+
+    // Enforce consistent class ordering inside class strings. Skipped when
+    // prettier-plugin-tailwindcss already sorts classes during formatting.
+    ...(prettierTailwindPluginDetected ? {} : { 'better-tailwindcss/enforce-consistent-class-order': 'warn' }),
+
+    // Wrap long class strings into readable multi-line groups. Skipped when
+    // prettier-plugin-tailwindcss already wraps classes during formatting.
+    ...(prettierTailwindPluginDetected
+      ? {}
+      : { 'better-tailwindcss/enforce-consistent-line-wrapping': ['warn', { printWidth: PRETTIER.BASE.printWidth }] }),
+
+    // Replace arbitrary values with matching theme scale utilities (e.g. `p-[16px]` to `p-4`).
+    ...(tailwindCssEslintPlugin && { 'tailwindcss/no-unnecessary-arbitrary-value': 'warn' }),
+  };
+};
+
 /**
  * JSDoc rules that enforce documentation presence on public/exported APIs.
  * Covers `@param`, `@returns`, `@throws`, `@description`, and `@property-description`.
@@ -145,11 +299,12 @@ const importOrderRules = (importOrder = true) =>
  * @param {boolean} [options.importOrder] - Enable import order rules.
  * @param {boolean} [options.prettier] - Enable Prettier integration.
  * @param {boolean} [options.jsdoc] - Enable JSDoc rules for public/exported APIs.
+ * @param {boolean} [options.tailwind] - Enable Tailwind CSS class rules.
  *
  * @returns {object} ESLint rules object.
  */
 export const commonRules = (options = {}) => {
-  const { typescript = true, importOrder = true, prettier = true, jsdoc = true } = options;
+  const { typescript = true, importOrder = true, prettier = true, jsdoc = true, tailwind = true } = options;
 
   return {
     // ---- TypeScript Rules ----
@@ -163,5 +318,8 @@ export const commonRules = (options = {}) => {
 
     // ---- JSDoc Integration ----
     ...jsdocRules(jsdoc),
+
+    // ---- Tailwind Integration ----
+    ...(tailwind && tailwindRules()),
   };
 };

package/src/eslint/next.js

@@ -14,7 +14,7 @@ import reactPlugin from 'eslint-plugin-react';
 import reactHooks from 'eslint-plugin-react-hooks';
 import tsEslint from 'typescript-eslint';
 
-import { buildConfig, files } from './lib/index.js';
+import { buildConfig, files, getTailwindCentralPlugins } from './lib/index.js';
 
 /**
  * Removes the next/typescript item from the core-web-vitals config array.
@@ -39,6 +39,7 @@ const prepareNextConfig = (configs) => configs.filter((c) => c.name !== 'next/ty
  * @param {boolean} [options.a11y] - Enable accessibility rules.
  * @param {boolean} [options.importOrder] - Enable import order rules.
  * @param {boolean} [options.jsdoc] - Enable JSDoc rules for public/exported APIs.
+ * @param {boolean} [options.tailwind] - Enable Tailwind CSS class rules (default: true).
  * @param {string[]} [options.ignores] - Additional ignore patterns.
  * @param {object} [options.rules] - Additional or overridden rules.
  * @param {object} [options.settings] - Additional settings.
@@ -51,12 +52,17 @@ const prepareNextConfig = (configs) => configs.filter((c) => c.name !== 'next/ty
  * @returns {import('eslint').Linter.Config[]} ESLint configuration array.
  */
 export const createConfig = (options = {}) => {
-  const { prettier = true, react = true, a11y = true, importOrder = true, jsdoc = true } = options;
+  const { prettier = true, react = true, a11y = true, importOrder = true, jsdoc = true, tailwind = true } = options;
 
   return buildConfig({
     files: [...files.withTs, ...(options.files || [])],
     builtinPlugins: [...prepareNextConfig(nextCoreWebVitals)],
-    centralPlugins: { react: reactPlugin, 'react-hooks': reactHooks, '@typescript-eslint': tsEslint.plugin },
+    centralPlugins: {
+      react: reactPlugin,
+      'react-hooks': reactHooks,
+      '@typescript-eslint': tsEslint.plugin,
+      ...(tailwind && getTailwindCentralPlugins()),
+    },
     parserOptions: { ecmaFeatures: { jsx: true } },
     settings: { react: { version: 'detect' } },
     rules: {
@@ -66,7 +72,7 @@ export const createConfig = (options = {}) => {
       }),
     },
     typescript: true,
-    options: { ...options, prettier, react, a11y, importOrder, jsdoc },
+    options: { ...options, prettier, react, a11y, importOrder, jsdoc, tailwind },
   });
 };
 

package/src/eslint/react.js

@@ -15,7 +15,7 @@ import reactRecommended from 'eslint-plugin-react/configs/recommended.js';
 import reactHooks from 'eslint-plugin-react-hooks';
 import tsEslint from 'typescript-eslint';
 
-import { buildConfig, files } from './lib/index.js';
+import { buildConfig, files, getTailwindCentralPlugins } from './lib/index.js';
 
 /**
  * Creates an ESLint configuration object for React projects with TypeScript
@@ -26,6 +26,7 @@ import { buildConfig, files } from './lib/index.js';
  * @param {boolean} [options.a11y] - Enable accessibility rules.
  * @param {boolean} [options.importOrder] - Enable import order rules.
  * @param {boolean} [options.jsdoc] - Enable JSDoc rules for public/exported APIs.
+ * @param {boolean} [options.tailwind] - Enable Tailwind CSS class rules (default: true).
  * @param {string[]} [options.ignores] - Additional ignore patterns.
  * @param {object} [options.rules] - Additional or overridden rules.
  * @param {object} [options.settings] - Additional settings.
@@ -38,7 +39,7 @@ import { buildConfig, files } from './lib/index.js';
  * @returns {import('eslint').Linter.Config[]} ESLint configuration array.
  */
 export const createConfig = (options = {}) => {
-  const { prettier = true, a11y = true, importOrder = true, jsdoc = true } = options;
+  const { prettier = true, a11y = true, importOrder = true, jsdoc = true, tailwind = true } = options;
 
   return buildConfig({
     files: [...files.withTs, ...(options.files || [])],
@@ -47,7 +48,12 @@ export const createConfig = (options = {}) => {
       { ...reactHooks.configs.flat.recommended, files: [...files.withTs, ...(options.files || [])] },
       ...tsEslint.configs.recommended,
     ],
-    centralPlugins: { react: reactPlugin, 'react-hooks': reactHooks, '@typescript-eslint': tsEslint.plugin },
+    centralPlugins: {
+      react: reactPlugin,
+      'react-hooks': reactHooks,
+      '@typescript-eslint': tsEslint.plugin,
+      ...(tailwind && getTailwindCentralPlugins()),
+    },
     conditionalPlugins: {
       a11y: { ...jsxA11y.flatConfigs.recommended, files: [...files.withTs, ...(options.files || [])] },
     },
@@ -55,7 +61,7 @@ export const createConfig = (options = {}) => {
     settings: { react: { version: 'detect' } },
     rules: { 'react/react-in-jsx-scope': 'off', 'react/no-unknown-property': ['error', { ignore: ['jsx', 'global'] }] },
     typescript: true,
-    options: { ...options, prettier, a11y, importOrder, jsdoc },
+    options: { ...options, prettier, a11y, importOrder, jsdoc, tailwind },
   });
 };
 

package/src/lib/__tests__/config-utils.test.js

@@ -32,6 +32,11 @@ describe('Config Utils', () => {
       const result = mergeDeep({ arr: [1, 2] }, { arr: [3] });
       expect(result).toEqual({ arr: [3] });
     });
+
+    it('should skip non-object sources and initialize missing nested keys', () => {
+      const result = mergeDeep({ a: 1 }, null, { b: { c: 2 } });
+      expect(result).toEqual({ a: 1, b: { c: 2 } });
+    });
   });
 
   describe('filterObjectEntries', () => {

package/src/next-sitemap/__tests__/index.test.js

@@ -82,4 +82,24 @@ describe('next-sitemap/index.js', () => {
     expect(transformed).toContain('User-agent: *');
     expect(transformed).toContain('Allow: /');
   });
+
+  // Test that transform stamps each sitemap entry with changefreq, priority, and lastmod.
+  it('should return loc with metadata in transform', async () => {
+    // Dynamically import the module to test its function.
+    const module = await import('../index.js');
+
+    // Call createSitemapConfig to get default config.
+    const config = module.createSitemapConfig({ siteUrl: 'https://example.com' });
+
+    // Call the transform function with mock data.
+    const transformed = await config.transform(config, '/about/');
+
+    // Verify that the entry location is preserved and defaults are stamped.
+    expect(transformed.loc).toBe('/about/');
+    expect(transformed.changefreq).toBe(config.changefreq);
+    expect(transformed.priority).toBe(config.priority);
+
+    // Verify that lastmod uses ISO format without milliseconds.
+    expect(transformed.lastmod).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);
+  });
 });