feat: docs/brand polish, runtime portability hardening, and monorepo restructure#6
Merged
Merged
Conversation
…restructure
Squash of two parallel tracks on this branch:
LIBRARY (changesets cover details — see .changeset/*.md)
- readEnv() falls back to {} when `process` is undeclared so isolate
runtimes (Workers without nodejs_compat, Edge) work out of the box
- replace lodash.merge with defu — fixes silent shallow-merge regression
on V8 isolate runtimes where lodash isPlainObject collapses across realms
- rename <ClientEnv /> → <EnvScript /> in @vlandoss/env/react
- rename @vlandoss/env/node entrypoint → @vlandoss/env/fs
- README + docs polish (tone, brand v2, typography, codeblock theme)
MONOREPO TOOLING
- adopt mise as the single task orchestrator; drop turbo
- examples/* leave the pnpm workspace and become runtime-isolated:
each one declares its own runtime (node/bun/deno/wrangler) and
package manager (pnpm/bun) in its own mise.toml, has its own
lockfile, its own biome.json, and consumes @vlandoss/env from a
packed tarball generated by `mise run env:pack`
- pnpm workspace reduced to package + docs
- root package.json carries no scripts — mise is the only task API
- per-example package.json carries no scripts — mise is the only task API
- lefthook.yml inlined (no longer pulls turborepo preset)
- CI migrated to jdx/mise-action@v2 in both workflows
EXAMPLES
- 9 examples, each runtime-isolated, each green via `mise run test:e2e`
- backend-node: pnpm
- backend-bun: bun
- backend-deno: bun (deno's package manager can't extract local
file: tarballs; bun does it cleanly with a flat layout deno can read
via nodeModulesDir: "manual")
- 6 web/edge examples: pnpm
DOCS
- root README slimmed
- new CONTRIBUTING.md (branch / commit / changeset conventions, PR flow)
- new DEVELOPMENT.md (setup, mise tasks reference, troubleshooting,
the two-layer model: pnpm workspace for lib+docs, mise-isolated examples)
- examples/README.md rewritten around the runtime-isolation model
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The package has browser-mode vitest tests for the React component (via
@vitest/browser-playwright + chromium). Before the monorepo restructure
they worked because `playwright` was a root devDep and pnpm hoisted it.
After moving playwright to per-example devDeps, the package lost access
to the browser binary and `mise run lib:test` started failing in CI.
- package/package.json: add `playwright` 1.59.1 as devDep
- .github/workflows/ci.yml: install Chromium before `mise run lib:test`
- lefthook.yml: simplify tscheck to `pnpm rr tsc` (workspace-recursive)
and widen the glob to `{package,docs}/**` so docs type regressions
are caught pre-commit too
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…mple `pnpm pack` produces a non-deterministic tarball (mtime / platform-dependent gzip bytes), so the integrity hash committed in each example's pnpm-lock.yaml won't match the hash of a freshly packed tarball in CI. The default `--frozen-lockfile` in CI then aborts with ERR_PNPM_TARBALL_INTEGRITY. The tarball is ephemeral by design — `mise run env:pack` regenerates it on every install. `--no-frozen-lockfile` keeps the rest of the lockfile pinned (hono, react, vite, etc.) but lets pnpm refresh the local tarball hash silently. CI doesn't commit the mutation, so the committed lockfile stays as the canonical snapshot. bun-based examples (backend-bun, backend-deno) were not affected — bun doesn't verify the hash of a local `file:` tarball the same way. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…tier limit Replace fumadocs-core/highlight in the landing-page server fn with a shiki/core highlighter that only loads the typescript grammar and the vitesse-dark theme. The previous import pulled the full shiki bundle (~300 language grammars) into the SSR closure, which alone exceeded the Worker size limit. Also drop Mermaid: the single <Mermaid /> usage in concepts/overview is replaced by a plain ASCII flow, and the component plus the mermaid dep are removed — that lifts cytoscape, dagre, graphlib and the whole diagram chunk set out of the Worker. Worker size (gzip): 3.65 MiB → 820 KiB. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
Preview releaseLatest commit: Some packages have been released:
Note Use the PR number as tag to install any package. For instance: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two parallel tracks landed on this branch:
.changeset/*.md(5 changesets).examples/*truly runtime-isolated. Pure tooling/docs work —package/src/untouched, no changeset needed.Library changes (see changesets for details)
readEnv()falls back to{}whenprocessis undeclared (Workers withoutnodejs_compat, Edge)lodash.merge→defu— fixes silent shallow-merge regression on V8 isolate runtimes<ClientEnv />→<EnvScript />in@vlandoss/env/react@vlandoss/env/nodeentrypoint →@vlandoss/env/fsMonorepo restructure
package.jsonand per-examplepackage.jsoncarry no scripts; everything is amise run <task>. Same contract for devs and CI.examples/*left the pnpm workspace. Each one declares its own runtime + package manager inmise.toml, has its own lockfile, its ownbiome.json, and consumes@vlandoss/envfrom a tarball generated bymise run env:pack. No more workspace cheating — each example is a real consumer.package+docs; turbo brought no value at that scale.lefthook.ymlinlined (no longer pulls the turborepo preset).jdx/mise-action@v2in both workflows; the e2e matrix usesworking_directory: examples/<name>so each job provisions only the runtime that example needs.mise run test:e2e: 38 tests across Node, Bun, Deno, Cloudflare Workers, Next.js Edge, 2 Vite SPAs, React Router 7, TanStack Start.New docs
CONTRIBUTING.md— branch / commit / changeset conventions, PR checklist, release flowDEVELOPMENT.md— setup, mise tasks reference, the two-layer model (pnpm workspace for lib+docs, mise-isolated examples), troubleshootingREADME.mdslimmed;examples/README.mdrewritten around the isolation modelTest plan
mise install && mise run setupfrom a cold clone provisions all runtimes, packs the lib, installs every examplemise run test:e2e— 38 tests passed across the 9 examplesmise run test:static— biome + tsc clean acrosspackage+docsmise run examples:test:static— biome + tsc clean across all 9 examplesmise run lib:test— vitest unit tests green (81 passed)mise run docs— docs site dev server bootsci.yml+e2e.ymlmatrix)🤖 Generated with Claude Code