directory-lint

2.0.3 verified Fri May 01 auth: no javascript

A TypeScript-first library for validating and generating directory structures based on schema definitions. Current stable version is 2.0.3, with a regular release cadence. Key differentiators include zero dependencies, full TypeScript support, pattern matching with wildcards and regex, and a pluggable backend system. It supports two schema types: ValidateSchema for checking existing structures and GenerateSchema for creating them. Unlike similar tools, it focuses on schema-driven, programmatic validation rather than config-file-based linting, making it suitable for integration into build pipelines or scaffolding tools.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module not supported ↓

cause Package is ESM-only; using require() in CommonJS context.

fix

Use import statement or dynamic import('directory-lint') instead of require().

error TypeError: (0 , directory_lint.DirectoryLint) is not a constructor ↓

cause Default export incorrectly imported; must import named export.

fix

Use 'import { DirectoryLint } from "directory-lint"' instead of default import.

error TS2305: Module '"directory-lint"' has no exported member 'ValidateSchema' ↓

cause Using import instead of import type for a type-only export.

fix

Use 'import type { ValidateSchema } from "directory-lint"'.

Warnings

breaking Constructor now requires no arguments; instantiate with 'new DirectoryLint()' ↓

fix Remove any previously passed options; use validate/generate options instead.

breaking Dropped CommonJS support — package is ESM-only ↓

fix Switch to ES modules or use dynamic import() if you must use CommonJS.

breaking Renamed 'lint' method to 'validate'; 'generate' method added ↓

fix Replace all calls to .lint() with .validate().

deprecated Backend option 'fs' is no longer needed; use default file system backend ↓

fix Remove custom backend option; the library now includes a built-in filesystem backend.

gotcha Schema keys are case-sensitive; file names must match exactly unless using patterns ↓

fix Ensure case matches filesystem. For case-insensitive matching, use regex patterns.

gotcha The 'validate' function expects an absolute or relative path with proper basePath ↓

fix Provide correct base path; the library does not resolve relative to cwd automatically.

Install

npm install directory-lint

yarn add directory-lint

pnpm add directory-lint

Imports

DirectoryLint

wrong

const DirectoryLint = require('directory-lint')

correct

import { DirectoryLint } from 'directory-lint'

ESM-only; CommonJS require will fail. Use TypeScript or ES modules.

ValidateSchema

wrong

import { ValidateSchema } from 'directory-lint'

correct

import type { ValidateSchema } from 'directory-lint'

ValidateSchema is a type, not a runtime value. Use 'import type' for TypeScript.

GenerateSchema

wrong

import { GenerateSchema } from 'directory-lint'

correct

import type { GenerateSchema } from 'directory-lint'

GenerateSchema is a type, not a runtime value. Use 'import type' for TypeScript.

Quickstart

Shows how to validate a directory structure against a schema using DirectoryLint.validate() with ignore patterns.

import { DirectoryLint } from 'directory-lint';
import type { ValidateSchema } from 'directory-lint';

const schema: ValidateSchema = {
  'src': {
    type: 'directory',
    required: true,
    children: {
      'index.ts': { type: 'file', required: true },
      'components': { type: 'directory', required: false }
    }
  },
  'package.json': { type: 'file', required: true }
};

const linter = new DirectoryLint();
const result = await linter.validate('./my-project', schema, { ignore: ['node_modules', '.git'] });
console.log('Valid:', result.valid, 'Errors:', result.errors);