embed-eslint

ESLint integration for embedded TypeScript compilation.

embed-eslint extends embed-typescript to provide seamless ESLint integration during TypeScript compilation. It allows you to apply ESLint rules and get linting feedback as part of the compilation process, all within your application runtime.

Features

• Integrated linting: Apply ESLint rules during TypeScript compilation
• Type-aware rules: Full support for @typescript-eslint rules that require type information
• Unified diagnostics: ESLint violations are reported as TypeScript diagnostics
• Zero configuration: Works out of the box with sensible defaults
• Custom rules: Configure any ESLint rules you need

Installation

npm install embed-typescript embed-eslint 
npm install typescript 
npm install eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

Note: All of the following are peer dependencies that must be installed separately:

• embed-typescript
• typescript
• eslint
• @typescript-eslint/parser (>=6.0.0)
• @typescript-eslint/eslint-plugin (>=6.0.0)

Quick Start

import { EmbedEsLint } from "embed-eslint";
import ts from "typescript";

// Create compiler with ESLint integration
const compiler = new EmbedEsLint({
  compilerOptions: {
    target: ts.ScriptTarget.ES2015,
    module: ts.ModuleKind.CommonJS,
    strict: true,
  },
  rules: {
    // TypeScript ESLint rules
    "@typescript-eslint/no-floating-promises": "error",
    "@typescript-eslint/no-unused-vars": "warn",
    "@typescript-eslint/explicit-function-return-type": "error",
    
    // Standard ESLint rules
    "no-console": "warn",
    "no-debugger": "error",
  },
});

// Compile and lint TypeScript code
const result = compiler.compile({
  "src/index.ts": `
    // This will trigger multiple ESLint violations
    async function fetchData() {
      console.log("Fetching data...");
      return { data: "test" };
    }
    
    fetchData(); // floating promise
    
    const unused = 42; // unused variable
  `
});

// Handle results
if (!result.success) {
  for (const diagnostic of result.diagnostics) {
    console.log(`${diagnostic.severity}: ${diagnostic.message}`);
    console.log(`  at ${diagnostic.file}:${diagnostic.start?.line}:${diagnostic.start?.column}`);
  }
}

Configuration

Constructor Options

The EmbedEsLint constructor extends all options from embed-typescript and adds:

interface IEmbedEsLintProps extends IEmbedTypeScriptProps {
  /**
   * ESLint rules configuration
   * Uses @typescript-eslint/eslint-plugin rules by default
   */
  rules?: Record<string, any>;
}

Available Rules

All rules from the following packages are available:

• @typescript-eslint/eslint-plugin: TypeScript-specific rules
• eslint: Core ESLint rules

Common useful rules:

{
  // Type-aware rules (require type information)
  "@typescript-eslint/no-floating-promises": "error",
  "@typescript-eslint/no-misused-promises": "error",
  "@typescript-eslint/await-thenable": "error",
  "@typescript-eslint/no-unnecessary-type-assertion": "warn",
  
  // Code quality rules
  "@typescript-eslint/no-unused-vars": "warn",
  "@typescript-eslint/explicit-function-return-type": "error",
  "@typescript-eslint/no-explicit-any": "warn",
  
  // Best practices
  "no-console": "warn",
  "no-debugger": "error",
  "eqeqeq": ["error", "always"],
}

Usage Examples

Basic Linting

import { EmbedEsLint } from "embed-eslint";

const compiler = new EmbedEsLint({
  rules: {
    "@typescript-eslint/no-unused-vars": "error",
  },
});

const result = compiler.compile({
  "test.ts": `
    const x = 1; // Error: 'x' is declared but never used
    const y = 2;
    console.log(y);
  `
});

With External Dependencies

import { EmbedEsLint } from "embed-eslint";
import external from "./external.json"; // Generated by embed-typescript CLI

const compiler = new EmbedEsLint({
  external,
  compilerOptions: {
    target: ts.ScriptTarget.ES2015,
    module: ts.ModuleKind.CommonJS,
  },
  rules: {
    "@typescript-eslint/no-floating-promises": "error",
  },
});

Custom Rule Severity

const compiler = new EmbedEsLint({
  rules: {
    // Different severity levels
    "@typescript-eslint/no-explicit-any": "warn",     // Warning
    "@typescript-eslint/no-unused-vars": "error",     // Error
    "no-console": "off",                              // Disabled
    
    // With options
    "@typescript-eslint/naming-convention": [
      "error",
      {
        selector: "interface",
        format: ["PascalCase"],
        prefix: ["I"],
      },
    ],
  },
});

How It Works

1. TypeScript Compilation: First compiles your TypeScript code using the embedded TypeScript compiler
2. ESLint Analysis: Passes the TypeScript AST and type information to ESLint
3. Unified Reporting: Converts ESLint messages to TypeScript diagnostics format
4. Single Pass: Both compilation and linting happen in a single operation

Differences from Standard ESLint

• No filesystem access: Works entirely in memory
• No config files: Configuration is passed programmatically
• Integrated diagnostics: ESLint violations appear as TypeScript compilation errors
• Type information: Automatically provides type information to rules that need it

Performance Considerations

• ESLint analysis adds overhead to compilation time
• For large codebases, consider enabling only essential rules
• Type-aware rules are more expensive than syntax-only rules
• Use skipLibCheck: true in compiler options for better performance

Troubleshooting

Rules not being applied

Ensure the rule names are correct and the severity is not "off":

// Correct
"@typescript-eslint/no-unused-vars": "error"

// Incorrect (missing namespace)
"no-unused-vars": "error" // This won't catch TypeScript-specific cases

Type-aware rules not working

Type-aware rules require proper TypeScript configuration:

const compiler = new EmbedEsLint({
  compilerOptions: {
    strict: true, // Enable strict type checking
    // ... other options
  },
  rules: {
    "@typescript-eslint/no-floating-promises": "error",
  },
});

Performance issues

1. Reduce the number of active rules
2. Disable type-aware rules if not needed
3. Use skipLibCheck: true in compiler options
4. Consider splitting large files

Contributing

Contributions are welcome! Please see the main embed-typescript repository for contribution guidelines.

License

MIT License - see the LICENSE file for details.

See Also

• embed-typescript - Core TypeScript embedding library
• @typescript-eslint - TypeScript ESLint plugin documentation
• ESLint - ESLint documentation