mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-13 21:01:21 +08:00
1cbbd5a4e2
## Problem
A user setting up Hexclave in a new Next.js project with a coding agent
hit:
> **HexclaveTheme error:** Cannot render a `<style>` outside the main
document without knowing its precedence and a unique href key...
The agent eventually fixed it by moving
`HexclaveProvider`/`HexclaveTheme` from *wrapping* the `<html>` tag to
*inside* it.
## Root cause
The Next.js `layout.tsx` example in the setup prompt
([`ai-setup-prompt.ts`](packages/shared/src/ai/unified-prompts/skill-site-prompt-parts/ai-setup-prompt.ts))
returned **just** the providers, with no `<html>`/`<body>`:
```tsx
export default function RootLayout({ children }) {
return (
<HexclaveProvider app={hexclaveServerApp}>
<HexclaveTheme>{children}</HexclaveTheme>
</HexclaveProvider>
);
}
```
But a Next.js root layout is [**required** to render `<html>` and
`<body>`](https://nextjs.org/docs/app/api-reference/file-conventions/layout).
When an agent reconciles this incomplete snippet with an existing
layout, the snippet shows the providers as the outermost element — so it
wraps the existing `<html>` with them. That puts `HexclaveTheme`'s
hoisted `<style>` outside the document, which React refuses to render →
the error above.
Every other framework example in the prompt is complete (the TanStack
Start one explicitly separates the `<html>`/`<body>` shell from the
providers); only the Next.js one was ambiguous.
## Fix
- Show the full document shell with the providers nested **inside
`<body>`**.
- Add an explicit note: the root layout must render `<html>`/`<body>`,
and the providers must go inside `<body>` — do not wrap `<html>`.
- Drop the unused `Suspense` import (Suspense is covered in the separate
boundary step; per the Next.js docs you should not add `<head>`
manually, so the example stays minimal).
- Regenerated `setup.mdx`, `llms-full.txt`, and the agent-reminder
snippets from the prompt source.
This source feeds the CLI `init` prompt, `skill.hexclave.com`
(`llms-full.txt`), and the generated docs, so the fix propagates
everywhere.
## Verification
- `turbo run typecheck` — `@hexclave/shared` and all other packages
pass. (3 pre-existing failures in
`dashboard`/`example-demo-app`/`internal-tool` are stale `.next`
validators referencing the old `[...stack]` route name, unrelated to
this change.)
- `turbo run lint` — `@hexclave/shared` and `@hexclave/docs-mintlify`
pass.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes the Next.js layout example in the setup prompt to include the
required <html>/<body> shell and place
`HexclaveProvider`/`HexclaveTheme` inside `<body>`, preventing the React
style-outside-document error. Also makes the warning before the example
a clear, complete sentence that leads into the correct setup.
- **Bug Fixes**
- Updated Next.js example in `ai-setup-prompt.ts` to render
`<html>`/`<body>` and nest providers inside `<body>`; added a clear “do
not wrap `<html>`” note.
- Reworded the warning before the example to end as a full sentence and
introduce the correct snippet.
- Removed unused `Suspense` import.
- Regenerated `docs-mintlify/guides/getting-started/setup.mdx`,
`docs-mintlify/llms-full.txt`, and snippets (home prompt island, agent
reminders) to propagate the change.
<sup>Written for commit
|
||
|---|---|---|
| .. | ||
| api | ||
| guides | ||
| images | ||
| openapi | ||
| sdk | ||
| snippets | ||
| .gitignore | ||
| apps-sidebar-filter.js | ||
| code-language-labels.js | ||
| docs.json | ||
| index.mdx | ||
| llms-full.txt | ||
| migration.mdx | ||
| package.json | ||
| README.md | ||
| style.css | ||
docs-mintlify
How to run the Mintlify docs preview locally from this repository.
Prerequisites
-
Node.js
>=20.17.0 -
pnpm -
Repository dependencies installed (
pnpm installfrom repo root) -
OpenAPI specs in
openapi/are committed to git. Hosted Mintlify cannot run monorepo codegen on deploy, so these files must be present in the repo for production docs.When you change API route OpenAPI metadata, regenerate and commit the four specs from the repo root:
pnpm run --filter @hexclave/backend codegen-docs git add docs-mintlify/openapi/That writes
client.json,server.json,admin.json, andwebhooks.jsonintodocs-mintlify/openapi/(and intodocs/openapi/for the legacy Fumadocs app). CI fails ifpnpm codegenproduces different output than what is committed (see root lint-and-build workflow).
Run locally
From the repository root:
pnpm -C docs-mintlify run dev
This starts Mintlify in docs-mintlify on http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}04 (for example, http://localhost:8104 with the default prefix).
From inside docs-mintlify, you can also run:
pnpm dev
Useful variants:
# Override the default port
pnpm -C docs-mintlify run dev -- --port 3333
# Skip OpenAPI processing for faster iteration
pnpm -C docs-mintlify run dev -- --disable-openapi
Search + assistant in local preview
If you want local search and the Mintlify assistant:
pnpm -C docs-mintlify run login
pnpm -C docs-mintlify run status
Then re-run pnpm -C docs-mintlify run dev.
Package scripts
From repo root:
pnpm -C docs-mintlify run lint
pnpm -C docs-mintlify run typecheck
pnpm -C docs-mintlify run build
pnpm -C docs-mintlify run clean
lint runs both mint validate and mint broken-links.