OpenAEC-Foundation/solid-core-overview

solid-core-overview

Quick Reference

Version Matrix

| Package | Version | Status | Notes | |---------|---------|--------|-------| | solid-js | 1.x (1.8+) | Stable | Fine-grained reactivity, signals, stores, effects, SSR, streaming | | solid-js | 2.0 | Beta | Microtask batching, async first-class, onSettled replaces onMount | | @solidjs/start | 0.x | Deprecated | Used createServerData$, createServerAction$ — NEVER use for new projects | | @solidjs/start | 1.0 | Stable | Uses "use server" directive, built on Vinxi/Vite/Nitro | | @solidjs/router | < 0.15 | Legacy | Used cache function (now deprecated) | | @solidjs/router | 0.15+ | Stable | Introduced query (replaces cache), current API |

Key Version Dependencies

| Dependency | Requirement | |-----------|-------------| | SolidStart 1.0 | Requires @solidjs/router 0.15+ | | @solidjs/router | Requires solid-js 1.8.4+ | | createAsync | Bridge API between 1.x and 2.0 — use it NOW | | babel-preset-solid | Required build dependency for JSX compilation |

Critical Warnings

NEVER use SolidStart 0.x APIs (createServerData$, createServerAction$) in new projects — they are removed in SolidStart 1.0. ALWAYS use "use server" with query/action instead.

NEVER use cache from @solidjs/router — it is deprecated. ALWAYS use query (available in router 0.15+).

NEVER import store utilities from solid-js — stores live in solid-js/store. Wrong imports cause runtime errors with no compile-time warning.

NEVER import rendering utilities from solid-js — SSR/hydration functions live in solid-js/web.

NEVER confuse @solidjs/router (current) with the old solid-app-router package — the old package is abandoned.

---

API Categories at a Glance

Reactivity Primitives (solid-js)

| API | Purpose | |-----|---------| | createSignal | Reactive value with getter/setter | | createEffect | Side effects that auto-track dependencies | | createMemo | Cached derived values (reactive source) | | createResource | Async data fetching with loading/error states | | createComputed | Synchronous pre-render state sync | | createRenderEffect | Synchronous render-phase effects |

Reactive Utilities (solid-js)

| API | Purpose | |-----|---------| | batch | Defer updates until callback completes | | untrack | Read signals without creating dependencies | | on | Explicit dependency specification for effects | | observable | Convert signal to RxJS-compatible Observable | | from | Bridge external reactive systems into signals |

Lifecycle (solid-js)

| API | Purpose | SolidJS 2.x | |-----|---------|-------------| | onMount | Run once after DOM mount (non-tracking) | Replaced by onSettled | | onCleanup | Cleanup on unmount or effect re-run | Unchanged |

Store Utilities (solid-js/store)

| API | Purpose | |-----|---------| | createStore | Proxy-based reactive nested state | | createMutable | Direct-mutation reactive state (MobX-style) | | produce | Immer-style mutation syntax for stores | | reconcile | Diff-based store updates (API responses) | | unwrap | Strip reactive proxy, get plain object |

Component Utilities (solid-js)

| API | Purpose | |-----|---------| | splitProps | Split props into groups without losing reactivity | | mergeProps | Merge props with defaults reactively | | createContext | Create context for dependency injection | | useContext | Consume context value | | lazy | Code-split component with dynamic import | | children | Resolve and track children reactively |

Control Flow (solid-js)

| Component | Purpose | |-----------|---------| | <Show> | Conditional rendering | | <For> | Keyed list rendering (reference identity) | | <Index> | Indexed list rendering (position identity) | | <Switch>/<Match> | Multi-branch conditional | | <Suspense> | Async loading boundary | | <ErrorBoundary> | Error catching boundary | | <Portal> | Render outside component tree | | <Dynamic> | Dynamic component selection |

Rendering (solid-js/web)

| API | Purpose | |-----|---------| | render | Mount app to DOM element | | hydrate | Attach reactivity to server-rendered HTML | | renderToString | Synchronous SSR | | renderToStream | Streaming SSR | | isServer | Boolean constant for environment detection |

Router (@solidjs/router)

| API | Purpose | |-----|---------| | Router, Route, A | Core routing components | | useNavigate, useParams | Navigation hooks | | useSearchParams, useLocation | URL state hooks | | query | Cached server data fetching | | createAsync | Reactive async primitive (recommended) | | action | Server mutation wrapper | | useSubmission | Track mutation status |

SolidStart (@solidjs/start)

| API | Purpose | |-----|---------| | FileRoutes | File-based route generation | | "use server" | Server function directive | | API routes | HTTP method handlers (GET, POST, etc.) |

---

SolidJS 2.x Changes Summary

| Feature | SolidJS 1.x | SolidJS 2.x | |---------|-------------|-------------| | Reactivity | Synchronous by default | Microtask-batched | | Async | Manual with createResource | First-class Promises/async iterables | | Effects | Single createEffect | Split compute/apply pattern | | Lifecycle | onMount | onSettled (can return cleanup) | | Store setters | Path-style | Draft-first by default | | List rendering | <Index> component | <For keyed={false}> with accessors | | Derived state | createMemo only | createSignal(fn) for derived-but-writable |

New 2.x Primitives

• <Loading> — Fallback during initial render without tearing down UI
• isPending() — Track refreshing state
• action() — Dedicated mutation primitive with optimistic patterns
• createOptimistic / createOptimisticStore — Explicit optimistic UI

---

Getting Started

npm init solid@latest

Minimal SolidStart Project Structure

my-app/
├── public/
├── src/
│   ├── routes/
│   │   └── index.tsx          # / route
│   ├── entry-client.tsx       # Client hydration entry
│   ├── entry-server.tsx       # Server handler entry
│   └── app.tsx                # Root component
├── app.config.ts              # SolidStart configuration
├── package.json
├── tsconfig.json
└── vite.config.ts

Minimal app.tsx (SolidStart)

import { Suspense } from "solid-js";
import { Router } from "@solidjs/router";
import { FileRoutes } from "@solidjs/start/router";

export default function App() {
  return (
    <Router root={(props) => <Suspense>{props.children}</Suspense>}>
      <FileRoutes />
    </Router>
  );
}

Minimal SolidJS App (No SolidStart)

import { render } from "solid-js/web";
import { createSignal } from "solid-js";

function App() {
  const [count, setCount] = createSignal(0);
  return <button onClick={() => setCount((c) => c + 1)}>Count: {count()}</button>;
}

render(() => <App />, document.getElementById("root")!);

---

Ecosystem Package Map

| Package | npm Name | Purpose | |---------|----------|---------| | Solid Router | @solidjs/router | Client/server routing, data loading, actions | | SolidStart | @solidjs/start | Full-stack meta-framework (SSR, API routes) | | Solid Primitives | @solid-primitives/* | 40+ community reactive utilities | | Kobalte | @kobalte/core | Accessible unstyled UI components (like Radix UI) | | Solid Testing Library | @solidjs/testing-library | Testing utilities (Testing Library conventions) | | Solid DevTools | solid-devtools | Browser extension for signal/component inspection | | Babel Preset | babel-preset-solid | JSX compilation (required build dependency) | | Solid Transition Group | solid-transition-group | CSS enter/exit animations |

---

Reference Links

• references/methods.md -- Complete import map for all entry points
• references/examples.md -- App setup, SolidStart setup, version-specific patterns
• references/anti-patterns.md -- Wrong imports, version mismatches, ecosystem confusion

Official Sources

• https://docs.solidjs.com/concepts/intro-to-reactivity
• https://docs.solidjs.com/solid-start
• https://docs.solidjs.com/solid-router
• https://github.com/solidjs/solid
• https://github.com/solidjs-community/solid-primitives