@simplysm/eslint-plugin

An ESLint plugin for the Simplysm framework. It provides custom rules and a recommended preset to enforce project code conventions.

Uses ESLint Flat Config format and includes rules for TypeScript, SolidJS, and Tailwind CSS.

Installation

npm install @simplysm/eslint-plugin
# or
pnpm add @simplysm/eslint-plugin

Required Peer Dependencies

This plugin depends on the following packages:

| Package | Description | |---------|-------------| | eslint | ESLint core | | typescript | TypeScript compiler | | typescript-eslint | TypeScript ESLint parser and plugin | | eslint-plugin-import | Rules for import/export | | eslint-plugin-unused-imports | Auto-remove unused imports | | eslint-plugin-solid | SolidJS-specific rules | | eslint-plugin-tailwindcss | Tailwind CSS-specific rules | | globals | Global variable definitions |

Configuration

ESLint Flat Config (eslint.config.js)

Using recommended config (recommended)

The recommended config is a comprehensive setup that includes custom rules, TypeScript rules, SolidJS rules, and Tailwind CSS rules. This is sufficient for most cases.

import simplysm from "@simplysm/eslint-plugin";

export default [
  // Use recommended config
  simplysm.configs.recommended,
];

Using only specific rules

To selectively apply only certain custom rules:

import simplysm from "@simplysm/eslint-plugin";

export default [
  {
    plugins: {
      "@simplysm": simplysm,
    },
    rules: {
      "@simplysm/no-hard-private": "error",
      "@simplysm/no-subpath-imports-from-simplysm": "error",
      "@simplysm/ts-no-throw-not-implemented-error": "warn",
    },
  },
];

Custom Rules

This plugin provides 3 custom rules.

| Rule | Type | Auto-fix | Default Severity | Description | |------|------|----------|------------------|-------------| | no-hard-private | problem | Supported | error | Enforces TypeScript private instead of ECMAScript #field | | no-subpath-imports-from-simplysm | problem | Supported | error | Prohibits importing from @simplysm/*/src/ paths | | ts-no-throw-not-implemented-error | suggestion | Not supported | warn | Warns about usage of NotImplementedError |

no-hard-private

Restricts the use of ECMAScript private fields (#field). Use TypeScript's private keyword and _ prefix naming instead.

Supports auto-fix with the --fix option.

Detection targets:

• Class field declarations: #field
• Class method declarations: #method()
• Class accessor declarations: accessor #field
• Member access expressions: this.#field

Valid code:

class Foo {
  private _value = 1;
  private _count: number;

  private _doSomething() {
    return this._value;
  }
}

Invalid code:

class Foo {
  #value = 1;
  #count: number;

  #doSomething() {
    return this.#value;
  }
}

Auto-fix with decorators:

Members with decorators are also correctly converted. The private keyword is inserted after decorators and before other keywords like static.

// Before fix
class Foo {
  @Deco
  static #value = 1;
}

// After fix
class Foo {
  @Deco
  private static _value = 1;
}

Limitations:

• If a member with the same name prefixed with _ already exists, a name conflict occurs. In this case, auto-fix is not applied, and a nameConflict message requests manual adjustment.

class Foo {
  private _value = 1;
  #value = 2; // Error: Cannot convert "#value" to "_value" (name conflict)
}

no-subpath-imports-from-simplysm

Prohibits importing from @simplysm/* packages through /src/ paths. Only import through the official entry point (package root).

Supports auto-fix with the --fix option to convert to package root paths.

Detection targets:

• Static import statements: import ... from '...'
• Dynamic imports: import('...')
• Re-export statements: export { ... } from '...'
• Re-export all statements: export * from '...'

Valid code:

import { Foo } from "@simplysm/core-common";
import { Bar } from "@simplysm/core-node";

const mod = await import("@simplysm/core-common");

export { Baz } from "@simplysm/orm-common";
export * from "@simplysm/service-common";

Invalid code:

import { Foo } from "@simplysm/core-common/src/types/DateOnly";
import { Bar } from "@simplysm/core-node/src/utils";

const mod = await import("@simplysm/core-common/src/index");

export { Baz } from "@simplysm/orm-common/src/query-builder";
export * from "@simplysm/service-common/src/protocols";

Allowed subpaths:

Subpaths other than /src/ are allowed.

// Allowed: not a /src/ path
import { Foo } from "@simplysm/core-common/utils";

ts-no-throw-not-implemented-error

Warns about code that creates NotImplementedError from @simplysm/core-common with the new keyword. This rule prevents unimplemented code from being included in production.

It warns even if only creating without throwing. Auto-fix is not supported.

Supported import forms:

| Import Form | Detected | |-------------|----------| | named import: import { NotImplementedError } from "@simplysm/core-common" | Yes | | aliased import: import { NotImplementedError as NIE } from "@simplysm/core-common" | Yes | | namespace import: import * as CC from "@simplysm/core-common" | Yes | | dynamic import: await import("@simplysm/core-common") | No | | Re-exported from another module | No |

Invalid code (warnings):

import { NotImplementedError } from "@simplysm/core-common";

throw new NotImplementedError();                // Warning: "미구현" (default message)
throw new NotImplementedError("Feature X");     // Warning: "Feature X"
const err = new NotImplementedError();           // Warning: "미구현" (default message)

Aliased imports are also detected:

import { NotImplementedError as NIE } from "@simplysm/core-common";

throw new NIE(); // Warning

Namespace imports are also detected:

import * as CC from "@simplysm/core-common";

throw new CC.NotImplementedError(); // Warning

Message display rules:

• Calling new NotImplementedError() without arguments outputs a warning with the Korean default message "미구현".
• If a string argument is passed, that string is used as the warning message.

recommended Config Details

Full list of rules included in the recommended config.

Global Ignore Patterns

The following directories are excluded from linting:

• **/node_modules/**
• **/dist/**
• **/.*/**
• **/_*/**

Common Rules (JS/TS)

Rules applied to all JS and TS files.

| Rule | Severity | Description | |------|----------|-------------| | no-console | error | Prohibit console usage (prevent production performance degradation) | | no-warning-comments | warn | Warn about TODO/FIXME comments (to identify incomplete code) | | eqeqeq | error | Enforce ===, allow == null check | | no-self-compare | error | Prohibit self-comparison like x === x (prevent typos) | | array-callback-return | error | Prevent missing return in array callbacks like map/filter |

Node.js Built-in Module Restrictions

Restrict Node.js-specific API usage for code consistency across all packages.

| Restricted Target | Rule | Alternative | |-------------------|------|-------------| | Buffer (global) | no-restricted-globals | Uint8Array, BytesUtils from @simplysm/core-common | | buffer (import) | no-restricted-imports | Uint8Array, BytesUtils from @simplysm/core-common | | events (import) | no-restricted-imports | SdEventEmitter from @simplysm/core-common | | eventemitter3 (import) | no-restricted-imports | SdEventEmitter from @simplysm/core-common |

Unused Imports Rules

| Rule | Severity | Description | |------|----------|-------------| | unused-imports/no-unused-imports | error | Auto-remove unused imports | | unused-imports/no-unused-vars | error | Detect unused variables (allow _ prefix variables/arguments) |

Import Dependency Check

| Rule | Severity | Description | |------|----------|-------------| | import/no-extraneous-dependencies | error | Prohibit importing external dependencies not declared in package.json |

devDependencies are only allowed in the following paths:

• JS files: **/lib/**, **/eslint.config.js, **/simplysm.js, **/vitest.config.js
• TS files: **/lib/**, **/eslint.config.ts, **/simplysm.ts, **/vitest.config.ts, **/vitest.setup.ts

JS-only Rules (.js, .jsx)

Rules applied only to JS files. Not applied to TS files as the TypeScript compiler performs the same checks.

| Rule | Severity | Description | |------|----------|-------------| | require-await | error | Require await in async functions | | no-shadow | error | Prohibit variable shadowing | | no-duplicate-imports | error | Prohibit duplicate imports | | no-unused-expressions | error | Prohibit unused expressions | | no-undef | error | Prohibit using undefined variables |

TypeScript Rules (.ts, .tsx)

Rules applied based on @typescript-eslint. Performs precise checks using type information.

Async-related

| Rule | Severity | Description | |------|----------|-------------| | @typescript-eslint/require-await | error | Require await in async functions | | @typescript-eslint/await-thenable | error | Only allow await on thenable objects | | @typescript-eslint/return-await | error | Allow return await only inside try-catch | | @typescript-eslint/no-floating-promises | error | Prohibit unhandled Promises | | @typescript-eslint/no-misused-promises | error | Prevent error loss when passing async functions to void callbacks (excludes arguments, attributes) |

Type Safety

| Rule | Severity | Description | |------|----------|-------------| | @typescript-eslint/strict-boolean-expressions | error | Enforce strict boolean expressions (allow nullable boolean/object) | | @typescript-eslint/no-unnecessary-condition | error | Prohibit unnecessary condition checks (allow constant loop conditions) | | @typescript-eslint/no-unnecessary-type-assertion | error | Prohibit unnecessary type assertions | | @typescript-eslint/only-throw-error | error | Prohibit throwing non-Error objects (preserve stack trace) |

Code Style

| Rule | Severity | Description | |------|----------|-------------| | @typescript-eslint/no-shadow | error | Prohibit variable shadowing | | @typescript-eslint/prefer-reduce-type-parameter | error | Recommend using reduce type parameter | | @typescript-eslint/prefer-return-this-type | error | Recommend using this return type | | @typescript-eslint/no-unused-expressions | error | Prohibit unused expressions | | @typescript-eslint/prefer-readonly | error | Recommend readonly for members that don't change | | @typescript-eslint/no-array-delete | error | Prohibit using delete on arrays (prevent sparse array bugs) |

ts-comment Rules

| Rule | Severity | Description | |------|----------|-------------| | @typescript-eslint/ban-ts-comment | error | Require 3+ character description for @ts-expect-error |

SolidJS Rules (.ts, .tsx)

Rules applied based on eslint-plugin-solid. Applied to both .ts and .tsx files.

Mistake Prevention

| Rule | Severity | Description | |------|----------|-------------| | solid/reactivity | error | Detect reactivity loss (registers custom reactive functions like makePersisted) | | solid/no-destructure | error | Prohibit destructuring props (prevent reactivity loss) | | solid/components-return-once | error | Prohibit early returns in components | | solid/jsx-no-duplicate-props | error | Prohibit duplicate props | | solid/jsx-no-undef | error | Prohibit using undefined JSX variables (TypeScript support enabled) | | solid/no-react-deps | error | Prohibit React-style dependency arrays | | solid/no-react-specific-props | error | Prohibit React-specific props (className, etc.) |

Security

| Rule | Severity | Description | |------|----------|-------------| | solid/no-innerhtml | error | Prohibit innerHTML usage (prevent XSS) | | solid/jsx-no-script-url | error | Prohibit javascript: URLs |

Tooling Support

| Rule | Severity | Description | |------|----------|-------------| | solid/jsx-uses-vars | error | Prevent variables used in JSX from being flagged as unused imports |

Conventions

| Rule | Severity | Description | |------|----------|-------------| | solid/prefer-for | error | Recommend using For component | | solid/event-handlers | error | Enforce event handler naming rules | | solid/imports | error | Enforce import consistency | | solid/style-prop | error | Enforce style prop format | | solid/self-closing-comp | error | Enforce self-closing tags |

Tailwind CSS Rules (.ts, .tsx)

Rules applied based on eslint-plugin-tailwindcss. Recognizes clsx template literal tags.

| Rule | Severity | Description | |------|----------|-------------| | tailwindcss/classnames-order | warn | Auto-sort class order | | tailwindcss/enforces-negative-arbitrary-values | error | Unify negative arbitrary value format | | tailwindcss/enforces-shorthand | error | Recommend using shorthand | | tailwindcss/no-contradicting-classname | error | Prohibit conflicting classes (p-2 p-4, etc.) | | tailwindcss/no-custom-classname | error | Prohibit custom classes not defined in Tailwind | | tailwindcss/no-unnecessary-arbitrary-value | error | Prohibit unnecessary arbitrary values |

Test File Exception Rules

The following rules are relaxed for test files in **/tests/**/*.ts, **/tests/**/*.tsx paths:

| Rule | Change | Reason | |------|--------|--------| | no-console | off | Allow debug output in tests | | import/no-extraneous-dependencies | off | Allow using root devDependencies (vitest, etc.) | | @simplysm/ts-no-throw-not-implemented-error | off | Allow using not-implemented errors in test code | | solid/reactivity | off | Accessing signals inside async callbacks like waitFor in tests is intentional |

Configuration Summary by File Type

| File Pattern | Applied Rules | |--------------|---------------| | .js, .jsx | Common rules + JS-only rules + @simplysm custom rules + import/unused-imports rules | | .ts, .tsx | Common rules + @typescript-eslint rules + @simplysm custom rules + SolidJS rules + Tailwind CSS rules + import/unused-imports rules | | **/tests/** | Above rules with some relaxed |

License

Apache-2.0