feat(website): getting-started docs site, built and deployed with Composer#95
Merged
Merged
Conversation
…poser A small docs website under website/, built as a Prisma App (one Bun service, node adapter) and deployable with `prisma-composer deploy` — the framework hosting its own docs. Verified live on a stage. Content is generated from the canonical guides in docs/guides/ at build time (scripts/render-content.ts): markdown-it + shiki, with links that escape docs/guides/ rewritten to GitHub URLs and intra-guide links rewritten to site routes. The site is never a second copy of the docs — it is the docs, rendered. The only hand-authored page is the landing page. A bun test locks the link-rewriting and one-route-per-guide contract. - website/ is a private workspace package (registered in pnpm-workspace.yaml); build = render + tsdown into one self-contained entry; deploy/destroy scripts mirror the examples. - lint:deps now cruises website with the same public-imports-only rule as examples (ADR-0028), so the site is an honest demo of the user API. - generated content (website/src/generated/) is gitignored; the build regenerates it. Server routes / and /guides/<slug>, 404 elsewhere, cache headers, port from service.config(), binds 0.0.0.0. Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
commit: |
The hero sold a deploy tool; the site now makes the same central claim the README does — the fastest, most reliable way to build an app with your agent, scratch to deployed in minutes. The primary call to action is installing the skill, because that is genuinely the first thing to do, not the package install. Adds the three properties that back the claim up (Modules snap together, everything is typechecked, deploys are deterministic) so it reads as a reason rather than a slogan. The guide pages need no change here — they render from docs/guides/, which carries the same message. Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
The h1 inherited the body line-height of 1.65, which is set for prose and left the two-line headline looking gappy. Sets 1.08, and adds text-wrap: balance so the two lines stay evenly split. Puts "fastest" and "most reliable" in the accent colour — the claim is the point of the page, and it was reading flat in a single tone. Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
…add background depth - The three property titles are now the accent colour, so the row reads as three claims rather than a wall of body text. - "build an app" joins "fastest" and "most reliable" as accented — the three highlighted phrases are the whole pitch. - The flat background gains three soft radial washes in the theme colours, viewport-anchored (background-attachment: fixed) so they read as ambient depth rather than a banner that scrolls away. Cards and the install pill go slightly translucent with a backdrop blur, so they sit on the wash instead of punching solid holes in it. The glow values are per-theme rather than one alpha for both: over white, teal saturates far sooner than it does on the dark background, so light mode runs its own weaker set. Checked both themes on the landing page and a guide page — the wash never sits under running text or code. Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
The site renders docs/guides/*.md into its bundle at build time, so a guide edit does not reach the site until something rebuilds and redeploys it. This does that on push to main, filtered to the paths that can actually change the output (website/**, docs/guides/**, and the workflow itself). - Deploys production (no --stage), which is the environment the site serves from. - Fixed concurrency group with cancel-in-progress: false — one real-cloud deploy at a time, and a kill mid-deploy would leave the stack half-applied (the deploy is idempotent; an interrupted one is not). Same reasoning as the E2E deploy workflow. - Calls the CLI directly rather than the package deploy script, which sources a local .env that does not exist on a runner; on CI the credentials are already in the environment. - Credentials: repo secret CI_SITE_DEPLOY_TOKEN (the site deploy token, separate from the E2E workflow token) mapped onto PRISMA_SERVICE_TOKEN, which is the name the CLI reads, plus repo variable PRISMA_WORKSPACE_ID. Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
wmadden
approved these changes
Jul 16, 2026
…website Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io> # Conflicts: # pnpm-lock.yaml
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
2 participants
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.
A small getting-started docs website for Prisma Composer, living in
website/, built as a Prisma App (one Bun service,nodeadapter) and deployable to Prisma Compute withprisma-composer deploy— the framework hosting its own docs. Verified live on a stage: https://ujkny4p1d9nwbf6chkg1n1ln.ewr.prisma.buildSpec
At a glance. One Bun service that serves the guides as pre-rendered HTML. No static-hosting primitive exists, so a tiny service is the least machinery and dogfoods the core deploy path. Content is generated from the canonical guides in
docs/guides/; the only hand-authored page is the landing page.Chosen design.
nodeadapter. Next.js was considered and rejected for six static pages — standalone build weight and theforce-dynamicrule buy nothing here. Upgrading later is contained.docs/guides/*.md, rendered at build time (scripts/render.ts+render-content.ts): markdown-it + shiki (dual light/dark theme, build-time only — no highlighter in the runtime bundle). Links that escapedocs/guides/are rewritten to GitHub URLs; intra-guide links become site routes. The site can't drift from the docs because it is the docs, rendered.website/is a private workspace package:module.ts(module('composer-docs')provisioning onesiteservice),prisma-composer.config.ts,src/{server,service,template}.ts, the generator,tsdown.config.ts(viaprismaTsDownConfig— dogfooding the guide's own advice). Build = render + tsdown into one self-contained entry./and/guides/<slug>, 404 elsewhere, cache headers, port fromservice.config(), binds0.0.0.0.Deliberately out: CI auto-deploy on merge (follow-up); custom domain (no Composer surface yet); rendering the README/design docs/ADRs (guides only); search, versioning, analytics, client JS.
Verification (slice DoD)
pnpm turbo run build --filter composer-docs-websitegreen from clean; the generator test (9 cases) locks link-rewriting + one-route-per-guide.lint:depsnow cruiseswebsiteunder the same public-imports-only rule as examples (ADR-0028) — the site only imports@prisma/composer*, so it's an honest demo of the user API. Green./and every guide route (curl-verified); typecheck + biome clean.--stage docs-preview, 10 resources) and the live endpoint serves the landing page, every guide route (200, with highlighting), and 404s correctly — curl- and browser-verified.Notes for the reviewer
website/src/generated/) is gitignored; the build regenerates it. Nothing to review there.prisma-composer deploy module.ts, no--stage); happy to do that in this PR or a follow-up, your call.docs/guides/**orwebsite/**changes (mirrors the e2e-deploy workflow).prismaTsDownConfigemits deprecation warnings (external/noExternal) from tsdown — framework-owned, not introduced here.🤖 Generated with Claude Code