Docs

Frontend gotchas

Nifra owns the server/client seam, while each frontend framework owns its own reactivity and lifecycle rules. The frontend catalog connects those two layers without pretending Nifra can replace the framework's compiler or linter.

Use the same catalog from every surface

nifra frontend is the human CLI and nifra_frontend is the MCP tool. Both select the same entries. Pass --json to the CLI, or read the MCP result's structuredContent, to receive a stable result with schemaVersion, an optional top-level adapter, match status, and entries. Entries include their adapters and may omit framework version ranges, categories, or source URLs.

Shell
# Browse all entries
nifra frontend

# Search a framework and symptom
nifra frontend solid "list reorder state"

# Give an agent stable JSON with versions and source links
nifra frontend vue "watcher never runs" --json

# The same catalog is available over MCP, as text plus structuredContent
nifra_frontend({ adapter: "react", symptom: "hydration mismatch" })

What Nifra reports

  • Shared seam cases: server-only imports, hydration determinism, typed loader data, duplicate runtimes, and stable list identity.
  • React and Preact: effect dependencies and cleanup, hydration browser reads, state identity, compat boundaries, and runtime duplication.
  • Solid: tracked reads, props and stores, For versus Index, and owner cleanup.
  • Vue: refs in script, watch sources and traversal, reactive props, and SSR hydration.
  • Svelte: runes, keyed each blocks, effect teardown, and browser-only SSR reads.
  • CSP and browser: React Activity hydration, inline styles under a strict Content-Security-Policy, and WebKit's handling of streamed module scripts. Server-runtime differences are in runtime differences.

Version-sensitive advice

Ecosystem entries may include the framework versions covered by the advice and link to the framework's documentation. When a major version changes the rule, add a new entry or update the version range with a fixture. Keep high-confidence, statically provable rules in nifra check; use this catalog for symptoms that need context or an ecosystem linter.

Contributing a gotcha

Add a broken and fixed fixture, a symptom users actually report, the exact cause, a safe fix, and an authoritative source. If the issue is Nifra's own boundary, add a check code and a regression test. If it belongs to React, Preact, Solid, Vue, or Svelte, link the ecosystem linter or compiler instead of duplicating its entire rule set.