Guides

Learn

• Context: Provide values to a subtree with createContext, read them with useContext, make them reactive, override them.
• Suspense and resources: Load async data with useResource, show loading UI with Suspense, keep old data while refetching, handle failures, update optimistically, and understand how the resource cache works with server rendering.
• Data fetching: Load, refetch, mutate and optimistically update server data with useResource and useOptimistic, and choose between resources and router loaders.
• Error handling: Catch render, effect and resource errors with ErrorBoundary, route errors with catchError, onError and handleError, and recognize ShadowJS error codes.
• Transitions: Keep the current screen while the next one loads with startTransition, useTransition and useDeferredValue. How transitions interact with Suspense, what isPending means, and what runs on the server.
• Styling: Style components with class, classList, inline styles and CSS files, and set up Tailwind CSS 4 with the Vite plugin.

Guides

• State with useStore: Hold single values and deeply nested data in reactive state, update it in every supported form, and know exactly when the DOM and your effects see the change.
• Effects and lifecycle: Run side effects with automatic dependencies, clean them up, control ownership and flush timing, and know what runs on the server.
• Control flow in depth: Show, Switch, For, Index, Dynamic, Portal, Fragment and lazy components, what each one rebuilds, and how fallbacks behave.
• Lists and keys: Render and update lists with For and Index, choose between item references and keys, keep DOM nodes and row state across updates, and make selection O(1) with useSelector.
• SSR, hydration and streaming: Render components to HTML on the server, hand resource data to the browser, and hydrate the markup without recreating a single node.
• Accessibility: Write accessible components with semantic HTML, correct ARIA attribute values, labels, focus management, live regions and keyboard handling.
• Performance: Keep updates proportional to what changed, inspect compiled output, and measure rendering and memory in your application.
• Bundle size: Measure what your bundle ships, what each ShadowJS package costs, and which import patterns and package fields keep it small.
• Benchmarks: The row benchmark behind the numbers on the home page: the app, the machine, the method and every measurement, read from the newest run.
• Security: What ShadowJS escapes, blocks and validates for you, what stays your responsibility, and how to handle CSP, environment variables and tokens.
• Extending ShadowJS: Build your own hooks, reactive primitives and control-flow components from the same extension APIs the built-ins use, with the same ownership, scheduling and diagnostics.
• MDX and Markdown: Write pages in MDX with @shadow-js/vite/mdx, mount them as components, replace Markdown elements, read frontmatter, build a content collection, and know what the plugin does in dev, build and SSR.
• Dark mode: Provide a persisted light and dark theme through context, apply it to the document root, and follow the system preference until the user chooses.
• Debounced search: Build a search box that waits for a pause in typing, aborts superseded requests, and shows loading, empty and error states.
• Optimistic updates: Show a new todo the moment it is submitted, confirm it when the real list updates, and roll it back with an error message when the save fails.
• Infinite list: Append pages to a keyed list when a sentinel scrolls into view, without recreating the rows that are already on screen.
• Sortable, filterable table: Build a table that filters with a text input, sorts by clicking a column header, reports the sort with aria-sort, and reorders its existing rows instead of recreating them.
• Form validation: Build an accessible signup form with a store for the values, derived error messages, touched state and a submit button that follows validity.
• Modal dialog: Build an accessible modal dialog with a portal, focus management, Escape and backdrop dismissal, and a Tab focus trap.
• Accessible tabs: Build a tab set with ARIA roles, a roving tabindex, arrow-key navigation with wrap-around, and hidden panels, and test it with keyboard events.
• Keyboard shortcuts: Register global keyboard shortcuts with a hook that owns one document listener, matches modifiers exactly and skips text fields.
• Undo and redo: Add undo and redo to a store-backed document by pushing snapshot() copies onto a capped history and restoring them with reconcile(), so unchanged items keep their identity and their DOM rows.

Tooling

• Compiler: Read what compile() emits, know which literal and root rewrites it applies, write compiler plugins that run in the build, and pass them to the Vite plugin.
• Vite plugin: Add @shadow-js/vite to a Vite app, know which files it compiles and which it skips, how dev, build, SSR and Vitest differ, what its options do, and how compile errors and bad options are reported.
• Create a ShadowJS app: Scaffold a ShadowJS app with npm create shadow-app - the flags, the spa and dusk templates, the add-ons, the package manager choice, adding features later, upgrading, and the fixes for the usual failures.