@baseplate-dev/tools 0.5.2 → 0.6.0

package/eslint-configs/react.js

@@ -4,94 +4,138 @@
  * @typedef {import('./typescript.js').GenerateTypescriptEslintConfigOptions} GenerateTypescriptEslintConfigOptions
  */
 
+/**
+ * @typedef {Object} GenerateReactEslintConfigOptions
+ * @property {string | null} [tailwindEntryPoint] - Absolute path to Tailwind CSS entry file (e.g., path.join(import.meta.dirname, 'src/styles.css')). Pass null to disable Tailwind linting.
+ */
+
+import eslintPluginBetterTailwindcss from 'eslint-plugin-better-tailwindcss';
 import eslintPluginImportX from 'eslint-plugin-import-x';
 import reactJsxA11yPlugin from 'eslint-plugin-jsx-a11y';
 import reactPlugin from 'eslint-plugin-react';
 import reactHooksPlugin from 'eslint-plugin-react-hooks';
+import { defineConfig } from 'eslint/config';
 import globals from 'globals';
-import tsEslint from 'typescript-eslint';
 
 /** @type {GenerateTypescriptEslintConfigOptions} */
 export const reactTypescriptEslintOptions = {
   extraDefaultProjectFiles: [],
 };
 
-export const reactEslintConfig = tsEslint.config(
-  // React & A11y
-  {
-    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
-    languageOptions: {
-      globals: { ...globals.browser },
-    },
-    extends: [
-      reactPlugin.configs.flat?.recommended,
-      reactPlugin.configs.flat?.['jsx-runtime'],
-      reactJsxA11yPlugin.flatConfigs.recommended,
-    ],
-    settings: {
-      react: {
-        version: 'detect',
+/**
+ * Generates a React ESLint configuration
+ * @param {GenerateReactEslintConfigOptions} options - Configuration options
+ */
+export function generateReactEslintConfig(options) {
+  return defineConfig(
+    // React & A11y
+    {
+      files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
+      languageOptions: {
+        globals: { ...globals.browser },
       },
-    },
-  },
-
-  // Typescript
-  {
-    files: ['**/*.{tsx,mtsx}'],
-    rules: {
-      // Allow promises to be returned from functions for attributes in React
-      // to allow for React Hook Form handleSubmit to work as expected
-      // See https://github.com/orgs/react-hook-form/discussions/8020
-      '@typescript-eslint/no-misused-promises': [
-        'error',
-        { checksVoidReturn: { attributes: false } },
+      extends: [
+        reactPlugin.configs.flat?.recommended,
+        reactPlugin.configs.flat?.['jsx-runtime'],
+        reactJsxA11yPlugin.flatConfigs.recommended,
       ],
-      // Allow floating navigate from useNavigate to be handled by the router
-      '@typescript-eslint/no-floating-promises': [
-        'error',
-        {
-          allowForKnownSafeCalls: ['UseNavigateResult'],
+      settings: {
+        react: {
+          version: 'detect',
         },
-      ],
+      },
+    },
+
+    // Typescript
+    {
+      files: ['**/*.{tsx,mtsx}'],
+      rules: {
+        // Allow promises to be returned from functions for attributes in React
+        // to allow for React Hook Form handleSubmit to work as expected
+        // See https://github.com/orgs/react-hook-form/discussions/8020
+        '@typescript-eslint/no-misused-promises': [
+          'error',
+          { checksVoidReturn: { attributes: false } },
+        ],
+        // Allow floating navigate from useNavigate to be handled by the router
+        '@typescript-eslint/no-floating-promises': [
+          'error',
+          {
+            allowForKnownSafeCalls: ['UseNavigateResult'],
+          },
+        ],
+      },
     },
-  },
 
-  // React Hooks
-  reactHooksPlugin.configs.flat['recommended-latest'],
-  {
-    rules: {
-      // Disable new strict rules from react-hooks v7 until we enable React Compiler
-      'react-hooks/refs': 'off',
-      'react-hooks/set-state-in-effect': 'off',
-      'react-hooks/preserve-manual-memoization': 'off',
-      'react-hooks/incompatible-library': 'off',
+    // React Hooks
+    reactHooksPlugin.configs.flat['recommended-latest'],
+    {
+      rules: {
+        // Disable new strict rules from react-hooks v7 until we enable React Compiler
+        'react-hooks/refs': 'off',
+        'react-hooks/set-state-in-effect': 'off',
+        'react-hooks/preserve-manual-memoization': 'off',
+        'react-hooks/incompatible-library': 'off',
+      },
     },
-  },
 
-  // Import-X
-  eslintPluginImportX.flatConfigs.react,
+    // Import-X
+    // @ts-ignore - bug with incompatible types between @types/eslint and typescript eslint config - https://github.com/un-ts/eslint-plugin-import-x/issues/421
+    eslintPluginImportX.flatConfigs.react,
 
-  // Unicorn
-  {
-    rules: {
-      // Support kebab case with - prefix to support ignored files in routes and $ prefix for Tanstack camelCase files
-      'unicorn/filename-case': [
-        'error',
-        {
-          cases: {
-            kebabCase: true,
+    // Better Tailwindcss - correctness rules only (formatting handled by Prettier)
+    // Only enable if tailwindEntryPoint is provided (not null/undefined)
+    ...(options.tailwindEntryPoint !== null &&
+    options.tailwindEntryPoint !== undefined
+      ? [
+          eslintPluginBetterTailwindcss.configs['correctness'],
+          {
+            settings: {
+              'better-tailwindcss': {
+                entryPoint: options.tailwindEntryPoint,
+              },
+            },
           },
-          ignore: [
-            String.raw`^-[a-z0-9\-\.]+$`,
-            String.raw`^\$[a-zA-Z0-9\.]+$`,
-          ],
-        },
-      ],
+          {
+            rules: {
+              // Detect custom component classes defined in @layer components
+              'better-tailwindcss/no-unknown-classes': [
+                'error',
+                {
+                  detectComponentClasses: true,
+                  // Ignore classes used in custom component classes
+                  ignore: [
+                    'toaster', // Sonner library class
+                  ],
+                },
+              ],
+            },
+          },
+        ]
+      : []),
+
+    // Unicorn
+    {
+      rules: {
+        // Support kebab case with - prefix to support ignored files in routes and $ prefix for Tanstack camelCase files
+        'unicorn/filename-case': [
+          'error',
+          {
+            cases: {
+              kebabCase: true,
+            },
+            ignore: [
+              String.raw`^-[a-z0-9\-\.]+$`,
+              String.raw`^\$[a-zA-Z0-9\.]+$`,
+            ],
+          },
+        ],
+      },
     },
-  },
 
-  // Global ignores
-  {
-    ignores: ['**/route-tree.gen.ts'],
-  },
-);
+    // Global ignores
+    {
+      ignores: ['**/route-tree.gen.ts'],
+    },
+  );
+}

package/eslint-configs/storybook.js

@@ -1,25 +1,19 @@
 // @ts-check
 
-/**
- * @typedef {import('./typescript.js').GenerateTypescriptEslintConfigOptions} GenerateTypescriptEslintConfigOptions
- */
-
 import storybook from 'eslint-plugin-storybook';
-import tsEslint from 'typescript-eslint';
+import { defineConfig } from 'eslint/config';
 
-/** @type {GenerateTypescriptEslintConfigOptions} */
-export const storybookTypescriptEslintOptions = {
-  extraDevDependencies: [
-    // allow dev dependencies for Storybook configuration block
-    '.storybook/**/*.{js,ts,tsx,jsx}',
-    // allow dev dependencies for Storybook
-    '**/*.stories.{js,ts,tsx,jsx}',
-    // allow dev dependencies for MDX files
-    '**/*.mdx',
-  ],
-};
+/** @type {string[]} */
+export const storybookTypescriptExtraDevDependencies = [
+  // allow dev dependencies for Storybook configuration block
+  '.storybook/**/*.{js,ts,tsx,jsx}',
+  // allow dev dependencies for Storybook
+  '**/*.stories.{js,ts,tsx,jsx}',
+  // allow dev dependencies for MDX files
+  '**/*.mdx',
+];
 
-export const storybookEslintConfig = tsEslint.config(
+export const storybookEslintConfig = defineConfig(
   // Storybook
   // @ts-ignore -- TypeScript resolution bug where it expects a named export called default
   storybook.configs['flat/recommended'],

package/eslint-configs/typescript.js

@@ -6,6 +6,7 @@ import { importX } from 'eslint-plugin-import-x';
 import perfectionist from 'eslint-plugin-perfectionist';
 import eslintPluginUnicorn from 'eslint-plugin-unicorn';
 import unusedImports from 'eslint-plugin-unused-imports';
+import { defineConfig } from 'eslint/config';
 import globals from 'globals';
 import tsEslint from 'typescript-eslint';
 
@@ -13,6 +14,7 @@ import noUnusedGeneratorDependencies from './rules/no-unused-generator-dependenc
 
 /**
  * @typedef {Object} GenerateTypescriptEslintConfigOptions
+ * @property {string} [rootDir] - Absolute path to tsconfig root directory (for tsconfigRootDir)
  * @property {string[]} [extraTsFileGlobs] - Additional file globs to lint with Typescript
  * @property {string[]} [extraDevDependencies] - Additional globs for dev dependencies
  * @property {string[]} [extraDefaultProjectFiles] - Additional default project files
@@ -23,13 +25,10 @@ const KEEP_UNUSED_IMPORTS =
 
 /**
  * Generates a Typescript ESLint configuration
- * @param {GenerateTypescriptEslintConfigOptions[]} [options=[]] - Configuration options
+ * @param {GenerateTypescriptEslintConfigOptions} [options={}] - Configuration options
  */
-export function generateTypescriptEslintConfig(options = []) {
-  const tsFileGlobs = [
-    '**/*.{ts,tsx}',
-    ...options.flatMap((option) => option.extraTsFileGlobs ?? []),
-  ];
+export function generateTypescriptEslintConfig(options = {}) {
+  const tsFileGlobs = ['**/*.{ts,tsx}', ...(options.extraTsFileGlobs ?? [])];
   const devDependencies = [
     // allow dev dependencies for test files
     '**/*.test-helper.{js,ts,jsx,tsx}',
@@ -42,13 +41,13 @@ export function generateTypescriptEslintConfig(options = []) {
     '*.{js,ts}',
     '.*.{js,ts}',
     '.workspace-meta/**/*',
-    ...options.flatMap((option) => option.extraDevDependencies ?? []),
+    ...(options.extraDevDependencies ?? []),
   ];
   const defaultProjectFiles = [
     'vitest.config.ts',
-    ...options.flatMap((option) => option.extraDefaultProjectFiles ?? []),
+    ...(options.extraDefaultProjectFiles ?? []),
   ];
-  return tsEslint.config(
+  return defineConfig(
     // ESLint Configs for all files
     eslint.configs.recommended,
     {
@@ -82,6 +81,7 @@ export function generateTypescriptEslintConfig(options = []) {
       ],
       languageOptions: {
         parserOptions: {
+          ...(options.rootDir ? { tsconfigRootDir: options.rootDir } : {}),
           projectService: {
             // allow default project for root configs
             allowDefaultProject: defaultProjectFiles,
@@ -162,6 +162,7 @@ export function generateTypescriptEslintConfig(options = []) {
     },
 
     // Import-X Configs
+    // @ts-ignore - bug with incompatible types between @types/eslint and typescript eslint config - https://github.com/un-ts/eslint-plugin-import-x/issues/421
     importX.flatConfigs.recommended,
     importX.flatConfigs.typescript,
     {
@@ -237,6 +238,9 @@ export function generateTypescriptEslintConfig(options = []) {
         // Allow usage of utf-8 text encoding since it's consistent with the WHATWG spec
         // and autofixing can cause unexpected changes (https://github.com/sindresorhus/eslint-plugin-unicorn/issues/1926)
         'unicorn/text-encoding-identifier-case': 'off',
+
+        // This rule can cause performance issues (https://github.com/sindresorhus/eslint-plugin-unicorn/issues/2819)
+        'unicorn/no-unnecessary-polyfills': 'off',
       },
     },
 

package/eslint.config.node.js

@@ -1,25 +1,30 @@
 // @ts-check
 
-import tsEslint from 'typescript-eslint';
+import { defineConfig } from 'eslint/config';
 
 import { prettierEslintConfig } from './eslint-configs/prettier.js';
 import { generateTypescriptEslintConfig } from './eslint-configs/typescript.js';
 
-/** @typedef {import('./eslint-configs/typescript.js').GenerateTypescriptEslintConfigOptions} GenerateTypescriptEslintConfigOptions */
+/**
+ * @typedef {Object} DefineNodeEslintConfigOptions
+ * @property {string} dirname - The import.meta.dirname of the calling package
+ * @property {string[]} [extraDefaultProjectFiles] - Additional default project files
+ * @property {string[]} [ignores] - Additional ignore patterns
+ */
 
 /**
- * Generates a Node.js ESLint configuration with customizable options
- * @param {GenerateTypescriptEslintConfigOptions} [options] - Configuration options
+ * Defines a Node.js ESLint configuration for a package
+ * @param {DefineNodeEslintConfigOptions} options - Configuration options
  */
-export function generateNodeConfig(options = {}) {
-  return tsEslint.config(
-    ...generateTypescriptEslintConfig([
-      {
-        extraDefaultProjectFiles: options.extraDefaultProjectFiles || [],
-      },
-    ]),
+export function defineNodeEslintConfig(options) {
+  const { dirname, extraDefaultProjectFiles = [], ignores = [] } = options;
+
+  return defineConfig(
+    ...generateTypescriptEslintConfig({
+      rootDir: dirname,
+      extraDefaultProjectFiles,
+    }),
     prettierEslintConfig,
+    ...(ignores.length > 0 ? [{ ignores }] : []),
   );
 }
-
-export default generateNodeConfig();

package/eslint.config.react.js

@@ -1,24 +1,51 @@
 // @ts-check
 
-import tsEslint from 'typescript-eslint';
+import { defineConfig } from 'eslint/config';
+import path from 'node:path';
 
 import { prettierEslintConfig } from './eslint-configs/prettier.js';
-import {
-  reactEslintConfig,
-  reactTypescriptEslintOptions,
-} from './eslint-configs/react.js';
+import { generateReactEslintConfig } from './eslint-configs/react.js';
 import {
   storybookEslintConfig,
-  storybookTypescriptEslintOptions,
+  storybookTypescriptExtraDevDependencies,
 } from './eslint-configs/storybook.js';
 import { generateTypescriptEslintConfig } from './eslint-configs/typescript.js';
 
-export default tsEslint.config(
-  ...generateTypescriptEslintConfig([
-    reactTypescriptEslintOptions,
-    storybookTypescriptEslintOptions,
-  ]),
-  ...reactEslintConfig,
-  ...storybookEslintConfig,
-  prettierEslintConfig,
-);
+/**
+ * @typedef {Object} DefineReactEslintConfigOptions
+ * @property {string} dirname - The import.meta.dirname of the calling package
+ * @property {boolean} [includeStorybook=false] - Whether to include Storybook configuration
+ * @property {string | null} [tailwindEntryPoint='src/styles.css'] - Path to Tailwind CSS entry file relative to dirname. Pass null to disable Tailwind linting.
+ * @property {string[]} [ignores] - Additional ignore patterns
+ */
+
+/**
+ * Defines a React ESLint configuration for a package
+ * @param {DefineReactEslintConfigOptions} options - Configuration options
+ */
+export function defineReactEslintConfig(options) {
+  const {
+    dirname,
+    includeStorybook = false,
+    tailwindEntryPoint = 'src/styles.css',
+    ignores = [],
+  } = options;
+
+  const absoluteTailwindPath =
+    tailwindEntryPoint === null ? null : path.join(dirname, tailwindEntryPoint);
+
+  return defineConfig(
+    ...generateTypescriptEslintConfig({
+      rootDir: dirname,
+      extraDevDependencies: includeStorybook
+        ? storybookTypescriptExtraDevDependencies
+        : [],
+    }),
+    ...generateReactEslintConfig({
+      tailwindEntryPoint: absoluteTailwindPath,
+    }),
+    ...(includeStorybook ? storybookEslintConfig : []),
+    prettierEslintConfig,
+    ...(ignores.length > 0 ? [{ ignores }] : []),
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baseplate-dev/tools",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Shared dev configurations for linting, formatting, and testing Baseplate projects",
   "keywords": [
     "development-tools",
@@ -52,9 +52,10 @@
     "@eslint/js": "9.39.2",
     "@tsconfig/node22": "22.0.5",
     "@tsconfig/vite-react": "7.0.2",
-    "@vitest/eslint-plugin": "1.6.6",
+    "@vitest/eslint-plugin": "1.6.9",
     "eslint-config-prettier": "10.1.8",
     "eslint-import-resolver-typescript": "4.4.4",
+    "eslint-plugin-better-tailwindcss": "4.2.0",
     "eslint-plugin-import-x": "4.16.1",
     "eslint-plugin-jsx-a11y": "6.10.2",
     "eslint-plugin-perfectionist": "5.4.0",
@@ -94,7 +95,7 @@
   "scripts": {
     "lint": "eslint .",
     "prettier:check": "prettier --check .",
-    "prettier:write": "prettier -w .",
+    "prettier:write": "prettier -w -l .",
     "typecheck": "tsc --noEmit"
   }
 }

package/prettier.config.node.js

@@ -1,5 +1,5 @@
 // @ts-check
-import { fileURLToPath } from 'node:url';
+import packageJsonPlugin from 'prettier-plugin-packagejson';
 
 /** @type {import("prettier").Config} */
 export default {
@@ -7,10 +7,7 @@ export default {
   singleQuote: true,
   trailingComma: 'all',
   semi: true,
-  plugins: [
-    // workaround for this bug: https://github.com/prettier/prettier-vscode/issues/3641
-    fileURLToPath(import.meta.resolve('prettier-plugin-packagejson')),
-  ],
+  plugins: [packageJsonPlugin],
   // we don't want trailing commas in jsonc files (https://github.com/prettier/prettier/issues/15956)
   overrides: [
     {

package/prettier.config.react.js

@@ -1,4 +1,5 @@
 // @ts-check
+
 import { fileURLToPath } from 'node:url';
 
 import basePrettierConfig from './prettier.config.node.js';
@@ -11,11 +12,13 @@ import basePrettierConfig from './prettier.config.node.js';
 /** @type {import("prettier").Config} */
 export default {
   ...basePrettierConfig,
+  // Tailwind-specific configuration
   tailwindFunctions: ['clsx', 'cn', 'cva'],
   tailwindStylesheet: './src/styles.css',
+  // Plugins must be specified as absolute paths due to Prettier limitations
+  // See: https://github.com/prettier/prettier/issues/8056
   plugins: [
     ...(basePrettierConfig.plugins ?? []),
-    // workaround for this bug: https://github.com/prettier/prettier-vscode/issues/3641
     fileURLToPath(import.meta.resolve('prettier-plugin-tailwindcss')),
   ],
 };