Package Exports
- @toolbox-ts/tseslint
Readme
@toolbox-ts/tseslint
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 objectinput.cfg
: Optional configuration overrides
getTsconfigPath(filename, start?)
Utility to locate TypeScript configuration files.
Parameters:
filename
: TSConfig filename to search forstart
: Starting directory (defaults toprocess.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 configurationconfig
: The base configuration shape
Returns: Resolved BaseCfg
Configuration Types
The package exports comprehensive TypeScript types for all configuration options:
BaseCfg<N>
: Base configuration interfaceCfgInput<N>
: Configuration override interfaceProcessedCfg<N>
: Final processed configurationDefineConfigInput
: 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