SolidJS 1.x Best Practices And API

Use this skill for SolidJS 1.x core framework work. Keep it focused on idiomatic Solid usage, not SolidStart-specific routing or server patterns.

Goals

• Preserve Solid 1.x reactivity instead of accidentally breaking it with destructuring or early reads.
• Prefer declarative derivation over effect-driven synchronization.
• Use the Solid control-flow and state primitives that match the problem.
• Explain recommendations in terms of Solid's fine-grained reactivity model.

Working style

Start by identifying whether the user needs one of these modes:

• explanation of a Solid 1.x concept
• debugging of stale or non-updating UI
• refactor toward more idiomatic Solid 1.x code
• code review of a Solid component or state pattern

When reviewing or editing code, prefer minimal changes that preserve behavior.

Default to explaining the smallest Solid-specific reason a pattern is wrong. Avoid turning a local fix into a large rewrite unless the user asked for that.

How to use this skill

Read this skill in passes instead of treating every section as equally important.

1. Start with Core mental model and Primitive selection guide.
2. Use Core best practices when writing or refactoring ordinary component code.
3. Use Specialized rule packs and Task-focused rule selection when the task is about testing, accessibility, web components, or performance work.
4. Use Common mistakes to catch and Debugging checklist for code review or bug triage.

Core mental model

• Components run once for setup.
• Reactive tracking happens when signals or reactive props are read inside JSX, createMemo, createEffect, and similar reactive scopes.
• If a read happens too early, outside tracking, it will not stay live.
• Props are reactive by default in Solid 1.x, so preserve their getters.

Use that model to explain bugs and justify fixes.

Primitive selection guide

Choose primitives with this bias:

1. createSignal for local scalar state
2. derived function or createMemo for computed values
3. createStore for nested structured state
4. createResource plus Suspense for async data loading
5. createEffect only when touching the outside world
6. Show, For, and Index for UI control flow
7. splitProps and mergeProps when reshaping props
8. context only for genuinely shared subtree concerns

Core heuristics

Keep these ideas in the foreground:

1. Keep getters intact.
2. Derive instead of synchronizing.
3. Let JSX and reactive scopes own dependency tracking.
4. Use effects for the outside world, not for routine data flow.
5. Use stores when the shape of nested data matters.

Core primitives

Use the smallest primitive that matches the job.

createSignal

• Use it for local scalar state and simple references.
• Read with count() and write with setCount(next) or setCount(prev => next).
• Prefer stores instead when nested object shape and fine-grained branch updates matter.

createMemo

• Use it for cached derived state that is reused or non-trivial.
• Read with memo().
• Do not use it for side effects or state writes.

createEffect

• Use it as the side-effect boundary for DOM APIs, browser APIs, logging, and third-party libraries.
• Clean up long-lived work with onCleanup.
• Do not use it as the default way to derive or synchronize state; check whether the real need is a memo, resource, store helper, or plain JSX.

createResource

• Use it for fetch-like UI data loading.
• Pair it with Suspense for loading UI.
• Prefer it over createEffect(async () => ...) so loading and reactivity stay aligned with Solid's async model.

batch

• Use it to group synchronous setter calls when downstream computations should observe the combined update.
• Treat it as a targeted optimization or coordination tool, not a vague performance ritual.

createStore

• Use it for nested objects and arrays when property-level reactivity matters.
• Read properties directly, like store.user.name, and prefer targeted updates.
• If updates are mostly whole-object replacement and nested granularity does not matter, a signal may be simpler.

produce, reconcile, and unwrap

• Use produce for ergonomic nested mutations.
• Use reconcile when syncing store state to incoming server or external object graphs.
• Use unwrap when a plain non-reactive value is required.

splitProps and mergeProps

• Use splitProps when you need local and rest prop groupings without breaking reactivity.
• Use mergeProps for layered defaults and overrides.
• Prefer both over ad-hoc destructuring when props need to stay reactive.

Show

• Use it for primary conditional UI branches with when={condition} and optional fallback={...}.
• Prefer it over scattered && rendering and large ternaries.

For

• Use it for referentially keyed list rendering with each={items()}.
• Prefer it over .map(...) in dynamic UI code because it preserves identity and updates lists efficiently.

Index

• Use it when the list shape is stable and per-index access matters more than keyed identity.
• Do not replace every list with Index; choose it only when position-based retention is the real goal.

Suspense and ErrorBoundary

• Pair Suspense with async reads such as createResource.
• Use ErrorBoundary where async or rendering failures should be isolated.
• Prefer these boundaries over hand-rolled loading, error, and ready booleans scattered through the tree.

lazy

• Use it for component-level code splitting.
• Lazy-load subtree components and usually render them under Suspense.

onCleanup

• Use it to tear down timers, listeners, subscriptions, and external resources created in effects or component-owned scopes.
• It prevents leaks and stale subscriptions.

untrack

• Use it for intentionally non-reactive reads that should happen once without subscribing the current scope.
• Use it narrowly. If a value should stay live, untrack is the wrong tool.

createContext and useContext

• Use them for shared subtree state or capabilities that would otherwise require prop drilling.
• Provide stable shared values near the subtree root and consume them with useContext.
• Prefer context for intentional sharing, not as a blanket replacement for local state.

refs

• Use refs for direct access to DOM nodes or child handles when imperative DOM work is actually needed.
• They are appropriate for focus, measurement, and DOM-library integration.
• Prefer normal declarative rendering unless imperative access is necessary.

Core best practices

Keep props and reads reactive

• Pass values to JSX props unless the child intentionally accepts an accessor API.
• Do not destructure reactive props by default; access them as props.name or preserve them with splitProps.
• Keep reactive reads inside JSX, memos, or other reactive scopes. The component body is setup code, not a tracked render loop.

Prefer:

function App() {
  const [id] = createSignal(0);
  return <User id={id()} name="Brenley" />;
}

function User(props: { id: number; name: string }) {
  return <h1>{props.id} - {props.name}</h1>;
}

Prefer derivation over synchronization

• If one value can be computed from another, derive it with a wrapper function or createMemo.
• Use createMemo when the computation is reused, non-trivial, or clearly benefits from caching.
• Do not mirror state through createEffect unless the job is actually synchronizing with the outside world.

Common anti-pattern:

const [firstName, setFirstName] = createSignal("John");
const [lastName, setLastName] = createSignal("Doe");
const [fullName, setFullName] = createSignal("");

createEffect(() => {
  setFullName(`${firstName()} ${lastName()}`);
});

Prefer:

const fullName = createMemo(() => `${firstName()} ${lastName()}`);

For async reads, prefer createResource over createEffect(async () => ...).

Use the framework primitives that match the job

• Prefer Show, For, Index, Switch, and Match over ad-hoc &&, ternaries, and .map(...) in JSX.
• Prefer createStore when nested object shape and property-level updates matter.
• Prefer splitProps and mergeProps when reshaping props.
• Prefer context for intentional subtree sharing, not as a blanket replacement for local state.

Keep imperative work explicit

• Use createEffect for DOM APIs, browser APIs, logging, subscriptions, and third-party integrations.
• Use refs only when direct DOM or child-handle access is genuinely needed.
• Pair long-lived imperative work with onCleanup.

If the job is ordinary rendering, keep it declarative. Use the rule packs below for testing, accessibility, web-component, and performance-specific guidance.

Debugging checklist

When a Solid 1.x component is not updating correctly, check these first:

1. Was a signal or prop read outside a reactive scope?
2. Were props destructured in a way that broke the getter?
3. Was an accessor passed where a plain value should have been, or vice versa?
4. Is createEffect being used to mirror state that should be derived?
5. Should splitProps or mergeProps be used instead of destructuring?
6. Would createStore better fit the shape of the state?
7. Was untrack or batch used intentionally, or is it masking the real problem?

Specialized rule packs

Use these rule packs when the task is more specialized than the general reactivity guidance above.

Treat the rule IDs as lookup labels inside this skill. They are there to make review checklists and task-focused loading more compact.

Control flow rules

State management rules

Refs and DOM rules

Performance rules

Accessibility rules

Testing rules

Task-focused rule selection

Writing new components

Load these rules first when creating new Solid 1.x components:

• 1-1 Ensure signals are called as functions
• 2-1 Prevent reactivity breakage from destructured props or early reads
• 2-2 Handle default props correctly
• 2-3 Separate local and forwarded props
• 2-6 No early returns; prefer JSX control flow
• 2-9 Never call components as plain functions
• 3-1 Proper conditional rendering with Show
• 3-2 Efficient list rendering with For
• 5-3 Cleanup long-lived work with onCleanup

Code review

Bias code review toward these priorities:

• 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:

• 1-2 Prevent unnecessary recomputation
• 1-6 Reduce update cycles
• 4-2 Prefer granular store updates
• 6-1 Prevent unwanted subscriptions
• 6-2 Use code splitting when it meaningfully shrinks the initial bundle
• 6-4 Read only the store properties that matter

State management

Load these rules when the task is mostly about application state:

• 4-1 Choose the right primitive
• 4-2 Use efficient store updates
• 4-3 Use produce for complex mutations
• 4-4 Use reconcile for external data integration
• 4-5 Use context for cross-component state

Accessibility audit

Load these rules when auditing accessibility:

• 7-1 Semantic structure
• 7-2 Screen reader support
• 7-3 Keyboard support

Writing tests

Load these rules when writing or reviewing tests:

• 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 separation
• 8-7 Browser mode versus jsdom
• 8-8 Portals and non-standard ARIA structures
• 8-9 IndexedDB and localStorage cleanup patterns
• 8-10 MemoryRouter setup for integration tests
• 8-11 QueryClient configuration for tests

Integrating web components and custom elements

Load these rules when the user is using Shoelace, FAST, Lion, Material Web Components, native <dialog>, the Popover API, or similar browser-native imperative APIs:

• 2-10 Declare custom element tags in the JSX namespace and type newer HTML attributes when TypeScript needs help
• 5-6 Use on: for custom element events and type CustomEvent payloads correctly
• 5-7 Sync Solid signals to imperative web component APIs with refs and effects
• 6-6 Prefer per-component imports and keep ::part() overrides in global CSS

Common mistakes to catch

React comparison

When the user is thinking in React terms, keep these comparisons handy:

Priority levels

• CRITICAL: fix immediately; likely runtime bugs, broken reactivity, or broken tests
• HIGH: address in code review; correctness or maintainability issues
• MEDIUM: apply when relevant; improves quality and ergonomics
• LOW: refactor-level improvements and secondary optimizations

Tooling note

For automated linting alongside these rules, prefer eslint-plugin-solid. It catches many of the same issues around destructured props, early returns, React-style props, style prop format, and unsafe patterns such as innerHTML misuse.

Output expectations

When helping the user, prefer this structure:

1. State the Solid-specific issue.
2. Explain why it happens in Solid 1.x.
3. Show the minimal corrected code.
4. Mention any tradeoff only if it materially affects the choice.

Example prompts this skill should handle well

• "Why does this Solid component stop updating when I destructure props?"
• "Can you refactor this SolidJS component to be more idiomatic?"
• "I think I am overusing createEffect in this Solid app."
• "Review this Solid 1.x component and point out reactivity mistakes."

Additional resources

• Solid 1.x best practices: https://www.brenelz.com/posts/solid-js-best-practices/
• Solid docs: https://docs.solidjs.com/
• Reactivity concepts: https://docs.solidjs.com/concepts/intro-to-reactivity