Found by the docs audit of the first-run path (#10563).
What is wrong
content/docs/getting-started/examples.mdx "Quick Run" (lines 51-56) tells a
stranger to run:
git clone https://github.com/objectstack-ai/objectstack.git
cd objectstack
pnpm install
pnpm dev:showcase # or: pnpm dev:todo / pnpm dev:crm
pnpm build is missing, and it is required.pnpm dev:showcase begins with
node scripts/check-dev-prereqs.mjs, which refuses to boot an unbuilt workspace.
Measured, on a fresh clone with no node_modules
$ node scripts/check-dev-prereqs.mjs ; echo "EXIT=$?"
✗ The workspace is not built — 1 unmet precondition, not a list of problems.
67 of 67 workspace packages declare an entry point under dist/ that is not on disk:
@objectstack/cli packages/cli/dist/index.js
@objectstack/client packages/client/dist/index.mjs
@objectstack/client-react packages/client-react/dist/index.mjs
… and 64 more
Fix:
pnpm install && pnpm build
EXIT=1
Nothing supplies the build implicitly: the root package.json has no
postinstall, and prepare is node scripts/setup-git-hooks.mjs only.
The repo's own README.md:210-212 documents the correct sequence:
pnpm install # Node 22+, pnpm 8+ (corepack enable)
pnpm build # build all packages
pnpm dev # run the showcase example (REST + Console on :3000)
So the docs site contradicts the README on the very first command a newcomer runs.
The standalone tabs are worse
The per-example "Standalone" tabs have the same gap and bypass the gate,
because check-dev-prereqs.mjs guards only the root dev:* scripts:
examples.mdx:107-109 — cd examples/app-todo && pnpm devexamples.mdx:283-285 — cd examples/app-showcase && pnpm dev
Both run objectstack dev directly against an unbuilt workspace, which fails with
exactly the misleading cascade check-dev-prereqs.mjs was written to prevent
(its own docblock cites #5726: a datasource: connect failed whose two suggested
fixes are both wrong for this cause, then 20+ TS errors that read like real
contract drift and are pure stale-dist artefact).
The second pnpm install block on the page (lines 256-259) is fine — that one is
for the external hotcrm repo, which needs no workspace build.
Note
pnpm build alone still does not produce the Console SPA at /_console/:
packages/console/dist is gitignored and built only by scripts/build-console.sh
(pnpm objectui:build), never by turbo run build — see the docblock of
scripts/check-console-sha.mjs. Whether the Quick Run should mention that too is
a judgement call for whoever fixes this.
Back-link: #10563
Found by the docs audit of the first-run path (#10563).
What is wrong
content/docs/getting-started/examples.mdx"Quick Run" (lines 51-56) tells astranger to run:
pnpm buildis missing, and it is required.pnpm dev:showcasebegins withnode scripts/check-dev-prereqs.mjs, which refuses to boot an unbuilt workspace.Measured, on a fresh clone with no
node_modulesNothing supplies the build implicitly: the root
package.jsonhas nopostinstall, andprepareisnode scripts/setup-git-hooks.mjsonly.The repo's own
README.md:210-212documents the correct sequence:So the docs site contradicts the README on the very first command a newcomer runs.
The standalone tabs are worse
The per-example "Standalone" tabs have the same gap and bypass the gate,
because
check-dev-prereqs.mjsguards only the rootdev:*scripts:examples.mdx:107-109—cd examples/app-todo && pnpm devexamples.mdx:283-285—cd examples/app-showcase && pnpm devBoth run
objectstack devdirectly against an unbuilt workspace, which fails withexactly the misleading cascade
check-dev-prereqs.mjswas written to prevent(its own docblock cites #5726: a
datasource: connect failedwhose two suggestedfixes are both wrong for this cause, then 20+ TS errors that read like real
contract drift and are pure stale-
distartefact).The second
pnpm installblock on the page (lines 256-259) is fine — that one isfor the external
hotcrmrepo, which needs no workspace build.Note
pnpm buildalone still does not produce the Console SPA at/_console/:packages/console/distis gitignored and built only byscripts/build-console.sh(
pnpm objectui:build), never byturbo run build— see the docblock ofscripts/check-console-sha.mjs. Whether the Quick Run should mention that too isa judgement call for whoever fixes this.
Back-link: #10563