firsthand

Firsthand documentation

Start with the guide if you are learning the framework, the reference if you are looking something up, and the ADRs if you want to know why something is the way it is.

Guide

Read in order the first time; each page assumes the ones before it.

#	Page	What it covers
1	Getting started	Install, configure, first component, how the pieces fit
2	Reactivity	Signals, computeds, effects, batching, when the DOM updates
3	Components	Running once, props, children, what replaces re-rendering
4	Rendering	Conditionals, lists and keys, fragments, portals, refs
5	Context and lifecycle	Sharing values, cleanup, error boundaries, the owner tree, async
6	Events and forms	Delegation, custom events, controlled inputs, validation
7	Styling	Plain CSS, class, and @firsthandjs/styled
8	Routing	Nested routes, params, links, code loaded on demand
9	Data	Resources, actions, tags, the cache, REST and GraphQL clients
10	Web components	Using them, and publishing your own components as custom elements
11	React interop	MUI and friends, and what the bridge costs
12	Internationalisation	i18next and friends, made reactive
13	Testing	Vitest, Playwright, Storybook, and what is worth asserting
14	Devtools	See what updates what, why it ran, and what the cache did
15	Performance	What is fast by construction, what is not, and how to measure
16	Building and deploying	The compiler, bundlers, chunking, hosting
17	Server rendering	Rendering to markup, hydration, and data that crosses the wire

Reference

One page per package, listing every export with its signature.

Package	Size (gzip)	What it is
@firsthandjs/core	2.36 kB	Signals, computeds, effects, context, owners
@firsthandjs/dom	4.20 kB	Components, rendering, elements, lists, portals
@firsthandjs/jsx-runtime	0.59 kB	JSX types, and the runtime fallback
@firsthandjs/server	server only	Rendering to markup, for a server
@firsthandjs/compiler	build only	The TSX transform and the bundler plugin
@firsthandjs/deep	0.72 kB	Deep reactivity: every property is a signal
@firsthandjs/devtools	6.29 kB	Experimental. What updates what, why, and when
@firsthandjs/i18n	0.37 kB	i18next and friends, made reactive
@firsthandjs/router	3.36 kB	Typed routes, links, history, lazy routes
@firsthandjs/data	3.84 kB	Resources, actions, tags, the cache, fetch client
@firsthandjs/data-axios	0.58 kB	Axios, as a client
@firsthandjs/data-urql	0.58 kB	urql, as a client
@firsthandjs/data-apollo	0.65 kB	Apollo, as a client, and its observables
@firsthandjs/styled	1.98 kB	CSS-in-JS with custom properties
@firsthandjs/react	0.66 kB	React components inside Firsthand, directly or not
@firsthandjs/testing	dev only	mount, cleanup, leak probes

Sizes are measured by npm run build and published in the README with everything else.

Everything else

• API conventions — the naming and behaviour rules every package follows, so you can guess an API before reading it.
• Architecture — how the packages fit together, and the compiler/runtime protocol.
• ADRs — every decision with performance or semantic consequences, including the ones measurement proved wrong.
• Performance plan and code rules — the limits a tool enforces and where each number came from — the risk register — what was predicted, and what actually happened.

Example applications

• examples/ — one idea each: counter, todo, context, portal, query, router, and a 100 000-row table.
• integrations/interop/ — MUI, Shoelace and styled components on one page.
• integrations/storybook/ — a working Storybook.

This site is open source. Improve this page.