js-style-kit

A zero-configuration style guide for ESLint and Prettier that provides sensible default settings and flexible configuration options.

Features

• ✅ Batteries included - ESLint, Prettier, and all plugins bundled (no peer dependency headaches)
• ✅ ESLint v9 flat config format
• ✅ TypeScript first with automatic project detection
• ✅ Framework support - React, Next.js, Vite, Remix, React Router
• ✅ Auto-sorting - Imports, objects, properties, and more
• ✅ Smart defaults - All rules configured as warnings (not errors)
• ✅ Highly configurable - Enable only what you need, what you don't use is left out of the config for efficiency
• ✅ ESM-only - For modern JavaScript projects

Requirements

• Node.js v20.11.0 or higher

Installation

npm install js-style-kit --save-dev
# or
yarn add js-style-kit --dev
# or
pnpm add js-style-kit --save-dev
# or
bun add js-style-kit --dev

Quick Start

Option 1: CLI (Recommended)

The fastest way to get started is with our CLI tool:

npx js-style-kit init

This will:

1. Install dependencies
2. Create style-kit.config.js, eslint.config.js, and prettier.config.js
3. Add npm scripts to your package.json
4. Configure VS Code settings

→ Learn more about the CLI

Option 2: Manual Setup

ESLint

Create eslint.config.js (or eslint.config.mjs if not using "type": "module"):

// @ts-check
import { eslintConfig } from "js-style-kit";

export default eslintConfig();

Add scripts to package.json:

{
  "scripts": {
    "lint": "eslint . --max-warnings=0 --cache",
    "lint:fix": "eslint . --fix --max-warnings=0 --cache"
  }
}

Note: The --max-warnings=0 flag is important since all rules are warnings by default.

Prettier

Create prettier.config.js (or prettier.config.mjs if not using "type": "module"):

// @ts-check
import { prettierConfig } from "js-style-kit";

export default prettierConfig();

Add scripts to package.json:

{
  "scripts": {
    "format": "prettier . --write --cache",
    "format:check": "prettier . --check --cache"
  }
}

Tip: For faster formatting, you can add the --experimental-cli flag to your format commands (e.g., prettier . --write --cache --experimental-cli). This uses Prettier's experimental CLI which can provide significant performance improvements. If you experience any issues, simply remove the flag.

Configuration

ESLint Options

import { eslintConfig } from "js-style-kit";

export default eslintConfig(
  {
    // Core options
    typescript: true, // Boolean or path to tsconfig.json
    react: false, // React support (see React config docs)
    functionStyle: "arrow", // "arrow" | "declaration" | "expression" | "off"

    // Plugin toggles
    importPlugin: true, // Import/export validation
    sorting: true, // Auto-sort imports, objects, etc.
    unicorn: true, // Enforce file naming and best practices
    // or configure filename case:
    // unicorn: { filenameCase: "kebabCase" }, // "camelCase" | "kebabCase" | "pascalCase" | "snakeCase"
    jsdoc: { requireJsdoc: false }, // JSDoc validation

    // Framework & tools
    query: false, // TanStack Query rules
    testing: { framework: "vitest" }, // Test framework config
    storybook: false, // Storybook rules
    turbo: false, // Turborepo rules
    convex: false, // Convex backend rules

    // Advanced
    ignores: [], // Additional ignore patterns
    rules: {}, // Custom rule overrides
  },
  // Additional ESLint config objects
  {
    name: "custom-globals",
    languageOptions: {
      globals: {
        process: "readonly",
      },
    },
  },
);

Configuration Guides

Each configuration has detailed documentation:

• Core Configs

  • Base ESLint Rules
  • TypeScript
  • Sorting (Perfectionist)
  • Import Plugin
  • Unicorn

• Framework Configs

  • React - React, hooks, compiler, and refresh support
  • TanStack Query - Query best practices

• Tool Configs

  • Testing - Vitest, Jest, Bun, Node
  • JSDoc - Documentation validation
  • Storybook - Component story rules
  • Turborepo - Monorepo rules
  • Convex - Convex backend rules

Prettier Options

import { prettierConfig } from "js-style-kit";

export default prettierConfig({
  // Plugin options
  cssOrderPlugin: true, // Sort CSS properties
  curlyPlugin: true, // Enforce curly braces
  jsonSortPlugin: true, // Sort JSON keys
  packageJsonPlugin: true, // Sort package.json
  tailwindPlugin: false, // Boolean, path to global css file, or config object
  parser: "oxc", // "oxc" (faster) or "default"

  // Standard Prettier options
  printWidth: 80,
  tabWidth: 2,
  // ... any Prettier option
});

→ Full Prettier documentation

Framework Examples

React with Next.js

import { eslintConfig } from "js-style-kit";

export default eslintConfig({
  typescript: "./tsconfig.json",
  react: {
    framework: "next",
    reactCompiler: true, // React 19 compiler rules (enabled by default)
  },
  testing: {
    framework: "vitest",
    itOrTest: "it",
  },
});

React with Vite

import { eslintConfig } from "js-style-kit";

export default eslintConfig({
  react: {
    framework: "vite",
    reactRefresh: true, // Fast Refresh validation (enabled by default with vite)
  },
  testing: { framework: "vitest" },
});

TypeScript Library

import { eslintConfig } from "js-style-kit";

export default eslintConfig({
  typescript: "./tsconfig.json",
  jsdoc: { requireJsdoc: true }, // Enforce JSDoc for public APIs
  testing: { framework: "bun" },
});

Adding Custom Rules

You can override any rule or add custom configurations. If you disable a rule in the rules object, it will be removed from the config for efficiency.

import { eslintConfig } from "js-style-kit";

export default eslintConfig(
  {
    typescript: true,
    react: true,
    rules: {
      // Override built-in rules
      "no-console": ["error", { allow: ["warn", "error"] }],
      "@typescript-eslint/no-explicit-any": "off",
    },
  },
  // Additional ESLint config objects
  {
    name: "custom-globals",
    languageOptions: {
      globals: {
        process: "readonly",
      },
    },
  },
);

What's Included

ESLint Plugins

• typescript-eslint - TypeScript linting
• eslint-plugin-perfectionist - Auto-sorting
• eslint-plugin-import-x - Import/export validation
• eslint-plugin-unicorn - Best practices & naming
• eslint-plugin-react - React rules
• eslint-plugin-react-hooks - React hooks rules
• eslint-plugin-react-refresh - Fast Refresh validation
• eslint-plugin-nextjs - My fork of the Next.js plugin
• @tanstack/eslint-plugin-query - TanStack Query rules
• eslint-plugin-jsdoc - JSDoc validation
• eslint-plugin-storybook - Storybook rules
• eslint-plugin-turbo - Turborepo rules
• eslint-plugin-vitest - Vitest rules
• eslint-plugin-jest - Jest rules
• @convex-dev/eslint-plugin - Convex backend rules

Prettier Plugins

• prettier-plugin-css-order - CSS property ordering
• prettier-plugin-curly - Curly brace enforcement
• prettier-plugin-packagejson - package.json sorting
• prettier-plugin-sort-json - JSON sorting
• prettier-plugin-tailwindcss - Tailwind class sorting
• @prettier/plugin-oxc - Faster parser (optional)

License

MIT

Note: This is a work in progress. Please open an issue if you have suggestions or find any problems!