Server-Side Rendering
Guidelines and patterns for SSR and hydration safety in Moraine and SolidStart.
Moraine supports SolidJS server rendering and hydration. Your application must still render the same initial state on the server and client, defer browser-only work, and create conditional JSX only when its branch renders.
This guide covers IDs, portals, content ownership, responsive state, and locale.
Deterministic Hydration IDs#
Accessible components need matching IDs between elements, for example a trigger’s aria-controls and a content panel’s id. Random IDs differ between server and client and cause hydration mismatches.
Use createId from moraine/utils to generate IDs that match across server rendering and client hydration. It builds on Solid’s createUniqueId. Pass an accessor as the first argument to prefer a caller-provided ID, and a prefix as the second:
Hydration-Safe Portals#
Overlays such as Dialog, Sheet, Drawer, Popover, Tooltip, DropdownMenu, and ContextMenu render their content through a Solid <Portal>. The portal mounts into the body of the trigger’s document, or into the mount element when you set one.
In Moraine:
- Overlays default to closed, so the server output contains only the trigger.
- Portals emit no server markup, so overlay content renders only on the client, even when an overlay starts open. The server and initial client trees match.
- Read browser APIs in
onMountor event handlers. For browser-only content, keep the server and initial client tree identical, then reveal that content after mounting.
Conditional JSX and item content#
Create JSX inside the branch that renders it. For collection items with optional panels, use a
content getter so an inactive panel does not consume hydration IDs before it mounts:
The same rule applies to JSX panel data in Accordion and Stepper. Keep server and client item order and initial selection equal.
Render-function children#
Some props accept either JSX or a function (props) => JSX.Element, including children of
Button, ToggleButton,
CopyButton, Slider,
BaseSelect trigger and item, Dialog,
BaseDialog, Sheet, and Drawer content, and
Resizable handle.
Declare the function parameter even when the callback does not use it. TypeScript still accepts a zero-argument function for that prop type. Moraine calls a zero-argument function as an accessor and does not mount it with a component boundary. Use a parameter when the callback depends on a Solid owner, lifecycle, or owned reactive computation.
Field children call every function with the field state, with or without a declared parameter. The call is tracked, so signals read directly in the function body re-run it.
Responsive Queries in SSR#
Browser APIs such as window.matchMedia do not exist on the server. A component that renders different layouts by screen width needs a deterministic server default.
Moraine’s createMediaQuery takes a defaultValue (default false) that is the state during SSR and the first client render. It updates from matchMedia after mount:
Transition Presence & Exit Lifecycles#
Solid’s <Show> unmounts elements as soon as its condition becomes false. Moraine components use createTransitionPresence internally to keep exiting overlays mounted while CSS exit animations run.
During server rendering:
- Hidden or transitioning elements keep deterministic closed states.
- Animation variables such as
--mo-collapsible-content-heightstart at safe initial values (0px) without DOM measurement.
Locale and Direction#
MoraineProvider renders the same locale on the server and during hydration. SSR and the first client render use en-US. A root provider then follows navigator.language unless you set locale or detectLocale={false}. To render localized text on the server, pass locale from a cookie or an Accept-Language header. The provider’s dir prop changes component behavior but does not set a dir attribute; set dir on <html> for layout. See the Localization guide.
Best Practices for SSR Safety#
- Avoid
windowordocumentin the component body: Read window dimensions,localStorage, or DOM properties insideonMountor user event handlers (onClick,onInput), never while the component runs. - Deterministic initial state: Initialize controlled signals with static defaults that the server evaluates the same way as the client.
- Use Moraine primitives for overlays: Built-in primitives already manage portals, scroll locks, and focus containment, so you do not need custom SSR guards.