Package

purescript-purs-solid

Repository
arazorda/purs-solid
License
ISC
Uploaded by
pacchettibotti
Published on
2026-11-17T20:48:23Z

PureScript bindings for Solid 2.0: fine-grained reactivity, rendering, SSR and hydration, the router, head tags and start mode.

The bindings use Solid's public API only; what they add is types that reject incorrect code. For example, a signal can't be written during setup, a derived value can't perform effects, a prop only type-checks on elements that have it, and a route's params come from its path. See docs/design.md.

Guide and API reference: purs-solid.vercel.app.

Example

module Example where

import Prelude

import Data.Tuple.Nested ((/\))
import Effect (Effect)
import Solid.Component as Component
import Solid.DOM.HTML as H
import Solid.Reactivity (createMemo)
import Solid.Signal (createSignal, modify_)
import Solid.Web (mount)

counter :: Component.Component {}
counter = Component.component \_ -> do
  count /\ setCount <- createSignal 0
  doubled <- createMemo ((_ * 2) <$> count)
  pure $ H.div { class: "counter" }
    [ H.button { onClick: \_ -> modify_ setCount (_ + 1), class: { big: (_ > 3) <$> count } } "+"
    , H.span {} (show <$> doubled)
    ]

main :: Effect Unit
main = mount (Component.element counter {})

Modules

  • Reactivity:
    • Solid.Signal, Solid.Reactivity;
    • Solid.Setup (the monad for component bodies and roots);
    • Solid.Root, Solid.Owner, Solid.Lifecycle, Solid.Context, Solid.Utility.
  • Async:
    • Solid.Async (createAsync over Aff; the result is Async, which can't be read before it loads);
    • Solid.Action (transactional mutations and optimistic values).
  • Stores: Solid.Store (typed paths, pure updates, projections, createSelector).
  • Views:
    • Solid.JSX, Solid.Component;
    • Solid.Component.JS (use JavaScript Solid components);
    • Solid.Control (conditionals, caseOn for data types, lists, loading, errored, portals);
    • Solid.DOM (props records: ref, class toggles, style, bindValue, typed aria-* and role, data-*, on: events), Solid.DOM.HTML, Solid.DOM.SVG, Solid.DOM.Aria. The HTML and SVG modules are generated from dom-indexed by npm run gen:dom.
  • Rendering: Solid.Web (mount, render, hydrate), Solid.Web.SSR (string, async and streamed server rendering), Solid.Errors (client and server error hooks, safe errors).
  • Routing and head tags:
    • Solid.Router (route @"/users/:id" gives the component { id :: String }, :id<int> an Int);
    • Solid.Router.Path (href);
    • Solid.Router.Search (query params typed by a schema row);
    • Solid.Router.Query (cached route data);
    • Solid.Router.Action (mutations the router tracks: forms, submissions, revalidation);
    • Solid.Meta.
  • Testing: Solid.Testing (mount into a DOM, settle, query, click, type, collect Solid's diagnostics).
  • Start mode: Solid.Start.ServerFunction, Solid.Start.UseServer, Solid.Start.RequestEvent, Solid.Start.Response (status, headers, and the Reply of an action: redirect, reload, respond), Solid.Start.Middleware.

Installing

Install the Solid 2.0 runtime and web renderer:

npm install --save-exact solid-js@2.0.0 @solidjs/web@2.0.0
npm install --save-exact @solidjs/router@2.0.0 @solidjs/meta@2.0.0
npm install --save-dev --save-exact @solidjs/vite-plugin@3.0.0 vite@8.3.8

Install the router and meta packages when using Solid.Router and Solid.Meta. Install Vite and the Solid plugin when using purs-solid/vite for compiled views or start mode. Bundle development builds with the development export condition to get Solid's diagnostics.

Start mode

A start-mode app is a Component. Use purs-solid/vite in place of @solidjs/vite-plugin. It takes the same options, with start.app and start.middleware given as module names. app defaults to the module App exporting app, and a middleware module exports middleware. Element calls with literal props are compiled by Solid's compiler into the same templates as Solid JSX, on the server and in the browser; anything else stays on the runtime path. compileViews: false keeps every element on the runtime path.

import solid from "purs-solid/vite";

export default defineConfig({ plugins: [solid({ start: true, ssr: true })] });

Server functions are written in PureScript in a server module, which re-exports Solid.Start.UseServer. None of its code reaches the browser. Every value it exports must be a serverFunction, and arguments and results must be Serializable:

module App.Api (module Solid.Start.UseServer, save) where

import Solid.Start.ServerFunction (ServerFunction, serverFunction)
import Solid.Start.UseServer (useServer)

save :: ServerFunction NewTodo Todo
save = serverFunction \todo -> Db.insert todo

Call them from anywhere with call, queryServer or serverAction.

See examples/src/StartMode/Host and examples/src/HackerNews/Host.

Examples

The examples workspace package holds:

  • Counter, TodoMVC: client-side apps;
  • Hydration: server rendering and hydration;
  • StartMode: the smallest full-stack app;
  • HackerNews: typed routes, cached server queries and streamed SSR;
  • Bench: the rows benchmark.
npm run build:example:hackernews
PORT=3000 npm run start:example:hackernews

Development

Requires Node.js 22.12+. PureScript, Spago and purs-tidy are pinned dev dependencies.

npm install
npm run test:all
Script What it runs
npm test client specs (happy-dom) and server specs on Solid's dev build; any Solid diagnostic fails them
npm run test:purescript:es the same specs compiled with purs-backend-es
npm run test:browser-smoke Counter and TodoMVC in Chromium
npm run test:hydration server render in Node, hydration in Chromium
npm run test:start, npm run test:dev the start-mode example built with Vite, and under Vite dev with edits while it runs
npm run test:vite the purs-solid/vite plugin's own logic
npm run test:types props the type checker must accept or reject
npm run test:compiled a fixture with every field kind, from purs and purs-backend-es output, through the runtime path and through compiled templates (vite/compile.mjs): the same server HTML, hydration that claims every element, and the same DOM after each interaction
npm run test:apps:runtime the start-mode and dev suites with compileViews: false
npm run build:site the landing page, guide and API reference (site/) into site/dist; its code samples are compiled regions of site/src
npm run gen:dom regenerates Solid.DOM.HTML, Solid.DOM.SVG and Solid.Internal.Names
npm run format, npm run format:check purs-tidy over the library, tests, examples and site
npm run bench, npm run bench:reference the rows benchmark, and the same app in plain Solid

Performance

The rows benchmark (keyed, after js-framework-benchmark): examples/src/Bench/Rows.purs against the same app in Solid JSX, test/bench/reference/rows.jsx. Medians in headless Chromium, Solid 2.0.0-rc.13:

Operation Solid JSX purs-solid (Vite plugin) purs-solid, runtime path
create 1k rows 12.0 ms 12.4 ms 16.9 ms
replace 1k rows 13.2 ms 14.1 ms 18.1 ms
update every 10th row 2.8 ms 3.3 ms 3.5 ms
swap rows 1.1 ms 1.4 ms 1.3 ms
create 10k rows 128.8 ms 126.7 ms 164.8 ms
bundle (gzip) 24.2 kB 34.6 kB 39.7 kB

Through purs-solid/vite, views compile to the same templates as Solid JSX. On the runtime path (compileViews: false, or builds without the plugin), purs-solid clones templates at runtime: updates cost about the same, and creating DOM is about 1.35x slower.

Modules
Solid.Action
Solid.Async
Solid.Component
Solid.Component.JS
Solid.Context
Solid.Control
Solid.DOM
Solid.DOM.Aria
Solid.DOM.AttrValue
Solid.DOM.HTML
Solid.DOM.SVG
Solid.Errors
Solid.Internal.Action
Solid.Internal.Equality
Solid.Internal.Identity
Solid.Internal.Names
Solid.Internal.Optimistic
Solid.Internal.Props
Solid.Internal.Reply
Solid.Internal.Serializable
Solid.Internal.ServerFunction
Solid.Internal.Setup
Solid.Internal.Store
Solid.Internal.Tracked
Solid.Internal.View
Solid.JSX
Solid.Lifecycle
Solid.Meta
Solid.Owner
Solid.Reactivity
Solid.Root
Solid.Router
Solid.Router.Action
Solid.Router.Path
Solid.Router.Query
Solid.Router.Search
Solid.Setup
Solid.Signal
Solid.Start.Middleware
Solid.Start.RequestEvent
Solid.Start.Response
Solid.Start.ServerFunction
Solid.Start.UseServer
Solid.Store
Solid.Testing
Solid.Utility
Solid.Web
Solid.Web.SSR
Dependencies