solid-js-best-practices

name	solid-js-best-practices
description	Solid.js best practices for AI-assisted code generation, code review, refactoring, and debugging reactivity issues. Use when writing Solid.js components, auditing SolidJS code, migrating from React to Solid, fixing signals and fine-grained reactivity bugs, or integrating web component libraries. 55 rules across 8 categories (reactivity, components, control flow, state management, refs/DOM, performance, accessibility, testing) ranked by priority.
license	MIT
allowed-tools	["Read","Grep","Glob"]
metadata	{"topics":["claude-skills","claude-code-skill"]}

Solid.js Best Practices

Comprehensive best practices for building Solid.js applications and components, optimized for AI-assisted code generation, review, and refactoring.

Quick Reference

Essential Imports

import {
  createSignal,
  createEffect,
  createMemo,
  createResource,
  onMount,
  onCleanup,
  Show,
  For,
  Switch,
  Match,
  Index,
  Suspense,
  ErrorBoundary,
  lazy,
  batch,
  untrack,
  mergeProps,
  splitProps,
  children,
} from "solid-js";

import { createStore, produce, reconcile } from "solid-js/store";

Component Skeleton

import { Component, JSX, mergeProps, splitProps } from "solid-js";

interface MyComponentProps {
  title: string;
  count?: number;
  onAction?: () => void;
  children?: JSX.Element;
}

const MyComponent: Component<MyComponentProps> = (props) => {
  // Merge default props
  const merged = mergeProps({ count: 0 }, props);

  // Split component props from passed-through props
  const [local, others] = splitProps(merged, ["title", "count", "onAction"]);

  // Local reactive state
  const [value, setValue] = createSignal("");

  // Derived/computed values
  const doubled = createMemo(() => local.count * 2);

  // Side effects
  createEffect(() => {
    console.log("Count changed:", local.count);
  });

  // Lifecycle
  onMount(() => {
    console.log("Component mounted");
  });

  onCleanup(() => {
    console.log("Component cleanup");
  });

  return (
    <div {...others}>
      <h1>{local.title}</h1>
      <p>Count: {local.count}, Doubled: {doubled()}</p>
      <input
        value={value()}
        onInput={(e) => setValue(e.currentTarget.value)}
      />
      <button onClick={local.onAction}>Action</button>
      {props.children}
    </div>
  );
};

export default MyComponent;

Rules by Category

1. Reactivity (7 rules)

#	Rule	Priority	Description
1-1	Use Signals Correctly	CRITICAL	Always call signals as functions count() not count
1-2	Use Memo for Derived Values	HIGH	Use createMemo for computed values, not createEffect
1-3	Effects for Side Effects Only	HIGH	Use createEffect only for side effects, not derivations
1-7	No Primitives in Reactive Contexts	HIGH	Don't call hooks or create reactive primitives inside effects or memos
1-4	Avoid Setting Signals in Effects	MEDIUM	Setting signals in effects can cause infinite loops
1-5	Use Untrack When Needed	MEDIUM	Use untrack() to prevent unwanted reactive subscriptions
1-6	Batch Signal Updates	LOW	Use batch() for multiple synchronous signal updates

2. Components (10 rules)

#	Rule	Priority	Description
2-1	Never Destructure Props	CRITICAL	Destructuring props breaks reactivity
2-6	Components Return Once	CRITICAL	Never use early returns — use <Show>, <Switch>, etc. in JSX
2-9	Never Call Components as Functions	CRITICAL	Always use JSX or createComponent() — direct calls leak reactive scope
2-2	Use mergeProps	HIGH	Use mergeProps for default prop values
2-3	Use splitProps	HIGH	Use splitProps to separate prop groups safely
2-7	No React-Specific Props	HIGH	Use class not className, for not htmlFor
2-10	Custom Element TypeScript Declarations	HIGH	Declare custom element tags in JSX namespace; augment DOM types for newer attributes
2-4	Use children Helper	MEDIUM	Use children() helper for safe children access
2-5	Prefer Composition	MEDIUM	Prefer composition and context over prop drilling
2-8	Style Prop Conventions	MEDIUM	Use object syntax with kebab-case properties for style

3. Control Flow (6 rules)

#	Rule	Priority	Description
3-1	Use Show for Conditionals	HIGH	Use <Show> instead of ternary operators
3-2	Use For for Lists	HIGH	Use <For> for referentially-keyed list rendering
3-3	Use Index for Primitives	MEDIUM	Use <Index> when array index matters more than identity
3-4	Use Switch/Match	MEDIUM	Use <Switch>/<Match> for multiple conditions
3-6	Stable Component Mount	MEDIUM	Avoid rendering the same component in multiple Switch/Show branches
3-5	Provide Fallbacks	LOW	Always provide fallback props for loading states

4. State Management (5 rules)

#	Rule	Priority	Description
4-1	Signals vs Stores	HIGH	Use signals for primitives, stores for nested objects
4-2	Use Store Path Syntax	HIGH	Use path syntax for granular, efficient store updates
4-3	Use produce for Mutations	MEDIUM	Use produce for complex mutable-style store updates
4-4	Use reconcile for Server Data	MEDIUM	Use reconcile when integrating server/external data
4-5	Use Context for Global State	MEDIUM	Use Context API for cross-component shared state

5. Refs & DOM (7 rules)

#	Rule	Priority	Description
5-1	Use Refs Correctly	HIGH	Use callback refs for conditional elements
5-2	Access DOM in onMount	HIGH	Access DOM elements in onMount, not during render
5-3	Cleanup with onCleanup	HIGH	Always clean up subscriptions and timers
5-5	Avoid innerHTML	HIGH	Avoid innerHTML to prevent XSS — use JSX or textContent
5-7	Web Component Controlled State	HIGH	Use createEffect + ref + imperative calls to sync signals to web component APIs
5-4	Use Directives	MEDIUM	Use use: directives for reusable element behaviors
5-6	Event Handler Patterns	MEDIUM	Use on:/oncapture: namespaces and array handler syntax correctly

6. Performance (6 rules)

#	Rule	Priority	Description
6-1	Avoid Unnecessary Tracking	HIGH	Don't access signals outside reactive contexts
6-2	Use Lazy Components	MEDIUM	Use lazy() for code splitting large components
6-3	Use Suspense	MEDIUM	Use <Suspense> for async loading boundaries
6-6	Web Component CSS and Bundle Strategy	MEDIUM	Import components individually; place ::part() overrides in a global stylesheet
6-4	Optimize Store Access	LOW	Access only the store properties you need
6-5	Prefer classList	LOW	Use classList prop for conditional class toggling

7. Accessibility (3 rules)

#	Rule	Priority	Description
7-1	Use Semantic HTML	HIGH	Use appropriate semantic HTML elements
7-2	Use ARIA Attributes	MEDIUM	Apply appropriate ARIA attributes for custom controls
7-3	Support Keyboard Navigation	MEDIUM	Ensure all interactive elements are keyboard accessible

8. Testing (11 rules)

#	Rule	Priority	Description
8-1	Configure Vitest for Solid	CRITICAL	Configure Vitest with Solid-specific resolve conditions and plugin
8-2	Wrap Render in Arrow Functions	CRITICAL	Always use render(() => <C />) not render(<C />)
8-3	Test Primitives in a Root	HIGH	Wrap signal/effect/memo tests in createRoot or renderHook
8-4	Handle Async in Tests	HIGH	Use findBy queries and proper timer config for async behavior
8-5	Use Accessible Queries	MEDIUM	Prefer role and label queries over test IDs
8-6	Separate Logic from UI Tests	MEDIUM	Test primitives/hooks independently from component rendering
8-7	Browser Mode for Web Components and PWA APIs	HIGH	Use Vitest browser mode (real Chromium) for custom elements, shadow DOM, and browser-native APIs
8-8	Testing Headless UI Libraries with Non-Standard ARIA	MEDIUM	Headless UI libraries use non-obvious ARIA structures and portals — inspect the actual tree before querying
8-9	Browser-Native API Test Isolation	HIGH	Clear IndexedDB and localStorage between tests — close connection before deleteDatabase
8-10	Router Integration Testing	HIGH	Use MemoryRouter root prop to provide router context to layout providers
8-11	TanStack Query Test Setup	HIGH	Create a fresh QueryClient per test with retry and caching disabled

Task-Based Rule Selection

Writing New Components

Load these rules when creating new Solid.js components:

Rule	Why
1-1	Ensure signals are called as functions
2-1	Prevent reactivity breakage
2-6	No early returns — use control flow in JSX
2-9	Never call components as plain functions
2-2	Handle default props correctly
2-3	Separate local and forwarded props
3-1	Proper conditional rendering
3-2	Efficient list rendering
5-3	Prevent memory leaks

Code Review

Focus on these rules during code review:

Priority	Rules
CRITICAL	1-1, 2-1, 2-6, 2-9
HIGH	1-2, 1-3, 1-7, 2-7, 5-2, 5-3, 5-5

Performance Optimization

Load these rules when optimizing performance:

Rule	Focus
1-2	Prevent unnecessary recomputation
1-6	Reduce update cycles
4-2	Granular store updates
6-1	Prevent unwanted subscriptions
6-2	Code splitting
6-4	Efficient store access

State Management

Load these rules when working with application state:

Rule	Focus
4-1	Choose the right primitive
4-2	Efficient updates
4-3	Complex mutations
4-4	External data integration
4-5	Cross-component state

Accessibility Audit

Load these rules when auditing accessibility:

Rule	Focus
7-1	Semantic structure
7-2	Screen reader support
7-3	Keyboard users

Writing Tests

Load these rules when writing or reviewing tests:

Rule	Focus
8-1	Correct Vitest configuration
8-2	Reactive render scope
8-3	Reactive ownership for primitives
8-4	Async queries and timers
8-5	Accessible query selection
8-6	Test architecture
8-7	When to use browser mode vs jsdom
8-8	Portals and non-standard ARIA structures
8-9	IDB and localStorage cleanup patterns
8-10	MemoryRouter setup for integration tests
8-11	QueryClient configuration for tests

Integrating Web Components / Custom Elements

Load these rules when using any custom element library (Shoelace, FAST, Lion, Material Web Components, etc.) or native browser APIs like <dialog> and the Popover API:

Rule	Why
2-10	Declare custom element tags in JSX namespace; type newer HTML attributes and experimental CSS properties
5-6	Use on: for all custom element events; type CustomEvent payloads correctly
5-7	Sync Solid signals to web component / native browser API imperative calls
6-6	Per-component imports for tree-shaking; ::part() overrides in global CSS only

Common Mistakes to Catch

Mistake	Rule	Solution
Forgetting () on signal access	1-1	Always call signals: count()
Destructuring props	2-1	Access via props.name
Using ternaries for conditionals	3-1	Use <Show> component
.map() for lists	3-2	Use <For> component
Deriving values in effects	1-2	Use createMemo
Setting signals in effects	1-4	Use createMemo or external triggers
Accessing DOM during render	5-2	Use onMount
Forgetting cleanup	5-3	Use onCleanup
Early returns in components	2-6	Use <Show>, <Switch> in JSX instead
Using className or htmlFor	2-7	Use class and for (standard HTML)
style="color: red" or camelCase styles	2-8	Use style={{ color: "red" }} with kebab-case
Using innerHTML with user data	5-5	Use JSX or sanitize with DOMPurify
Spreading whole store	6-4	Access specific properties
String concatenation for class toggling	6-5	Use classList={{ active: isActive() }}
render(<Comp />) without arrow	8-2	Use render(() => <Comp />)
Effects in tests without owner	8-3	Wrap in createRoot or use renderHook
getBy for async content	8-4	Use findBy queries
MyComp(props) instead of <MyComp />	2-9	Always use JSX syntax or createComponent()
Calling useMatch()/useQuery() inside createEffect/createComputed	1-7	Call hooks once at component init, not inside reactive computations
Same component in Switch fallback and Match branch	3-6	Keep component in one stable position; use CSS for layout changes
Custom elements don't upgrade / lifecycle doesn't fire in tests	8-7	Use Vitest browser mode (real Chromium) instead of jsdom
IDB state persists between tests causing order-dependent failures	8-9	Close connection before deleteDatabase; use useCleanDb()
Router primitives throw "can only be used inside a Route"	8-10	Use MemoryRouter root prop with a layout factory
QueryClient retries mask errors / cache leaks between tests	8-11	Use makeTestQueryClient() with retry: false, gcTime: 0
waitFor(length === 0) passes before data loads	8-4	Use a settled anchor with findBy before asserting absence
getByRole('form') throws even though the form exists	7-2	Add aria-label or aria-labelledby to expose role="form"
<my-element onMyChange={...}> misses all events	5-6	Use on:my-change — on: prefix required for all web component custom events
my-element::part(...) rule inside a .module.css is silently ignored	6-6	Move ::part() overrides to a non-module global stylesheet
Barrel import of entire web component library	6-6	Import individual components by path to enable tree-shaking
value={signal()} on web component — no two-way sync	5-7	Listen to change events; push value imperatively via ref + createEffect
<div popover> or <button popoverTarget="x"> TypeScript error	2-10	Augment HTMLElement / HTMLButtonElement in a .d.ts file
Object/array prop on custom element becomes "[object Object]"	5-7	Use prop:myProp={value()} to set a JS property, not an HTML attribute
Experimental CSS property (anchor-name) produces a TypeScript error	2-8	Cast with as unknown as JSX.CSSProperties instead of as never

Solid.js vs React Mental Model

When helping users familiar with React, keep these differences in mind:

React	Solid.js
Components re-render on state change	Components run once, signals update DOM directly
useState returns [value, setter]	createSignal returns [getter, setter]
useMemo with deps array	createMemo with automatic tracking
useEffect(fn, [deps])	createEffect(fn) (no deps array — automatic tracking)
Destructure props freely	Never destructure props
Early returns (if (!x) return null)	<Show> / <Switch> in JSX (components return once)
{condition && <Component />}	<Show when={condition}><Component /></Show>
{items.map(item => ...)}	<For each={items}>{item => ...}</For>
className	class
htmlFor	for
style={{ fontSize: 14 }}	style={{ "font-size": "14px" }}
Context requires useContext hook	Context works with useContext or direct access
React 18: ref + addEventListener for custom element events; React 19: onMyEvent={handler} natively	on:my-event={handler} — always use on: prefix with web component events

Priority Levels

• CRITICAL: Fix immediately. Causes bugs, broken reactivity, or runtime errors.
• HIGH: Address in code reviews. Important for correctness and maintainability.
• MEDIUM: Apply when relevant. Improves code quality and performance.
• LOW: Consider during refactoring. Nice-to-have optimizations.

Key Solid.js Concepts

Fine-Grained Reactivity

Solid.js updates only the specific DOM elements that depend on changed data, not entire component trees. This is achieved through:

• Signals: Reactive primitives that track dependencies
• Effects: Side effects that automatically re-run when dependencies change
• Memos: Cached derived values that only recompute when dependencies change

Components Render Once

Unlike React, Solid components are functions that run once during initial render. Reactivity happens at the signal level, not the component level. This is why:

• Props must not be destructured (would capture static values)
• Signals must be called as functions (to maintain reactive tracking)
• Control flow uses special components (<Show>, <For>) instead of JS expressions

Stores for Complex State

For nested objects and arrays, Solid provides stores with:

• Fine-grained updates via path syntax
• Automatic proxy wrapping for nested reactivity
• Utilities like produce and reconcile for common patterns

Tooling

For automated linting alongside these best practices, use eslint-plugin-solid. The plugin catches many of the same issues this skill covers (destructured props, early returns, React-specific props, innerHTML usage, style prop format, etc.) and provides auto-fixable rules.

Resources

• Solid.js Documentation