eslint-plugin-preact-signal-patterns

ESLint rules for Preact Signals architectural patterns, promoting reactive component patterns and proper signal-passing conventions.

🎯 Philosophy

This plugin promotes a signal-passing architectural pattern where:

Signals are passed directly to component props: <Typography text={mySignal} />
Components handle signal reactivity automatically
.value usage is minimized and only used when necessary
.peek() is used for non-reactive reads in callbacks

Rule Comparison:

no-signal-value-outside-hooks - ✅ Unique to this plugin - Enforces .peek() usage in callbacks
no-signal-value-in-jsx - ✅ Unique to this plugin - Promotes signal-passing patterns
no-implicit-boolean-signal - ✅ Both plugins - This one uses enhanced heuristics, theirs uses TypeScript types

When to Use Which:

Use this plugin for architectural guidance, pattern enforcement, and auto-fixing
Use bensaufley's plugin for strict TypeScript-based type safety
Use both together for comprehensive signal usage validation

Enhanced `no-implicit-boolean-signal` Rule

Our implementation includes improvements inspired by bensaufley's plugin:

Enhanced detection patterns: More signal naming conventions
Import-based detection: Checks for @preact/signals* imports
Flexible nullish coalescing: Options like 'always', 'nullish', false
Better error messages: Clear guidance on fixing issues

📦 Installation

npm install --save-dev eslint-plugin-preact-signal-patterns
# or
yarn add -D eslint-plugin-preact-signal-patterns

🚀 Usage

Recommended Configuration

Add to your .eslintrc.js:

module.exports = {
  plugins: ["preact-signal-patterns"],
  extends: ["plugin:preact-signal-patterns/recommended"],
};

Manual Configuration

module.exports = {
  plugins: ["preact-signal-patterns"],
  rules: {
    "preact-signal-patterns/no-signal-value-outside-hooks": "error", // Error + auto-fix
    "preact-signal-patterns/no-signal-value-in-jsx": "warn", // Warning only
    "preact-signal-patterns/no-implicit-boolean-signal": "error", // Prevent bugs
  },
};

📋 Available Configurations

recommended: All rules enabled (error for patterns, warn for JSX)
strict: All rules as errors
jsx-warnings-only: Only warn about JSX usage
type-safety: Only the boolean coercion rule (focuses on bug prevention)
warn-no-autofix: All rules as warnings with auto-fix disabled

// Different config options
extends: ['plugin:preact-signal-patterns/recommended']  // Default: all rules
extends: ['plugin:preact-signal-patterns/strict']       // Strict mode: all errors
extends: ['plugin:preact-signal-patterns/jsx-warnings-only']  // JSX warnings only
extends: ['plugin:preact-signal-patterns/type-safety']  // Bug prevention only
extends: ['plugin:preact-signal-patterns/warnings']     // All warnings, no auto-fix by default

📏 Rules

`preact-signal-patterns/no-signal-value-outside-hooks` (🔧 Fixable)

Purpose: Prevents reading signal.value outside of useComputed, useSignalEffect, or JSX contexts.

Severity: Error
Auto-fix: Yes (converts .value to .peek())

Configuration Options:

{
  "preact-signal-patterns/no-signal-value-outside-hooks": ["error", {
    "autoFix": true // Default: true, set to false to disable auto-fix
  }]
}

Signal Detection:

This rule uses enhanced signal detection that checks:

Import analysis: Variables from @preact/signals* packages
Assignment analysis: Variables assigned from signal(), useSignal(), etc.
Naming patterns: Variables ending with $ (like count$) or following exact pattern [word]Signal (like userSignal)

Improved Detection (v1.1.0): The naming pattern detection has been made more conservative to reduce false positives.

What it does:

Detects when signal.value is read in regular JavaScript code (outside JSX)
Automatically fixes violations by replacing .value with .peek() (when autoFix: true)
Allows signal.value in JSX contexts and inside useComputed/useSignalEffect
Always allows assignments to signal.value
Only flags actual signals, not arbitrary objects with .value properties

Examples:

❌ Bad (will error and auto-fix):

import { signal } from '@preact/signals';

const mySignal = signal(0);
const count$ = signal(10);

const onSelect = (): void => {
  if (mySignal.value) { // Error: auto-fixed to mySignal.peek()
    doSomething(count$.value); // Error: auto-fixed to count$.peek()
  }
};

// This will NOT be flagged (not a signal):
const regularObject = { value: "hello" };
if (regularObject.value) { // ✓ Correctly ignored
  console.log("This is fine");
}

✅ Good:

import { signal } from '@preact/signals';

const mySignal = signal(0);
const count$ = signal(10);

const onSelect = (): void => {
  if (mySignal.peek()) { // ✓ Correct usage (auto-fixed)
    doSomething(count$.peek()); // ✓ Correct usage (auto-fixed)
  }
};

// Regular objects are fine
const regularObject = { value: "hello" };
if (regularObject.value) { // ✓ Not flagged
  console.log("This is fine");
}

// Assignments are always allowed
mySignal.value = newValue; // ✓ Always allowed

// Inside useComputed is allowed
const computed = useComputed(() => mySignal.value); // ✓ Allowed in hooks

// JSX usage is allowed (but will trigger warning from other rule)
<div className={mySignal.value ? "active" : ""} />; // ✓ Allowed in JSX

Disable Auto-fix for Warnings:

Important: By default, when a rule is set to "warn", it may still auto-fix when using eslint --fix. To prevent auto-fixing for warnings, use one of these approaches:

module.exports = {
  rules: {
    // Option 1: Explicitly disable auto-fix for warnings
    "preact-signal-patterns/no-signal-value-outside-hooks": ["warn", { "autoFix": false }],
  },
};

// Option 2: Use the "warnings" configuration
module.exports = {
  extends: ["plugin:preact-signal-patterns/warnings"], // No auto-fix by default
};

`preact-signal-patterns/no-signal-value-in-jsx`

Purpose: Warns when signal.value is used in JSX contexts, encouraging passing signals directly to components.

Severity: Warning
Auto-fix: No (intentionally)

Signal Detection:

Like the previous rule, this uses enhanced signal detection and only flags actual signals, not arbitrary objects with .value properties.

What it does:

Detects when signal.value is read inside JSX expressions
Shows warning messages but doesn't auto-fix
Encourages passing signals directly to component props

Examples:

⚠️ Discouraged (will warn):

import { signal } from '@preact/signals';

const mySignal = signal("active");
const otherSignal = signal(true);

<AppButton
  className={clsx(
    styles.button,
    mySignal.value && styles.active, // Warning: consider passing signal directly
    otherSignal.value && styles.disabled // Warning: consider passing signal directly
  )}
/>

// This will NOT be flagged (not a signal):
const config = { value: "theme-dark" };
<div className={config.value} /> // ✓ Correctly ignored

✅ Preferred:

const signalClass = useComputed(() => {
  const mySignalValue = mySignal.value;
  const otherSignalValue = otherSignal.value;
  return clsx({
    [styles.button]: true,
    [styles.active]: mySignalValue,
    [styles.disabled]: otherSignalValue,
  });
});
<AppButton className={signalClass} />;

`preact-signal-patterns/no-implicit-boolean-signal`

Purpose: Prevents bugs from implicit boolean coercion of signal objects.

Severity: Error
Auto-fix: No

What it does:

Detects when signal variables are used in boolean contexts without .value or .peek()
Prevents common bugs where signal object truthiness is checked instead of signal value
Enhanced detection: Uses both naming heuristics AND import analysis
Flexible options: Configure nullish coalescing behavior

Configuration Options:

{
  "preact-signal-patterns/no-implicit-boolean-signal": ["error", {
    "allowNullishCoalesce": "nullish" // 'always' | 'nullish' | false
  }]
}

'always': Allow all nullish coalescing (signal ?? default)
'nullish' (default): Allow nullish coalescing for potentially null signals
false: Disallow all nullish coalescing

Detection Methods:

Naming Patterns: mySignal, count$, userStore, appState, dataSource
Import Analysis: Variables from @preact/signals* packages
Assignment Analysis: Variables assigned from signal() calls

Examples:

❌ Bug-prone (will error):

import { signal } from '@preact/signals';

const mySignal = signal("hello");
const userStore = signal(null);
const count$ = signal(0);

// Bug: Always true (checking signal object existence)
if (mySignal) {
  console.log("Signal exists"); // This always runs!
}

// Bug: Always true  
const isActive = !!userStore && someCondition;

// Bug: Always truthy
while (count$) { // Infinite loop!
  break;
}

// Nullish coalescing (configurable)
const value = mySignal ?? "default"; // Error if allowNullishCoalesce: false

✅ Correct:

import { signal } from '@preact/signals';

const mySignal = signal("hello");
const userStore = signal(null);
const count$ = signal(0);

// Correct: Check signal value
if (mySignal.value) {
  console.log("Signal has truthy value");
}

// Correct: Use .peek() for non-reactive reads
const isActive = !!userStore.peek() && someCondition;

// Correct: Check value in loop
while (count$.value > 0) {
  count$.value--;
}

// Correct: Explicit null check
if (userStore.value === null) {
  console.log("User not set");
}

// Correct: Proper nullish coalescing  
const value = mySignal.value ?? "default";

🛠️ Usage

Running ESLint

# Check for violations
npx eslint src/

# Auto-fix non-JSX violations
npx eslint --fix src/

Expected Behavior

Non-JSX reads: Flagged as errors and auto-fixed to .peek()
JSX reads: Flagged as warnings (no auto-fix)
Assignments: Always allowed
Hook contexts: Always allowed

🏗️ Real-world Example

import { useComputed, useSignal } from "@preact/signals";

const MyComponent = () => {
  const countSignal = useSignal(0);
  const doubledSignal = useComputed(() => countSignal.value); // ✓ Allowed in useComputed

  const handleClick = () => {
    // Before: countSignal.value > 5  ❌ Error (auto-fixed)
    // After:  countSignal.peek() > 5  ✓ Correct
    if (countSignal.peek() > 5) {
      console.log("Count is high");
    }
    countSignal.value = 0; // ✓ Assignments always allowed
  };

  return (
    <div>
      {/* Preferred: Pass signal directly */}
      <span>{countSignal}</span> {/* ✓ Best practice */}
      {/* Discouraged: Reading .value in JSX */}
      <span>{countSignal.value}</span> {/* ⚠️ Warning */}
      <button onClick={handleClick}>Reset</button>
    </div>
  );
};

🔧 Code Organization

This plugin uses a shared utility module for consistent signal detection across all rules:

utils/signal-detector.js: Shared signal detection logic
rules/: Individual ESLint rules that use the shared detector
index.js: Plugin entry point and configuration presets

This architecture ensures consistent behavior and reduces code duplication.

🤝 Contributing

Fork the repository
Create your feature branch: git checkout -b my-new-feature
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin my-new-feature
Submit a pull request

Motivation for Signal Usage Rules in Preact

Why Avoid `.value` in JSX?

Accessing signal.value directly in JSX (e.g. <div>{mySignal.value}</div>) causes the entire parent component to re-render every time the signal changes. This can lead to unnecessary updates and reduced performance, especially as your app grows.

Recommended Pattern

Instead, pass the signal object itself into JSX (e.g. <div>{mySignal}</div>). Preact will automatically update only the specific DOM node associated with the signal, without re-rendering the whole parent component. This results in more efficient updates and better performance.

Why Avoid `.value` Outside Hooks?

Reading signal values outside of hooks or Preact’s reactive utilities can break the reactivity chain, resulting in missed updates or unpredictable rendering. Always read signal values inside hooks or reactive contexts to ensure your app responds correctly to changes.

On Utility Components (`Show`, `For`, etc.)

Preact provides utility components such as Show and For in separate packages. These utilities help you manage conditional rendering or list rendering with signals, and ensure that only the necessary child components update (not their parents).

Note: This plugin does not include these utilities directly, but encourages their use for optimal signal reactivity and performance. For advanced rendering patterns, consider using @preact/signals/utils or other packages.

📄 License

🔗 Related

Made with ❤️ for the Preact community

DracoRunner/eslint-plugin-preact-signal-patterns

eslint-plugin-preact-signal-patterns

🎯 Philosophy

Enhanced no-implicit-boolean-signal Rule

📦 Installation

🚀 Usage

Recommended Configuration

Manual Configuration

📋 Available Configurations

📏 Rules

preact-signal-patterns/no-signal-value-outside-hooks (🔧 Fixable)

Configuration Options:

Signal Detection:

What it does:

Examples:

Disable Auto-fix for Warnings:

preact-signal-patterns/no-signal-value-in-jsx

Signal Detection:

What it does:

Examples:

preact-signal-patterns/no-implicit-boolean-signal

What it does:

Configuration Options:

Detection Methods:

Examples:

🛠️ Usage

Running ESLint

Expected Behavior

🏗️ Real-world Example

🔧 Code Organization

🤝 Contributing

Motivation for Signal Usage Rules in Preact

Why Avoid .value in JSX?

Recommended Pattern

Why Avoid .value Outside Hooks?

On Utility Components (Show, For, etc.)

📄 License

🔗 Related

Enhanced `no-implicit-boolean-signal` Rule

`preact-signal-patterns/no-signal-value-outside-hooks` (🔧 Fixable)

`preact-signal-patterns/no-signal-value-in-jsx`

`preact-signal-patterns/no-implicit-boolean-signal`

Why Avoid `.value` in JSX?

Why Avoid `.value` Outside Hooks?

On Utility Components (`Show`, `For`, etc.)