6a01e2507a
The local dashboard evaluates a project's hexclave.config.ts in a plain Node
context via jiti. When a config imported a value (e.g. defineStackConfig) from a
framework package like @stackframe/stack / @hexclave/next, jiti executed the
whole SDK (React, server-only, Next internals) and threw, surfacing only as
"Failed to register development environment session (500)".
- Catch jiti load failures in readConfigFile and rethrow a helpful message that
points at the lightweight import path.
- Add a side-effect-free `./config` subpath to the framework packages
(@hexclave/{js,next,react,tanstack-start}/config) that re-exports
defineHexclaveConfig/defineStackConfig + the HexclaveConfig type from
@hexclave/shared/config, with no framework runtime. Users directly depend on
these packages, so the subpath resolves under pnpm strict mode (unlike the
transitive @hexclave/shared/config).
- Point the setup prompt, hand-written docs (docs-mintlify), and the renderer
that auto-writes config files at the new `<pkg>/config` path. Legacy
@stackframe/* packages predate the subpath, so they keep their root import.
Existing config files that import from a package root are upgraded to the
/config path on their next dashboard/CLI sync.
|
||
|---|---|---|
| .. | ||
| 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.