@yfiles/eslint-plugin

Official ESLint plugin for yFiles for HTML projects. This repository provides an ESLint plugin with rules and flat-config presets. The goal is to ship helpful best‑practice rules tailored for applications built with yFiles for HTML. The rules included here are especially helpful for LLMs writing yFiles for HTML apps as they have been mostly trained on yFiles 2.6. Many of the rules correct common mistakes that happen when writing code for the deprecated yFiles 2.6 API. Some rules also provide suggestions for the best practices and fix patterns that are syntactically correct in yFiles 3.0 but won't work properly at runtime.

Note: The npm package name is "@yfiles/eslint-plugin" and the ESLint plugin key (namespace) is "@yfiles". Below is the list of currently implemented rules.

Features

• Works with ESLint v9 (flat config) and remains compatible with legacy .eslintrc via dual ESM/CJS builds.
• Written with type definitions included.
• Ships prebuilt flat-config presets (recommended, all, recommendedTypeChecked, allTypeChecked).

Installation

Peer requirements:

• Node >= 20.11
• ESLint ^8.57 or ^9

Install the plugin in your project:

npm i -D eslint typescript typescript-eslint @yfiles/eslint-plugin

• If you don’t use TypeScript, you can omit typescript and typescript-eslint and use the non-type-checked yFiles presets instead.

If you use TypeScript, make sure typescript is installed and configured in your project. Some rules require type information. See typescript-eslint for enabling linting with type information.

Usage (Flat Config – ESLint v9)

Use the typescript-eslint helper to define your flat config and enable typed linting. Create or edit eslint.config.js (or .mjs) at the root of your project:

// eslint.config.mjs
import tseslint from "typescript-eslint";
import yfilesconfigs from "@yfiles/eslint-plugin/configs";

// Use tseslint.config (define-style) to compose configs
export default tseslint.config(
  // 1) Start with TypeScript rules (type-checked)
  ...tseslint.configs.recommendedTypeChecked,

  // 2) Add yFiles plugin preset (type-checked)
  yfilesconfigs.recommendedTypeChecked,

  // 3) Configure TypeScript project for typed linting
  {
    languageOptions: {
      parserOptions: {
        // Point ESLint at your TS config(s) so rules can use type information
        project: ["./tsconfig.json"],
        // Ensure relative paths resolve from this file’s directory
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },

  // 4) Optionally, customize/override individual rules
  // {
  //   rules: {
  //     "@yfiles/replace-legacy-imports": "error",
  //   },
  // }
);

Run ESLint:

npx eslint .

Usage (Legacy .eslintrc)

If you still use the legacy config system, the package also publishes a CommonJS entry that can be loaded by .eslintrc files.

.eslintrc.cjs:

module.exports = {
  plugins: ["@yfiles"],
  rules: {
    "@yfiles/replace-legacy-imports": "error",
    "@yfiles/replace-legacy-fqns": "error",
    "@yfiles/replace-legacy-event-listeners": "error",
    "@yfiles/suggest-setter-methods": "error",
    "@yfiles/migrate-type-names": "error",
    "@yfiles/migrate-member-names": "error",
    "@yfiles/fix-implements-using-baseclass": "error",
    "@yfiles/remove-legacy-dollar-class": "error",
  },
};

Current Rules

The following rules are currently implemented:

• @yfiles/replace-legacy-imports
  • Rewrites imports from "yfiles" to "@yfiles/yfiles".
• @yfiles/replace-legacy-fqns
  • Replaces fully-qualified names like yfiles.view.GraphComponent with named imports and bare identifiers.
• @yfiles/replace-legacy-event-listeners
  • Rewrites addListener/removeListener calls to addEventListener/removeEventListener and swaps callback params to (event, sender).
• @yfiles/suggest-setter-methods
  • Warns on assigning to readonly yFiles properties like INode.layout or IEdge.sourceNode; suggests the corresponding IGraph methods.
• @yfiles/migrate-type-names
  • Renames legacy yFiles 2.6 type names to yFiles 3.0 names in type positions.
• @yfiles/migrate-member-names
  • Renames legacy yFiles 2.6 member names to their yFiles 3.0 counterparts.
• @yfiles/fix-implements-using-baseclass
  • Enforces using BaseClass(...) for yFiles interfaces instead of TypeScript implements, adding imports and fixing extends/implements as needed.
• @yfiles/remove-legacy-dollar-class
  • Removes obsolete ".$class" from yFiles type references.

More yFiles-specific rules (e.g., graph component usage best practices, canvas/webgl mode checks, license/loader configuration hints) will be added.

Configs

• configs.recommended
  • Enables a curated default rule set for typical yFiles for HTML apps.
• configs.all
  • Enables all rules shipped by this plugin.
• configs.recommendedTypeChecked
  • Enables a curated default rule set for typical yFiles for HTML apps including TypeScript type checking.
• configs.allTypeChecked
  • Enables all rules shipped by this plugin including TypeScript type checking.

Example enabling the "all" profile in flat config:

import yfilesconfigs from "@yfiles/eslint-plugin/configs";
export default [yfilesconfigs.allTypeChecked];

TypeScript and typed linting

Many yFiles projects use TypeScript. Some rules in this plugin are type-aware and require ESLint to read your TypeScript Program. Follow the typed-linting guidance from typescript-eslint:

• Use the typescript-eslint package and its flat-config helpers.
• Point ESLint at your TS config(s) via languageOptions.parserOptions.project and set tsconfigRootDir.
• Alternatively, enable the Project Service for multi-project repos.

Quick setup (single tsconfig):

import tseslint from "typescript-eslint";
import yfilesconfigs from "@yfiles/eslint-plugin";

export default tseslint.config(
  ...tseslint.configs.recommendedTypeChecked,
  yfilesconfigs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: ["./tsconfig.json"],
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
);

Using a dedicated tsconfig for linting (recommended in monorepos):

1. Create tsconfig.eslint.json next to your main tsconfig:

{
  "extends": "./tsconfig.json",
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "tests/**/*.ts",
    "tests/**/*.tsx"
  ]
}

2. Reference it in ESLint:

// inside your config:
const typedOptions = {
  languageOptions: {
    parserOptions: {
      project: ["./tsconfig.eslint.json"],
      tsconfigRootDir: import.meta.dirname,
    },
  },
};
export default tseslint.config(
  ...tseslint.configs.recommendedTypeChecked,
  yfilesconfigs.recommendedTypeChecked,
  typedOptions,
);

Project Service (alternative):

// inside your config:
const typedOptions = {
  languageOptions: {
    parserOptions: {
      projectService: true,
      tsconfigRootDir: import.meta.dirname,
    },
  },
};
export default tseslint.config(
  ...tseslint.configs.recommendedTypeChecked,
  yfilesconfigs.recommendedTypeChecked,
  typedOptions,
);

Notes:

• Ensure your tsconfig includes all files you lint; missing files cause “File is not included in project” errors.
• Typed linting is slower than syntax-only; consider running type-aware rules only in CI, or per-package.
• If you don’t need type information, you can use the non-type-checked presets: yfilesconfigs.recommended or yfilesconfigs.all.

Releases

This package publishes dual ESM and CJS builds and type definitions. Consumers on ESLint v9 (flat config) should import the default export; legacy users can continue using .eslintrc with the CommonJS entry.

License

Copyright (c) 2025 yWorks GmbH. See the license terms for yFiles for HTML.