@hyperse/eslint-config-hyperse

🛠 A comprehensive ESLint and Prettier configuration for TypeScript projects, with support for monorepos and ESM. Optimized for Next.js and React applications. ⚡️

Features

• 🎯 TypeScript & JavaScript Linting: Latest standards-based linting for both TypeScript and JavaScript
• 🔧 Multiple Config Presets: Ready-to-use configurations for react, hooks, next, and more
• 📝 Shared TypeScript Config: Pre-configured tsconfig.json for consistent TypeScript settings
• 💅 Prettier Integration: Automatic code formatting with sensible defaults
• ♿️ Accessibility: Built-in rules for JSX accessibility
• 📦 Monorepo Support: Optimized for monorepo setups
• 🔄 Module Support: Full compatibility with both ESM and CommonJS
• 🎨 Tailwind CSS: Built-in support for Tailwind CSS class sorting
• 🔍 SonarJS: Optional integration for code quality rules

Installation & Configuration

Basic Setup

1. Initialize your project (if needed):

   npm init
   

2. Install the ESLint config:

   npm i -D @hyperse/eslint-config-hyperse
   

3. Create ESLint configuration:

   • Create eslint.config.js (or eslint.config.mjs for CommonJS) in your project root
   • Add the base configuration:

   import { base, defineConfig } from '@hyperse/eslint-config-hyperse';
   
   export default defineConfig([
     ...base,
     {
       rules: {
         '@typescript-eslint/no-explicit-any': 'off',
       },
     },
   ]);
   

TypeScript Configuration

Base Configuration (tsconfig.json)

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "extends": "@hyperse/eslint-config-hyperse/tsconfig.base.json",
  "compilerOptions": {
    "baseUrl": "./",
    "rootDir": ".",
    "outDir": "dist",
    "types": ["vitest/globals"],
    "paths": {}
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"]
}

Build Configuration (tsconfig.build.json)

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "baseUrl": "./",
    "incremental": false,
    "paths": {}
  },
  "exclude": ["**/*.stories.tsx", "**/*.stories.mdx", ".storybook/**", "dist"]
}

Available Scripts

Add to your package.json:

{
  "scripts": {
    "lint": "tsc --noEmit && eslint .",
    "lint:fix": "npm run lint -- --fix"
  }
}

Or for JavaScript-only projects:

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "npm run lint -- --fix"
  }
}

Framework-Specific Configurations

Next.js

import { defineConfig, nextjs } from '@hyperse/eslint-config-hyperse';

export default defineConfig([
  ...nextjs,
  {
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
    },
  },
]);

React.js (without Next.js)

import { defineConfig, reactjs } from '@hyperse/eslint-config-hyperse';

export default defineConfig([
  ...reactjs,
  {
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
    },
  },
]);

SonarJS Integration

import { defineConfig, sonarjs } from '@hyperse/eslint-config-hyperse';

export default defineConfig([
  ...sonarjs,
  {
    rules: {
      'sonarjs/fixme-tag': 'warn',
      'sonarjs/todo-tag': 'warn',
    },
  },
]);

VS Code Integration

1. Install the ESLint extension

2. Configure VS Code settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "dbaeumer.vscode-eslint",
  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit",
    "source.organizeImports": "never"
  },
  "[jsonc]": { "editor.formatOnSave": false },
  "[json]": { "editor.formatOnSave": false },
  "eslint.workingDirectories": [
    "./apps/docs",
    "./apps/web",
    "./packages/core",
    "./packages/utils"
  ],
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  },
  "tailwindCSS.classFunctions": ["tw", "clsx", "twMerge", "extendVariants"],
  "tailwindCSS.classAttributes": ["className", "classNames"],
  "tailwindCSS.experimental.configFile": {
    "apps/web/src/app/globals.css": "apps/web/src/**",
    "apps/docs/src/app/globals.css": "apps/docs/src/**"
  }
}

Additional Configuration

Prettier Configuration

Use definePrettierConfig() so Prettier CLI matches ESLint prettier/prettier (base options and prettier-plugin-tailwindcss, with the plugin always last when you add more plugins). The name mirrors this package’s defineConfig helper for ESLint.

Create prettier.config.mjs:

import { definePrettierConfig } from '@hyperse/eslint-config-hyperse';

/**
 * @see https://prettier.io/docs/configuration
 * @see https://github.com/tailwindlabs/prettier-plugin-tailwindcss#installation
 */
export default definePrettierConfig({
  // ...your overrides (e.g. Tailwind v4)
});

Optional slim import (no ESLint stack): @hyperse/eslint-config-hyperse/definePrettierConfig (the legacy path @hyperse/eslint-config-hyperse/getPrettierConfig still resolves to the same module).

The previous name getPrettierConfig remains exported but is deprecated; prefer definePrettierConfig.

Tailwind CSS Integration

Configure Tailwind via definePrettierConfig (paths are resolved relative to this config file):

import { definePrettierConfig } from '@hyperse/eslint-config-hyperse';

export default definePrettierConfig({
  tailwindStylesheet: './src/app/globals.css',
  tailwindFunctions: ['tw', 'clsx', 'twMerge', 'extendVariants'],
  tailwindAttributes: ['className', 'classNames'],
});

Important Notes

• TypeScript settings:
  • isolatedModules: true (default)
  • verbatimModuleSyntax: true (default)
• JSON/JSONC files: VS Code formatting is disabled by default
• React ESLint rules: See source code

Performance Considerations

The following ESLint rules may impact performance during linting/formatting:

• prettier/prettier: Can be slow on large files due to full reformatting
• @typescript-eslint/no-deprecated: Requires type information which increases checking time
• sonarjs/arguments-order: Complex analysis of function argument usage patterns

Consider selectively disabling these rules for specific files if performance becomes an issue.