CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-putout--eslint-flat

Utilities for working with ESLint Flat Config format, providing object-based syntax and monorepo configuration management.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

monorepo-config.mddocs/

Monorepo Configuration Management

Utilities for merging ESLint configurations across multiple directories in monorepos, providing bulk configuration processing and convenient helper functions.

Capabilities

mergeESLintConfigs Function

Merges ESLint configurations from multiple directories in a monorepo structure. Reads all subdirectories within specified directories and combines their configurations into a single flat config array.

/**
 * Merges ESLint configurations from multiple directories
 * @param {string|URL} cwd - Current working directory or file URL
 * @param {string|Array<string>} directories - Directory name(s) to read configs from
 * @param {Object} [options] - Optional override functions { readdir, readESLintConfig }
 * @returns {Promise<Array<Object>>} Promise resolving to flattened array of merged ESLint config objects
 */
async function mergeESLintConfigs(cwd, directories, options);

Parameters:

  • cwd (string|URL): Current working directory or file:// URL
  • directories (string|Array): Single directory name or array of directory names to process
  • options (Object, optional): Override functions for dependency injection
    • readdir (function): Custom directory reading function

Returns: Promise resolving to a flattened array of all merged ESLint configuration objects.

Usage Examples:

Single Directory Processing:

const { mergeESLintConfigs } = require('@putout/eslint-flat');

// Process all packages in ./packages directory
const config = await mergeESLintConfigs(__dirname, 'packages');

// This will:
// 1. Read all subdirectories in ./packages
// 2. Read ESLint config from each subdirectory
// 3. Use matchToFlatDir for each subdirectory
// 4. Flatten all configs into single array

Multiple Directory Processing:

const { mergeESLintConfigs } = require('@putout/eslint-flat');

// Process multiple directory types
const config = await mergeESLintConfigs(__dirname, ['packages', 'tools', 'scripts']);

With File URL (ESM):

import { mergeESLintConfigs } from '@putout/eslint-flat';

const config = await mergeESLintConfigs(import.meta.url, ['packages']);

Complete Monorepo ESLint Configuration:

import { safeAlign } from 'eslint-plugin-putout/config';
import { mergeESLintConfigs } from '@putout/eslint-flat';

const packageConfigs = await mergeESLintConfigs(import.meta.url, ['packages']);

export default [
  ...safeAlign,
  ...packageConfigs,
];

With Custom Options:

const { mergeESLintConfigs } = require('@putout/eslint-flat');
const fs = require('fs/promises');

// Custom directory reading for filtered processing
const customReaddir = async (path) => {
  const items = await fs.readdir(path);
  // Only process directories starting with 'pkg-'
  return items.filter(item => item.startsWith('pkg-'));
};

const config = await mergeESLintConfigs(__dirname, 'packages', {
  readdir: customReaddir,
});

createESLintConfig Function

Convenience function that serves as an alias to ESLint's defineConfig function, providing a cleaner API for creating ESLint configurations.

/**
 * Alias to ESLint's defineConfig function for creating configurations
 * @param {Array<Object>} configs - Array of ESLint configuration objects
 * @returns {Array<Object>} Processed configuration array from ESLint's defineConfig
 */
function createESLintConfig(configs);

Parameters:

  • configs (Array<Object>): Array of ESLint configuration objects to be processed

Returns: Array of ESLint configuration objects processed by ESLint's defineConfig function.

Usage Examples:

Simple Configuration Creation:

const { createESLintConfig } = require('@putout/eslint-flat');
const { safeAlign } = require('eslint-plugin-putout/config');

// Instead of spreading arrays manually
export default createESLintConfig([
  ...safeAlign,
  {
    files: ['**/*.js'],
    rules: {
      'no-console': 'warn',
    },
  },
]);

Compared to Manual Spreading:

// Without createESLintConfig (more verbose)
export default [
  ...safeAlign,
  ...otherConfigs,
  customConfig,
];

// With createESLintConfig (cleaner)
export default createESLintConfig([safeAlign, otherConfigs, customConfig]);

Monorepo Processing Flow

The mergeESLintConfigs function follows this processing flow:

  1. Directory Resolution: Converts cwd to proper directory path (handles file:// URLs)
  2. Directory Reading: Reads all items in each specified directory
  3. Subdirectory Processing: For each subdirectory found:
    • Reads ESLint configuration using internal readESLintConfig
    • Applies matchToFlatDir to process and prefix file patterns
  4. Flattening: Combines all configuration arrays into single flat array

Directory Structure Example

my-monorepo/
├── packages/
│   ├── package-a/
│   │   └── eslint.config.js
│   ├── package-b/
│   │   └── eslint.config.js
│   └── package-c/
│       └── .eslintrc.json
└── tools/
    ├── build-tool/
    │   └── eslint.config.js
    └── dev-tool/
        └── eslint.config.js

Configuration:

const config = await mergeESLintConfigs(__dirname, ['packages', 'tools']);
// Processes: package-a, package-b, package-c, build-tool, dev-tool
// Returns: Single flattened array with all configurations

Error Handling

  • Gracefully handles missing directories (skips them)
  • Uses try-catch internally for file operations
  • Empty configurations return empty arrays rather than errors
  • Supports dependency injection for testing and custom behavior

Performance Considerations

  • Processes directories in parallel using Promise.all
  • Reads configurations asynchronously
  • Flattens results efficiently using Array.flat()
  • Suitable for large monorepos with many packages

Install with Tessl CLI

npx tessl i tessl/npm-putout--eslint-flat

docs

directory-config.md

index.md

monorepo-config.md

transformation.md

tile.json