Skip to main content

Server-Side Rendering

Guidelines and patterns for SSR and hydration safety in Moraine and SolidStart.

View as Markdown

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:

import { createId } from 'moraine/utils'

function CustomField() {
  const id = createId() // Returns an accessor with the same ID on the server and the client

  return (
    <div>
      <label for={id()}>Username</label>
      <input id={id()} type="text" />
    </div>
  )
}

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 onMount or event handlers. For browser-only content, keep the server and initial client tree identical, then reveal that content after mounting.
import { Button, Dialog } from 'moraine'

export function UserDialog() {
  return (
    <Dialog>
      <Dialog.Trigger as={Button}>Edit Profile</Dialog.Trigger>
      {/* Content portals to the body on the client only, so hydration matches */}
      <Dialog.Content title="Edit Profile">
        <p>Update your profile details below.</p>
      </Dialog.Content>
    </Dialog>
  )
}

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:

import { Tabs } from 'moraine'

export function SettingsTabs() {
  return (
    <Tabs
      items={[
        {
          value: 'account',
          label: 'Account',
          get content() {
            return <p>Account settings</p>
          },
        },
        {
          value: 'notifications',
          label: 'Notifications',
          get content() {
            return <p>Notification settings</p>
          },
        },
      ]}
    />
  )
}

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:

import { createMediaQuery } from 'moraine/utils'
import { Show } from 'solid-js'

export function Navigation() {
  // false on the server and during hydration; follows matchMedia after mount
  const isDesktop = createMediaQuery('(min-width: 1024px)', false)

  return (
    <nav>
      <Show when={isDesktop()} fallback={<MobileDrawer />}>
        <DesktopNav />
      </Show>
    </nav>
  )
}

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-height start 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#

  1. Avoid window or document in the component body: Read window dimensions, localStorage, or DOM properties inside onMount or user event handlers (onClick, onInput), never while the component runs.
  2. Deterministic initial state: Initialize controlled signals with static defaults that the server evaluates the same way as the client.
  3. Use Moraine primitives for overlays: Built-in primitives already manage portals, scroll locks, and focus containment, so you do not need custom SSR guards.