Linting

The @studiometa/eslint-plugin-js-toolkit package provides an Oxlint/ESLint plugin that enforces best practices when writing components with this framework.

Installation

npm install --save-dev @studiometa/eslint-plugin-js-toolkit

Configuration

Oxlint

Add the plugin to your .oxlintrc.json:

{
  "jsPlugins": [
    {
      "name": "js-toolkit",
      "specifier": "@studiometa/eslint-plugin-js-toolkit"
    }
  ],
  "rules": {
    "js-toolkit/require-config": "error",
    "js-toolkit/require-config-name-pascal-case": "error",
    "js-toolkit/refs-camel-case": "error",
    "js-toolkit/refs-plural-multiple": "error",
    "js-toolkit/refs-no-bracket-access": "error",
    "js-toolkit/require-refs-declared-in-config": "error",
    "js-toolkit/options-camel-case": "error",
    "js-toolkit/require-options-declared-in-config": "error",
    "js-toolkit/async-lifecycle-methods": "error",
    "js-toolkit/on-handler-naming": "error",
    "js-toolkit/on-global-handler-prefix": "warn",
    "js-toolkit/emits-kebab-case": "error",
    "js-toolkit/emits-multi-word": "error",
    "js-toolkit/require-emit-declared-in-config": "error",
    "js-toolkit/components-pascal-case": "error",
    "js-toolkit/require-children-declared-in-config": "error",
    "js-toolkit/no-deprecated-properties": "warn",
    "js-toolkit/no-dispatch-event": "warn",
    "js-toolkit/no-shadow-dom": "error",
    "js-toolkit/no-create-app": "warn",
    "js-toolkit/no-event-listener-methods": "error",
    "js-toolkit/no-deep-utils-import": "error",
    "js-toolkit/no-redundant-with-mount-when-in-view": "warn",
    "js-toolkit/no-manual-intersection-observer": "warn",
    "js-toolkit/no-manual-mutation-observer": "warn",
    "js-toolkit/prefer-ref-over-query-selector": "warn"
  }
}

ESLint

Add the recommended config to your eslint.config.js (ESLint v9 flat config):

import jsToolkit from '@studiometa/eslint-plugin-js-toolkit';

export default [
  jsToolkit.configs.recommended,
  // ...your other config
];

To customise individual rule severities, add an override entry after the recommended config:

import jsToolkit from '@studiometa/eslint-plugin-js-toolkit';

export default [
  jsToolkit.configs.recommended,
  {
    rules: {
      'js-toolkit/no-create-app': 'error',
    },
  },
];

Rules

Class structure

Rule	Description	Fixable
js-toolkit/require-config	Requires a static config property with a name on every class extending Base.	❌
js-toolkit/require-config-name-pascal-case	Requires config.name to be PascalCase.	🔧

Refs

Rule	Description	Fixable
js-toolkit/refs-camel-case	Requires ref names in config.refs to be camelCase. Supports the [] multiple-ref suffix.	🔧
js-toolkit/refs-plural-multiple	Requires refs using the [] multiple-ref suffix to be pluralized (e.g. links[] not link[]).	❌
js-toolkit/refs-no-bracket-access	Disallows bracket access with a [] suffix on this.$refs (e.g. this.$refs['items[]']). Rewrites to dot notation camelCase.	🔧
js-toolkit/require-refs-declared-in-config	Requires all this.$refs.<name> accesses to be declared in static config.refs.	❌
js-toolkit/prefer-ref-over-query-selector	Warns when this.$el.querySelector() or this.$el.querySelectorAll() is used inside a Base subclass. Declare a ref in static config and use this.$refs instead.	❌

Options

Rule	Description	Fixable
js-toolkit/options-camel-case	Requires option keys in config.options to be camelCase.	🔧
js-toolkit/require-options-declared-in-config	Requires all this.$options.<name> accesses to be declared in static config.options.	❌

Emits

Rule	Description	Fixable
js-toolkit/emits-kebab-case	Requires emit names in config.emits to be kebab-case (e.g. content-change).	🔧
js-toolkit/emits-multi-word	Requires emit names in config.emits to be multi-word to avoid collisions with native DOM events (e.g. item-click not click).	❌
js-toolkit/require-emit-declared-in-config	Requires all this.$emit('name') calls to use event names declared in static config.emits.	❌

Components

Rule	Description	Fixable
js-toolkit/components-pascal-case	Requires component keys in config.components to be PascalCase.	🔧
js-toolkit/require-children-declared-in-config	Requires all this.$children.<Name> accesses to be declared in static config.components.	❌

Lifecycle methods

Rule	Description	Fixable
js-toolkit/async-lifecycle-methods	Requires lifecycle methods (mounted, destroyed, updated, terminated, ticked, scrolled, resized, moved, loaded, keyed) to be declared async.	🔧

Event handlers

Rule	Description	Fixable
js-toolkit/on-handler-naming	Requires event handler methods to follow the onXxxYyy camelCase convention.	❌
js-toolkit/on-global-handler-prefix	Requires handlers for window-only events (e.g. resize) to use the onWindow or onDocument prefix.	❌

Forbidden patterns

Rule	Description	Fixable
js-toolkit/no-deprecated-properties	Disallows deprecated properties ($parent, $root, $children). Use $closest() or $query() instead.	❌
js-toolkit/no-dispatch-event	Disallows dispatchEvent() inside Base subclasses. Use this.$emit() instead.	❌
js-toolkit/no-shadow-dom	Disallows attachShadow() inside Base subclasses. The framework uses Light DOM only.	❌
js-toolkit/no-create-app	Disallows createApp() (deprecated). Use registerComponent() instead.	❌
js-toolkit/no-event-listener-methods	Disallows addEventListener() and removeEventListener() inside Base subclasses. Define on* methods instead — the framework handles binding and cleanup automatically.	❌
js-toolkit/no-deep-utils-import	Disallows deep imports from @studiometa/js-toolkit/utils/*. Use the public entrypoint @studiometa/js-toolkit/utils instead.	🔧
js-toolkit/no-redundant-with-mount-when-in-view	Disallows wrapping withMountWhenInView inside withScrolledInView — the latter already includes the former internally.	❌
js-toolkit/no-manual-intersection-observer	Disallows new IntersectionObserver() inside Base subclasses. Use withIntersectionObserver or withMountWhenInView decorators instead.	❌
js-toolkit/no-manual-mutation-observer	Disallows new MutationObserver() inside Base subclasses. Use the withMutation decorator instead.	❌