JSPM

@toolbox-ts/tseslint

0.1.5
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2
  • Score
    100M100P100Q71350F
  • License MIT

TypeScript ESLint configuration and utilities.

Package Exports

  • @toolbox-ts/tseslint

Readme

@toolbox-ts/tseslint

Coverage Commitizen friendly A comprehensive TypeScript ESLint configuration package that provides opinionated, production-ready ESLint configurations for TypeScript projects with standardized built-in support for different environments (build, development, and test). Supports both single-package and monorepo project structures.

Features

  • 🎯 Environment-specific configurations (build, dev, test)
  • 📦 Built-in TypeScript support with automatic tsconfig detection
  • 🔧 Highly customizable with override capabilities
  • 🌟 Modern ESLint flat config format
  • 🔍 Import resolution with TypeScript and Node.js support
  • 📝 Documentation linting with JSDoc and TSDoc
  • Performance optimized with project service integration

📦 Installation

npm install --save-dev @toolbox-ts/tseslint
# or
pnpm add -D @toolbox-ts/tseslint
# or
yarn add --dev @toolbox-ts/tseslint

The following peerDependencies are required:

  • eslint
  • @eslint/js
  • eslint-config-prettier
  • eslint-import-resolver-typescript
  • eslint-plugin-import
  • eslint-plugin-jsdoc
  • eslint-plugin-tsdoc
  • typescript
  • typescript-eslint
  • eslint-plugin-perfectionist
  • eslint-plugin-unicorn
  • @vitest/eslint-plugin
  • **jiti — only required if your eslint config is in TypeScript.

Installation by Package Manager

pnpm: Choose one of the following methods:

  • Execute pnpm config set auto-install-peers true to automatically install peer dependencies
  • Add auto-install-peers=true in your project's root .npmrc file
  • Manual installation:
pnpm i -D - eslint @eslint/js eslint-config-prettier eslint-import-resolver-typescript eslint-plugin-import eslint-plugin-jsdoc eslint-plugin-tsdoc typescript typescript-eslint eslint-plugin-perfectionist eslint-plugin-unicorn @vitest/eslint-plugin
# Add jiti if using eslint.config.ts
pnpm i -D jiti

npm: Peer dependencies are automatically installed since v7.

yarn: Peer dependencies must be installed manually:

yarn add --dev eslint @eslint/js eslint-config-prettier eslint-import-resolver-typescript eslint-plugin-import eslint-plugin-jsdoc eslint-plugin-tsdoc typescript typescript-eslint eslint-plugin-perfectionist eslint-plugin-unicorn @vitest/eslint-plugin
# Add jiti if using eslint.config.ts
yarn add --dev jiti

🚀 Quick Start

  • Ensure you have at minimum the following tsconfigs: tsconfig.build.json,tsconfig.dev.json,tsconfig.test.json
  • Create an eslint.config.{js|ts} file in your project root:
import { defineConfig } from '@toolbox-ts/tseslint';

export default defineConfig();

That's it! This will automatically configure ESLint for your TypeScript project with three environments:

  • Build: Production source code (src/**/*.{ts,tsx,js,jsx})
  • Dev: Development tools and config files (dev/**/*, tools/**/*, *.{ts,js})
  • Test: Test files (**/*.{test,spec,bench}.{ts,tsx,js,jsx})

🔨 Configuration

Default Configurations

The package provides three pre-configured environments:

name tsconfig includes excludes description
build `tsconfig.build.json [src, packages, apps, bin] directories test files Production source code with strict linting
dev `tsconfig.dev.json [dev, _dev, tools, _tools] directories and root config files test files Development tools and root configuration files
test `tsconfig.test.json [ *.{test,spec,bench}.*] all non-test files Relaxed rules for testing

Custom Configuration

Overriding Default Configurations

import { defineConfig } from '@toolbox-ts/tseslint';

export default defineConfig({
  defaults: {
    // Disable build configuration
    build: false,

    // Customize dev configuration
    dev: { files: ['custom-dev/**/*.ts'], rules: { 'no-console': 'warn' } },

    // Customize test configuration
    test: {
      ignores: ['**/*.integration.test.ts'],
      rules: { '@typescript-eslint/no-explicit-any': 'error' }
    }
  }
});

Adding Custom Configurations

import { defineConfig } from '@toolbox-ts/tseslint';

export default defineConfig({
  custom: {
    integration: {
      base: {
        name: 'integration',
        files: ['tests/integration/**/*.ts'],
        ignores: [],
        importResolverNodeExtensions: ['ts', 'js'],
        rules: { '@typescript-eslint/no-floating-promises': 'error' }
      },
      cfg: { files: ['additional/files/**/*.ts'] }
    }
  }
});

Advanced Usage

Manual Configuration with Create Function

For advanced use cases, you can use the lower-level create function:

import { create, configs } from '@toolbox-ts/tseslint';

const customConfig = create({
  base: configs.build,
  cfg: { files: ['custom/**/*.ts'], rules: { 'prefer-const': 'error' } }
});

Custom Base Configuration

You can also create your own base level configs at the lowest level using createBaseConfig

import { createBaseConfig } from '@toolbox-ts/tseslint';

const customBase = createBaseConfig('api', {
  files: ['api/**/*.ts'],
  rules: { '@typescript-eslint/explicit-function-return-type': 'error' }
});

🔎 TypeScript Configuration Detection

The package automatically detects TypeScript configuration files using the pattern:

  • tsconfig.json (for empty config names)
  • tsconfig.{configName}.json | override if provided (for named configurations)

The getTsconfigPath utility searches for these files starting from the current working directory and traversing up the directory tree.

⚙️ Built-in Rules and Plugins

For rule overrides see the rules definition file

Included Plugins

  • @typescript-eslint: Comprehensive TypeScript linting
  • eslint-plugin-import: Import/export validation and optimization
  • eslint-plugin-unicorn: Modern JavaScript/TypeScript best practices
  • eslint-plugin-perfectionist: Code organization and sorting
  • eslint-plugin-jsdoc: JSDoc validation
  • eslint-plugin-tsdoc: TSDoc validation
  • @vitest/eslint-plugin: Vitest testing framework support
  • eslint-config-prettier: Prettier integration

📖 API Reference

defineConfig(options?)

Main configuration function that creates a complete ESLint flat config.

Parameters:

  • options.defaults: Control default configurations (boolean or per-config overrides)
  • options.custom: Add custom configurations

Returns: ESLint flat config array

create(input)

Lower-level function to create individual configurations.

Parameters:

  • input.base: Base configuration object
  • input.cfg: Optional configuration overrides

getTsconfigPath(filename, start?)

Utility to locate TypeScript configuration files.

Parameters:

  • filename: TSConfig filename to search for
  • start: Starting directory (defaults to process.cwd())

Returns: Absolute path to the configuration file

createBaseConfig(name, config)

Utility primarily for internal use, to create base configurations.

Parameters:

  • name: Name of the configuration
  • config: The base configuration shape

Returns: Resolved BaseCfg

Configuration Types

The package exports comprehensive TypeScript types for all configuration options:

  • BaseCfg<N>: Base configuration interface
  • CfgInput<N>: Configuration override interface
  • ProcessedCfg<N>: Final processed configuration
  • DefineConfigInput: Main configuration input interface

🤝 Contributing

This package is part of the @toolbox-ts monorepo. See the main repository for contribution guidelines.

⚖️ License

MIT – © 2025 Nolan Gajdascz GitHub | NPM