Skip to content

docs: restructure readme - #35

Merged
kahlstrm merged 3 commits into
mainfrom
docs/readme
Aug 3, 2026
Merged

kahlstrm merged 3 commits into
mainfrom
docs/readme

Conversation

@kahlstrm

@kahlstrm kahlstrm commented Aug 3, 2026

Copy link
Copy Markdown
Owner

Summary

The README had grown by accretion over this week's changes — a one-note "Dependencies" section
wedged between Getting Started and Database, lint and formatting docs buried under a "Tests"
heading, and a lot of prose explaining why a change was made rather than what a reader needs.

Restructured around what someone actually needs, in the order they need it:

Getting started → Environment → Architecture → Database → Checks → Deployment → Gotchas

Two things were missing entirely

ENABLE_EXPERIMENTAL_COREPACK=1 was documented nowhere — only in #21's description. It is
set on Production and Preview, and removing it breaks deploys: Vercel would fall back to
pnpm 9, which rejects a pnpm-workspace.yaml with no packages: field, failing with
ERROR packages field missing or empty. That is now its own section.

There was no Deployment section at all — the original ## Deploy on Vercel was
create-next-app boilerplate and I deleted it earlier while rewriting. The repo has real
deploy requirements now, so it is back with actual content.

Added

  • Architecture — the edge-runtime constraint that explains the libsql/container decisions,
    and a table of which paths are protected, public, or middleware-only. The
    clerkMiddleware()-protects-nothing trap is stated, since that is what caused the auth
    regression.
  • Environment — a table of the variables, including that the publishable key is public
    while the secret key is an instance admin credential.
  • The unstable_cache never-trust-a-miss behaviour, which is otherwise only visible as a
    comment in the route.

Trimmed

Migration history — "ESLint was kept briefly, then dropped" and similar. That belongs in PR
descriptions, not a README. The consequence is kept: the oxlint known-gap list, because it
tells you what is not caught.

Verified, not remembered

Every factual claim was checked against the code rather than written from memory:

  • all seven routes really do declare runtime = "edge"
  • createRouteMatcher(["/"]) is the protected set
  • /api/health is outside the proxy matcher
  • pnpm-workspace.yaml has no packages: field
  • CI really runs lint, format:check, test:unit, test:e2e and the build

That last one caught an error of mine: I had written "CI runs all five", but pnpm format is
the write variant and CI cannot run it. Corrected.

ENABLE_EXPERIMENTAL_COREPACK was confirmed still present on both environments via
vercel env ls before documenting it as required.

@vercel

vercel Bot commented Aug 3, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
next-shortener Ready Ready Preview Aug 3, 2026 5:26pm

@kahlstrm
kahlstrm merged commit e4fcce4 into main Aug 3, 2026
4 checks passed
@kahlstrm
kahlstrm deleted the docs/readme branch August 3, 2026 17:30

This branch was successfully deployed

1 active deployment
Preview — 740cd165 Deployed Aug 3, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant