Configuration

This guide will help you configure DeepLint for your project.

This is part of the Getting Started series:

1. Installation

2. Configuration (current page)

3. First Run

4. Git Integration

Initialization

The easiest way to configure DeepLint is to use the initialization command:

deeplint init

This command will:

1. Create a configuration file in your project root

2. Set up default configuration options

3. Detect whether your project is using ESM or CJS and create the appropriate file format

By default, the init command will detect your project's module format and create the appropriate configuration file:

• For ESM projects (with "type": "module" in package.json): deeplint.config.js with ESM syntax

• For CJS projects: deeplint.config.js or deeplint.config.cjs with CJS syntax

You can also specify the format you want to use:

JavaScript (CJS)

deeplint init --cjs

This will create a deeplint.config.js or deeplint.config.cjs file with CommonJS syntax.

JavaScript (ESM)

deeplint init --esm

This will create a deeplint.config.js or deeplint.config.mjs file with ECMAScript Modules syntax.

YAML

deeplint init --yaml

This will create a .deeplintrc.yml file.

JSON

deeplint init --json

This will create a .deeplintrc.json file.

Configuration File Locations

DeepLint uses cosmiconfig to find your configuration file. It will look for configuration in the following places (in order of precedence):

1. package.json with a "deeplint" property

2. .deeplintrc file (no extension) in JSON or YAML format

3. .deeplintrc.json, .deeplintrc.yaml, .deeplintrc.yml, .deeplintrc.js, .deeplintrc.cjs, or .deeplintrc.mjs file

4. deeplint.config.js, deeplint.config.cjs, deeplint.config.mjs, or deeplint.config.ts file

5. Any of the above in a .config subdirectory

This flexible configuration system allows you to use the format and location that best fits your project structure.

Configuration File

The configuration file contains settings for DeepLint's behavior. Here are examples for both ESM and CJS:

CJS (deeplint.config.js)

// For CJS projects
const { defineConfig } = require("deeplint-cli");

module.exports = defineConfig({
  // Context builder configuration
  contextBuilder: {
    // Maximum number of tokens to use for the context
    maxTokens: 8000,

    // Maximum number of tokens to use per file
    tokensPerFile: 1000,

    // Maximum file size in KB to include in the context
    maxFileSize: 500,

    // Whether to include dependencies in the context
    includeDependencies: true,

    // Whether to include code structure in the context
    includeStructure: true,
  },

  // File filtering configuration
  files: {
    // Patterns to include in the analysis
    include: ["**/*.js", "**/*.ts", "**/*.jsx", "**/*.tsx"],

    // Patterns to exclude from the analysis
    exclude: ["node_modules/**", "dist/**", "build/**"],

    // Whether to use .gitignore for file filtering
    useGitignore: true,
  },

  // Git integration configuration
  git: {
    // Whether to include unstaged changes in the analysis
    includeUnstaged: false,
  },

  // Logging configuration
  logging: {
    // Log level: "debug", "info", "success", "warn", "error", "none"
    level: "info",
  },

  // LLM configuration
  llm: {
    // LLM provider to use (currently only "openai" is supported)
    provider: "openai",

    // API key for the provider (optional, can use OPENAI_API_KEY env var)
    apiKey: "sk-...",

    // Model to use (optional, can use OPENAI_MODEL env var, default: "gpt-4o")
    model: "gpt-4o",

    // Maximum number of tokens to use for the analysis
    maxTokens: 16384,
  },

  // Additional files to ignore (deprecated, use files.exclude instead)
  ignore: ["node_modules", "dist", "build"],
});

ESM (deeplint.config.js)

// For ESM projects (with "type": "module" in package.json)
import { defineConfig } from "deeplint-cli";

export default defineConfig({
  // Context builder configuration
  contextBuilder: {
    // Maximum number of tokens to use for the context
    maxTokens: 8000,

    // Maximum number of tokens to use per file
    tokensPerFile: 1000,

    // Maximum file size in KB to include in the context
    maxFileSize: 500,

    // Whether to include dependencies in the context
    includeDependencies: true,

    // Whether to include code structure in the context
    includeStructure: true,
  },

  // File filtering configuration
  files: {
    // Patterns to include in the analysis
    include: ["**/*.js", "**/*.ts", "**/*.jsx", "**/*.tsx"],

    // Patterns to exclude from the analysis
    exclude: ["node_modules/**", "dist/**", "build/**"],

    // Whether to use .gitignore for file filtering
    useGitignore: true,
  },

  // Git integration configuration
  git: {
    // Whether to include unstaged changes in the analysis
    includeUnstaged: false,
  },

  // Logging configuration
  logging: {
    // Log level: "debug", "info", "success", "warn", "error", "none"
    level: "info",
  },

  // LLM configuration
  llm: {
    // LLM provider to use (currently only "openai" is supported)
    provider: "openai",

    // API key for the provider (optional, can use OPENAI_API_KEY env var)
    apiKey: "sk-...",

    // Model to use (optional, can use OPENAI_MODEL env var, default: "gpt-4o")
    model: "gpt-4o",

    // Maximum number of tokens to use for the analysis
    maxTokens: 16384,
  },

  // Additional files to ignore (deprecated, use files.exclude instead)
  ignore: ["node_modules", "dist", "build"],
});

JSON (package.json)

{
  "name": "your-project",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    // ...
  },
  "devDependencies": {
    "deeplint-cli": "^1.0.0"
    // ...
  },
  "deeplint": {
    "contextBuilder": {
      "maxTokens": 8000,
      "tokensPerFile": 1000,
      "maxFileSize": 500,
      "includeDependencies": true,
      "includeStructure": true
    },
    "files": {
      "include": ["**/*.js", "**/*.ts", "**/*.jsx", "**/*.tsx"],
      "exclude": ["node_modules/**", "dist/**", "build/**"],
      "useGitignore": true
    },
    "git": {
      "includeUnstaged": false
    },
    "logging": {
      "level": "info"
    },
    "llm": {
      "provider": "openai",
      "model": "gpt-4o",
      "maxTokens": 16384
    }
  }
}

YAML (.deeplintrc.yml)

# Context builder configuration
contextBuilder:
  # Maximum number of tokens to use for the context
  maxTokens: 8000

  # Maximum number of tokens to use per file
  tokensPerFile: 1000

  # Maximum file size in KB to include in the context
  maxFileSize: 500

  # Whether to include dependencies in the context
  includeDependencies: true

  # Whether to include code structure in the context
  includeStructure: true

# File filtering configuration
files:
  # Patterns to include in the analysis
  include:
    - "**/*.js"
    - "**/*.ts"
    - "**/*.jsx"
    - "**/*.tsx"

  # Patterns to exclude from the analysis
  exclude:
    - "node_modules/**"
    - "dist/**"
    - "build/**"

  # Whether to use .gitignore for file filtering
  useGitignore: true

# Git integration configuration
git:
  # Whether to include unstaged changes in the analysis
  includeUnstaged: false

# Logging configuration
logging:
  # Log level: debug, info, success, warn, error, none
  level: info

# LLM configuration
llm:
  # LLM provider to use (currently only "openai" is supported)
  provider: openai

  # API key for the provider (optional, can use OPENAI_API_KEY env var)
  apiKey: sk-...

  # Model to use (optional, can use OPENAI_MODEL env var, default: "gpt-4o")
  model: gpt-4o

  # Maximum number of tokens to use for the analysis
  maxTokens: 16384

# Additional files to ignore (deprecated, use files.exclude instead)
ignore:
  - node_modules
  - dist
  - build

Configuration Options

The following table shows all available configuration options and their implementation status:

Section	Status	Description
contextBuilder	✅ Implemented	Controls how DeepLint builds context for analysis
files	✅ Implemented	Controls which files are included in the analysis
git.includeUnstaged	✅ Implemented	Controls whether to include unstaged changes
logging	✅ Implemented	Controls logging behavior
llm	✅ Implemented	Controls LLM-powered analysis
ignore	⚠️ Deprecated	Use files.exclude instead

Note: For planned features such as custom rules, auto-fixes, and advanced hooks, see the Roadmap.

Context Builder

Configure how DeepLint builds context for analysis:

contextBuilder: {
  // Maximum number of tokens to use for the context
  maxTokens: 8000,

  // Maximum number of tokens to use per file
  tokensPerFile: 1000,

  // Maximum file size in KB to include in the context
  maxFileSize: 500,

  // Whether to include dependencies in the context
  includeDependencies: true,

  // Whether to include code structure in the context
  includeStructure: true,
},

For more details on context building, see Context Building.

File Filtering

Control which files are included in the analysis:

files: {
  // Patterns to include in the analysis
  include: ["**/*.js", "**/*.ts", "**/*.jsx", "**/*.tsx"],

  // Patterns to exclude from the analysis
  exclude: ["node_modules/**", "dist/**", "build/**"],

  // Whether to use .gitignore for file filtering
  useGitignore: true,
},

Git Integration

Configure Git integration:

git: {
  // Whether to include unstaged changes in the analysis
  includeUnstaged: false,
},

For more details on Git integration, see Git Integration.

Logging

Configure logging behavior:

logging: {
  // Log level: "debug", "info", "success", "warn", "error", "none"
  level: "info",
},

LLM Configuration

Configure LLM-powered analysis (AI linting):

llm: {
  // LLM provider (currently only "openai" is supported)
  provider: "openai",

  // API key for the provider (optional, can use OPENAI_API_KEY env var)
  apiKey: "sk-...",

  // Model to use (optional, can use OPENAI_MODEL env var, default: "gpt-4o")
  model: "gpt-4o",

  // Maximum number of tokens to use for the analysis
  maxTokens: 16384,
},

LLM options can also be set via CLI flags or environment variables:

• CLI: --provider, --model, --api-key, --instructions, --unstaged, --json

• Env: OPENAI_API_KEY, OPENAI_MODEL

• Precedence: CLI > Env > Config file > Defaults

For a full list of options and details, see the LLM Configuration Guide.

Deprecated Options

// Additional files to ignore (deprecated, use files.exclude instead)
ignore: ["node_modules", "dist", "build"],

Configuration Methods

DeepLint uses a cascading configuration system powered by cosmiconfig, where values are resolved in the following order (highest precedence first):

1. Command-line options (e.g., --model, --unstaged)

2. Environment variables (e.g., OPENAI_API_KEY, OPENAI_MODEL)

3. Configuration file (searched in the order listed in Configuration File Locations)
4. Default values

This means that:

• Command-line options override everything else

• Environment variables override configuration file settings and defaults

• Configuration file settings override defaults

• Defaults are used when no other value is provided

Debugging Configuration

To verify the configuration values being used by DeepLint, you can use the --debug flag:

deeplint --debug

This will print the current configuration values to the console, along with other debug information:

ℹ  Current configuration:
ℹ  Context Builder Configuration:
ℹ    maxTokens: 8000
ℹ    tokensPerFile: 1000
ℹ    maxFileSize: 500
ℹ    includeDependencies: true
ℹ    includeStructure: true
ℹ  Files Configuration:
ℹ    include: ["**/*.js","**/*.ts","**/*.jsx","**/*.tsx"]
ℹ    exclude: ["node_modules/**","dist/**","build/**"]
ℹ    useGitignore: true
ℹ  Git Configuration:
ℹ    includeUnstaged: false
ℹ  Logging Configuration:
ℹ    level: "info"
ℹ  LLM Configuration:
ℹ    provider: "openai"
ℹ    model: "gpt-4o"
ℹ    maxTokens: 16384
ℹ  Ignore Patterns (deprecated):
ℹ    - node_modules
ℹ    - dist
ℹ    - build

This is particularly useful during development to ensure your configuration is being correctly loaded and applied.

Common Configuration Scenarios

Analyzing Only Specific Files

To analyze only specific files or directories:

files: {
  include: ["src/**/*.ts", "lib/**/*.js"],
  exclude: ["**/*.test.ts", "**/*.spec.js"],
}

Including Unstaged Changes

To include unstaged changes in your analysis:

git: {
  includeUnstaged: true,
}

Using More Comprehensive Analysis

For more comprehensive analysis (at the cost of performance):

contextBuilder: {
  maxTokens: 16000,
  includeDependencies: true,
  tokensPerFile: 2000,
}

Configuration Validation

DeepLint validates your configuration when it loads it. If there are any issues with your configuration, DeepLint will:

1. Log warnings about invalid configuration options

2. Apply default values to fix invalid values

3. Continue with the corrected configuration

For example, if you specify an invalid value for contextBuilder.maxTokens:

contextBuilder: {
  maxTokens: "not a number", // Invalid: should be a number
}

DeepLint will log a warning and use the default value:

WARN: Configuration validation failed with 1 errors:
  - contextBuilder.maxTokens: Value must be a number.
INFO: Applying defaults to fix invalid values...

Validation Rules

Here are some key validation rules:

• contextBuilder.maxTokens: Must be a number between 1,000 and 100,000

• contextBuilder.tokensPerFile: Must be a number between 100 and 10,000

• contextBuilder.maxFileSize: Must be a number between 1 and 10,000

• contextBuilder.includeDependencies: Must be a boolean

• contextBuilder.includeStructure: Must be a boolean

• files.include and files.exclude: Must be arrays of strings

• git.includeUnstaged: Must be a boolean

For a complete list of validation rules, see the Configuration System documentation.

Related Resources

• Context Building - Learn how context building works
• Configuration System - Technical details of the configuration system
• Command Line Options - Command line options that override configuration

Developer Note: The configuration system uses a schema-based validation approach with automatic defaults. If a configuration option is invalid, DeepLint will apply a sensible default value and continue running.

Next Steps

Now that you've configured DeepLint, you can:

1. Run your first analysis - Learn how to analyze your code
2. Set up Git integration - Integrate with your Git workflow

---

Previous: Installation | Next: First Run →