← Skills

SolidJS SSR

Two skills with strong opinions on server-rendered SolidJS. One keeps edits from breaking hydration. The other finds the mismatch fast when they do.

Stage
Build
Skills
solid-ssr-change-safety ↗solid-ssr-hydration-debug-playbook ↗
Size
177 lines · 4 files
Updated
Sep 11, 2026

What it does

Most of my newer apps are SolidStart. In a server-rendered Solid app, the classic bug is a hydration mismatch. The server renders one DOM tree, the client builds a different one, and you get template2 is not a function or content that flashes and disappears.

These aren't steps in a workflow. They are strong opinions about how to write this code, so the agent writes it the safe way the first time.

Change safety

The core rule: the server-rendered tree and the first client render must match, node for node. Change attributes, text, and content after mount, never the shape.

  • No render-time branches on window, viewport size, time, or random values.
  • Don't pass JSX elements through props and insert them conditionally inside a shared shell.
  • Give each independent async resource its own Suspense island.
  • Keep list ordering deterministic on both sides.

Debug playbook

When it breaks anyway: comment out a large suspect subtree, confirm hydration is stable, then turn chunks back on one at a time until the mismatch returns. Rewrite only that chunk. For async pages, reduce the route to static content and bring each async section back on its own.

What it made

A solution note for a Solid hydration crash: Problem and Symptoms

A write-up from Pluck UI. Removing the filter bar fixed the page. Rendering a single popover broke it again. That narrowing is the debug playbook. The change-safety rules warn about the same pattern: JSX passed through props into a shared wrapper.

It's working if

  • A hard refresh shows no hydration warnings.
  • The fix touches one chunk, not the whole page.

Read the skill

These are the files the agent loads, copied from byronwall/.agents. Copy one file, or download the folder as a ZIP and drop it into your own skills folder.

solid-ssr-change-safety

2 files · ready to copy or download

SKILL.mdsolid-ssr-change-safety/SKILL.md
---
name: solid-ssr-change-safety
description: Prevent SolidJS SSR hydration mismatches during frontend edits. Use when changing components that render on both server and client, especially markdown renderers, conditional JSX, list rendering, and DOM-structure-heavy UI.
---

# Solid SSR Change Safety

## Goal

Keep the server-rendered DOM tree identical to the initial client hydration tree.

## Core Rule

Match node existence and hierarchy between SSR and first client render.
Only mutate attributes/text/content after mount.

## Change Guardrails

- Keep the same JSX element structure for SSR and initial client render.
- Do not pass already-created JSX elements through ordinary props and then conditionally insert them inside SSR-rendered layout shells. In Solid hydration this can surface as `template2 is not a function`. Prefer data props, component references, render callbacks invoked in one stable branch, or explicit call-site slots with stable wrapper nodes.
- Avoid render-time branches based on `window`, `document`, viewport size, time, random values, or client-only APIs.
- Treat select/menu/popover portal behavior as hydration-sensitive.
  - Prefer in-tree rendering (`skipPortal`/non-portalled mode) on SSR route surfaces by default.
  - Only enable portal rendering when required by clipping/stacking constraints, then hard-refresh verify parity.
- Avoid returning different element types for the same markdown node (`code` must stay `code`, `pre` must stay `pre`).
- Defer enhancements to `onMount` and use client-side DOM mutation for progressive enhancement.
- Prefer setting `id`, `class`, `data-*`, `innerHTML`, and event hooks post-mount over changing JSX tree shape.
- Preserve stable wrapper nodes when adding buttons/overlays; hide/show after hydration with attributes/CSS.

## Async Data Guardrails (High Signal)

- Prefer separate `Suspense` islands for independent async resources.
  - Example: if one section uses `createAsync(fetchA)` and another uses `createAsync(fetchB)`, do not mix both sections under one shared `Show`/list subtree unless they are intentionally coupled.
- Keep each async section’s fallback/empty states local to that section.
  - Avoid one section’s unresolved state changing the DOM shape of another section.
- Avoid mixing multiple async accessors inside one list-render gate.
  - Gate one list with one resolved accessor where possible.
- Keep list ordering deterministic across server and client.
  - Prefer stable lexical comparisons (`a < b ? -1 : 1`) over locale-sensitive comparators when hydration stability matters.

## Safe Workflow

1. Identify where SSR output is generated.
2. Keep a minimal baseline renderer that is hydration-safe.
3. Add enhancement logic only in `onMount`.
4. Ensure fallback markup is identical server/client pre-hydration.
5. Hard refresh and verify no hydration mismatch.
6. For async-heavy pages, validate each async section in isolation before recombining.

## Red Flags

- Hydration errors like `template2 is not a function` or missing hydration keys.
- `template2 is not a function` after adding a panel/header/icon prop, especially `icon={<Icon />}` or other JSX-valued props that are conditionally rendered by a shared shell.
- Brief flash of content before crash.
- Failures that disappear when select/content portal is disabled (`skipPortal`) indicate portal hydration ownership mismatch.
- Component works only when custom renderer is disabled.
- Hash/query navigation state conflicts that change rendered tree at load.
- Page works when one async section is removed, but fails when two async sections render in the same boundary.

## Recent Incident Notes (Vacation Planner)

- `template2` failures were triggered by pre-hydration tree-shape changes from derived "effective" selectors that changed major `Show` branches before hydration completed.
  - Rule: avoid introducing fallback memos that can switch whole route subtrees during initial hydration.
  - Prefer stable signal defaults (or route-level serialized state) that do not alter branch ownership between SSR and first client pass.
- `SimpleSelect` portal rendering increased hydration fragility in this app.
  - Rule: default overlay/select wrappers to non-portalled in SSR surfaces unless a portal is required.
  - If portal is required, validate hard-refresh SSR parity explicitly.
- Ark/Zag `Splitter` surfaced `ReferenceError: document is not defined` in server/HMR cleanup paths.
  - Rule: when SSR errors mention `@zag-js/splitter` cleanup (`removeGlobalCursor` / `clearGlobalCursor`), treat Splitter as the first suspect and swap to static CSS split as containment.
- Color palette debugger hit `template2 is not a function` when a reusable `Panel` accepted `icon?: JSX.Element` and inserted `props.icon` inside a conditional header.
  - Rule: reusable SSR shells should own their header tree directly or accept serializable/icon-name data, not conditionally reinsert pre-created JSX nodes.

## Example Prompts

- "Use the Solid SSR safety skill and refactor this markdown renderer so hydration is stable while keeping features."
- "Before I merge this frontend change, run an SSR safety pass and list any DOM-tree mismatch risks."
- "Apply hydration-safe progressive enhancement rules to this Solid component and avoid render-time client-only branches."

## Verification

Run `pnpm type-check`.
Use hard-refresh/manual navigation checks for hydration behavior.
markdown82 lines

solid-ssr-hydration-debug-playbook

2 files · ready to copy or download

SKILL.mdsolid-ssr-hydration-debug-playbook/SKILL.md
---
name: solid-ssr-hydration-debug-playbook
description: Troubleshoot and resolve SolidJS hydration mismatches using a comment-out and re-enable playbook. Use when seeing hydration errors, template crashes, or server/client DOM mismatch behavior.
---

# Solid SSR Hydration Debug Playbook

## Goal

Find the exact mismatch source fast, then restore features with targeted hydration-safe fixes.

## Isolation Method

Use coarse-to-fine comment/backout isolation.

1. Disable a large suspect subtree.
2. Confirm hydration stabilizes.
3. Re-enable one chunk at a time.
4. Stop when mismatch returns.
5. Rewrite only that chunk with hydration-safe patterns.

## Practical Sequence (General)

1. Disable custom render overrides first (high signal).
2. Restore plain baseline render path.
3. Re-enable headings only.
4. Re-enable `code` behavior only.
5. Re-enable `pre` wrappers/controls.
6. Re-enable mermaid/client-only visuals last.

## Practical Sequence (Async Route Pages)

1. Reduce route to static content (no `createAsync`, no list rendering).
2. Re-enable one async section only.
3. Re-enable second async section only.
4. If each works alone but fails together, split into separate `Suspense` islands.
5. Re-enable list iteration in steps:
   - scalar render (`count` only)
   - list loop with native elements
   - styled/components wrappers
6. Keep each suspect step as a single small delta so regressions are attributable.

## Fix Patterns

- Keep SSR and initial client DOM identical.
- Move dynamic branching to `onMount` only when truly client-only behavior is needed.
- Prefer one async resource per `Suspense` boundary for unrelated sections.
- Replace shared mixed-resource list gates with section-local gates.
- Keep list ordering deterministic across SSR/client.
- If `grouped().length` works but `For each={grouped()}` fails, suspect row subtree hydration ownership and isolate row markup/component boundaries.

## Debug Signals

- `template2 is not a function` with content flash: likely tree mismatch.
- `Hydration Mismatch. Unable to find DOM nodes for hydration key ...` with `data-source-loc`: use the source location to isolate that exact JSX subtree first.
- Routes with Ark/overlay selects that stabilize when `skipPortal` is enabled: treat portal ownership as the first suspect.
- Works when one section is removed, fails when both are present: boundary interaction problem.
- Works until one feature re-enabled: culprit localized.
- `ReferenceError: document is not defined` with `@zag-js/splitter` frames (`removeGlobalCursor` / `clearGlobalCursor`): Splitter machine cleanup is running in server context.

## Recent Incident Pattern (Vacation Planner)

Use this order for similar failures:

1. Check for framework machine stack traces first.
   - If stack includes `@zag-js/splitter`, remove/gate Splitter immediately and verify with static CSS columns.
2. Revert pre-hydration "effective state" memos that can change `Show` gates.
   - Example: derived IDs that pick first record (`selected || firstItem`) caused route subtree ownership flips during hydration.
3. Disable portalling in select/popover wrappers on SSR routes.
   - Keep overlays in-tree first; only re-enable portals after hydration is stable.
4. Re-run verification in this order:
   - hard refresh `/`
   - direct deep-link URL load
   - in-app navigation between tabs/views
   - `pnpm type-check`

## Example Prompts

- "Use the hydration debug playbook: comment out risky chunks, isolate the mismatch, then re-enable features incrementally."
- "I get a Solid hydration error on refresh. Apply the backout-and-restore workflow and fix only the culprit area."
- "Run a coarse-to-fine SSR mismatch triage on this component and propose targeted post-mount fixes."

## Completion Criteria

- Hard refresh loads without hydration error.
- Server render and client hydration both succeed.
- Required features restored incrementally.
- No broad rewrites outside culprit area.

## Verification

Run `pnpm type-check`.
Validate with hard refresh, direct URL load, and in-app navigation.
markdown93 lines