Imported from ShaulLavo/anubis (apps/web/AGENTS.md). Install upstream with npx skills add ShaulLavo/anubis --skill web. Copyright stays with the author.

AGENTS_SOLID.md — SolidJS Guidelines

Comprehensive guide for SolidJS development patterns, reactivity rules, and async handling.

Table of Contents

1. Core Principles
2. Terminology
3. Naming Conventions
4. Props & Reactivity
5. Async & Suspense
6. Solid Primitives Library

Core Principles

Reactivity Rules

⚠️ NEVER destructure props—it kills reactivity. Use splitProps or access props.property directly.

• Props are reactive getters—no need to wrap props.value in a function
• Use batch() for simultaneous signal updates
• Debug reactivity with createEffect containing a log statement

Terminology

Naming Conventions

create* — Reactive Primitives

Creates a reactive primitive that integrates with Solid's tracking system.

createSignal() // Signal with getter/setter
createMemo() // Derived reactive value
createEffect() // Side effect on dependency change

Use when:

• Setting up reactivity
• Registering dependencies
• Producing tracked reads/writes

make* — Non-Reactive Foundations

Creates a non-reactive building block with only setup + cleanup.

makeTimer() // Timer scheduler + cleanup, returns { clear }
// createTimer() would wrap makeTimer() to add reactivity

Use when:

• Building low-level utilities
• Composing into reactive primitives
• Zero reactivity needed

use* — Access Existing Resources

Consumes an already-created resource rather than creating new reactive machinery.

useContext() // Retrieves context created by createContext()
useTransition() // Accesses transition state

Use when:

• Accessing existing contexts
• Retrieving already-created resources

Props & Reactivity

The children Helper

Always use the children helper when accepting props.children:

import { children } from 'solid-js'

const resolved = children(() => props.children)
// Use resolved() in JSX

Benefits:

• Properly resolves children (functions executed, arrays flattened)
• Memoizes to prevent redundant DOM creation
• Tracks in the correct scope

Conditional rendering tip:

const resolved = children(() => visible() && props.children)

Async & Suspense

Quick Reference

Suspense Rules

1. Only resources trigger Suspense—signals, memos, and props do not

2. Never wrap resources in <Show> inside Suspense:

   // ❌ Bad
   <Suspense><Show when={res()} /></Suspense>
   
   // ✅ Good
   <Suspense>{res()}</Suspense>

3. Nested Suspense isolates loading states—each waits only for its own resources

Pattern: Resource-Driven UI

const [font] = createResource(activeFont, loadFont)

<Suspense fallback={<Spinner />}>
  <Editor font={font()} />
</Suspense>

// Smooth transition on change
startTransition(() => setActiveFont("Inter"))

Decision Guide

Solid Primitives Library

💡 Before implementing custom solutions, check solid-primitives.

Install: bun add @solid-primitives/{name}

Available Packages

active-element audio autofocus bounds clipboard connectivity context cursor date deep destructure devices event-bus event-dispatcher event-listener event-props filesystem fullscreen geolocation graphql history i18n immutable input intersection-observer keyboard keyed lifecycle map media memo mouse mutation-observer network pagination platform pointer props raf range refs resize-observer resource rootless scheduled script-loader scroll selection share signal-builders start static-store storage stream styles template timer title transition trigger tween upload utils websocket workers

Fetcher Modifiers

Resource Modifiers

Aggregation Rules:

• Array → append
• Object → shallow merge
• String → append
• null → no overwrite

createFetch

TanStack-Query-like fetch layer with native Solid integration:

// Built-in modifiers:
;(withAbort,
	withTimeout,
	withRetry,
	withCache,
	withAggregation,
	withRefetchEvent,
	withCatchAll,
	withCacheStorage)

Streams

WebSockets

Static Stores

Use for: Window size, mouse position, layout state, event state

Composition Pattern

Stack primitives for full-featured data fetching:

source → makeCache → makeRetrying → makeAbortable → createResource → createAggregated → Suspense

Result: Keys, cache, retry, abort, streaming, pagination, fine-grained reactivity, Suspense, and transitions—all without a query client.