@futdevpro/dynamo-eslint

Shared ESLint presets, custom Dynamo rules, and validation tools for FutDevPro TypeScript projects. This package provides standardized linting configurations optimized for lint-on-save functionality across different project types.

🚀 Quick Start

Installation

npm install --save-dev @futdevpro/dynamo-eslint

Required Peer Dependencies

npm install --save-dev \
  @typescript-eslint/eslint-plugin@^8.0.0 \
  @typescript-eslint/parser@^8.0.0 \
  eslint@^9.0.0 \
  eslint-plugin-import@^2.29.0 \
  eslint-plugin-jsdoc@^48.0.0 \
  eslint-plugin-prettier@^5.1.3 \
  prettier@^3.3.0

For Angular projects, also install:

npm install --save-dev \
  @angular-eslint/eslint-plugin@^19.0.0 \
  @angular-eslint/eslint-plugin-template@^19.0.0 \
  @angular-eslint/template-parser@^19.0.0

📋 Available Presets

1. base - Core TypeScript Rules

Generic TypeScript projects with browser environment.

const baseConfig = require('@futdevpro/dynamo-eslint/base');

module.exports = baseConfig;

Features:

• Browser environment
• 1000 line limit
• All Dynamo custom rules enabled
• Explicit return types required

2. nts - Node TypeScript Projects

Node.js TypeScript applications and services.

const ntsConfig = require('@futdevpro/dynamo-eslint/nts');

module.exports = ntsConfig;

Features:

• Node environment
• 1500 line limit (extended for server code)
• Module source type
• All base rules + Node-specific optimizations

3. ngx - Angular Projects

Angular applications with component and template linting.

const ngxConfig = require('@futdevpro/dynamo-eslint/ngx');

module.exports = ngxConfig;

Features:

• Angular ESLint integration
• Browser environment
• Component and template linting
• Angular-specific rules

4. fsm - Full Stack Module

Full-stack TypeScript modules (same as base).

const fsmConfig = require('@futdevpro/dynamo-eslint/fsm');

module.exports = fsmConfig;

5. nts-package - Node TypeScript Packages

NPM packages and libraries built with TypeScript.

const ntsPackageConfig = require('@futdevpro/dynamo-eslint/nts-package');

module.exports = ntsPackageConfig;

Features:

• Relaxed @typescript-eslint/ban-types and no-explicit-any rules
• Optimized for package development
• Extended line limits for library code

6. ngx-package - Angular Packages

Angular libraries and packages.

const ngxPackageConfig = require('@futdevpro/dynamo-eslint/ngx-package');

module.exports = ngxPackageConfig;

⚙️ Lint-on-Save Configuration

Critical: Configure ESLint to run ONLY on save, not on type!

VSCode/Cursor Settings

Create .vscode/settings.json in your project root:

{
  "eslint.run": "onSave",
  "eslint.workingDirectories": [{ "mode": "auto" }],
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": [
    "javascript",
    "typescript"
  ]
}

Workspace vs User Settings

• Workspace settings (.vscode/settings.json): Apply only to current project
• User settings: Apply globally to all projects

For team consistency, use workspace settings.

Multi-Root Workspace Configuration

For workspaces with multiple projects:

{
  "eslint.run": "onSave",
  "eslint.workingDirectories": [
    { "mode": "auto" },
    { "directory": "./packages/package-a" },
    { "directory": "./packages/package-b" }
  ],
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

🔧 Custom Dynamo Rules

This package includes custom ESLint rules for Dynamo conventions:

Import Rules

• @futdevpro/dynamo/import-order: Enforces consistent import ordering
• @futdevpro/dynamo/no-import-type: Forbids TypeScript import type syntax
• @futdevpro/dynamo/no-js-import: Prevents importing .js files in TypeScript

Naming Rules

• @futdevpro/dynamo/naming-patterns: Enforces DyFM naming conventions

Type Rules

• @futdevpro/dynamo/explicit-types: Enforces explicit type annotations on all TypeScript declarations (functions, variables, parameters, class properties, destructuring)

🛠️ CLI Validation Tools

Use these commands to validate your codebase:

# Validate import ordering across all TypeScript files
dynamo-validate-imports

# Validate naming conventions across all TypeScript files  
dynamo-validate-naming

# Audit ESLint configurations for duplicate rules
dynamo-eslintrc-audit

# Run comprehensive fixes
dynamo-fix

# Fix missing type annotations (functions, variables, parameters, class properties)
dynamo-fix-return-types

NPM Scripts Integration

Add to your package.json:

{
  "scripts": {
    "lint": "eslint src --ext .ts",
    "lint:fix": "eslint src --ext .ts --fix",
    "validate:imports": "dynamo-validate-imports",
    "validate:naming": "dynamo-validate-naming",
    "audit:eslintrc": "dynamo-eslintrc-audit",
    "fix": "dynamo-fix",
    "fix:types": "dynamo-fix-return-types"
  }
}

🔄 Migration from Manual Configs

Quick Migration Checklist

1. Install the package and peer dependencies
2. Replace your .eslintrc.json with the appropriate preset
3. Configure lint-on-save in VSCode/Cursor settings
4. Run validation tools to check for issues
5. Update CI/CD to use the new configuration

Common Migration Issues

• Peer dependency conflicts: Ensure all peer dependencies are installed
• Working directory issues: Use "eslint.workingDirectories": [{ "mode": "auto" }]
• Rule conflicts: The presets handle most conflicts automatically

📖 Detailed Migration Guide: See Migration Guide for step-by-step instructions.

🐛 Troubleshooting

Lint-on-Save Not Working

1. Check ESLint is running on save only:

   {
     "eslint.run": "onSave"  // NOT "onType"
   }

2. Verify working directories:

   {
     "eslint.workingDirectories": [{ "mode": "auto" }]
   }

3. Check file associations:

   {
     "eslint.validate": ["javascript", "typescript"]
   }

Peer Dependency Issues

Ensure all peer dependencies are installed with compatible versions:

npm ls @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint

ESLint v9 Flat Config

This package now uses ESLint v9 flat config format (eslint.config.js) for all exported presets. The package itself also uses flat config for self-linting.

📁 Examples

Reference implementations are available in the samples/ directory:

• samples/base/eslint.config.js - Base preset example
• samples/nts/eslint.config.js - Node TypeScript example
• samples/ngx/eslint.config.js - Angular example
• samples/fsm/eslint.config.js - Full Stack Module example
• samples/nts-package/eslint.config.js - Node TypeScript Package example
• samples/ngx-package/eslint.config.js - Angular Package example

🔧 Recent Fixes

TypeScript AST Transformation Context Fix

The dynamo-fix-return-types script includes a fix for TypeScript AST transformation context issues. This resolves compilation errors when using ts.visitEachChild() by properly providing the TransformationContext parameter:

// Fixed implementation
return ts.visitEachChild(node, visit, {} as ts.TransformationContext);

This ensures compatibility with TypeScript's AST transformation APIs.

Enhanced Type Annotation Fixing

The dynamo-fix-return-types script now handles comprehensive type annotation fixing:

• Function declarations: Adds return type annotations
• Arrow functions: Adds return type annotations
• Variable declarations: Adds type annotations based on initializer types
• Function parameters: Adds parameter type annotations
• Class properties: Adds property type annotations

The script uses TypeScript's type checker to infer appropriate types and automatically adds them to your code.

📚 Self-Linting

This package uses its own presets and rules for self-linting. The ESLint v9 flat config is in eslint.config.js and demonstrates advanced configuration patterns.

🏗️ Architecture

• Presets: Standardized rule configurations for different project types
• Custom Rules: Dynamo-specific linting rules for import order and naming
• CLI Tools: Validation and fixing utilities
• TypeScript Integration: Full TypeScript AST transformation support

Maintained by: Future Development Program Ltd.
License: ISC
Version: 02.00.0