Skip to content

feat(docs): Next.js docs site with online playground - #2

Merged
hunghg255 merged 4 commits into
mainfrom
claude/upbeat-brown-xyue6m
Sep 24, 2026
Merged

hunghg255 merged 4 commits into
mainfrom
claude/upbeat-brown-xyue6m

Conversation

@hunghg255

Copy link
Copy Markdown
Owner

Summary

Replaces the markdown-to-html docs/ folder with a Next.js 16 app (deployable on Vercel, Root Directory = docs) that has a landing page, the documentation and an online playground.

Pages

  • / – landing: install command, features, code example.
  • /docs – rendered at build time from the root README.md (single source of truth): section sidebar, "On this page" TOC with scrollspy, anchor links, shiki-highlighted code, scrollable tables.
  • /playground – spec from editor (JSON/YAML, CodeMirror), URL, file upload (drag & drop) or bundled examples (Petstore, Swagger 2, minimal); every playground option grouped with descriptions; generate via button / Ctrl+Enter / auto; file list + highlighted viewer; copy, download a file or everything as .zip; "Show config" (config file / CLI command); shareable URL; localStorage persistence; light/dark; mobile layout.

POST /api/generate (docs/lib/server/*)

  • Whitelisted plain-data options only (no hooks / templates / functions); output: false, silent: true forced.
  • Spec text: size limit (3 MB), JSON / safe YAML, node-count and depth limits (YAML alias bombs), external $refs rejected.
  • URL download: http(s) only, DNS resolved once and pinned (no rebinding), private / loopback / link-local / metadata / CGNAT / IPv6 special ranges blocked (incl. mapped / NAT64 / 6to4 forms and numeric hostnames), manual redirects re-checked (max 3), 10s timeout, decompressed size limit.
  • Generation timeout, response size guard, in-memory rate limit (30/min/IP, GENERATE_RATE_LIMIT), friendly errors with proper status codes (400/413/415/422/429/500).
  • The library is loaded from ../dist at runtime (bundling it broke template lookup); next.config.ts traces dist, templates, the oxfmt native binding and the library's runtime deps.

Library

  • fix: fail loudly when built-in templates are missing instead of silently generating empty files (happens when the package is bundled). Test added.
  • bin/cli.mjs made executable.

CI

  • CI now runs on main – the workflow targeted master, so it never ran on this repo.
  • New docs job: typecheck, unit tests, next build, route trace check, Playwright e2e.

Deploy (manual)

Import the repo on Vercel with Root Directory docs; docs/vercel.json builds the library first. Adding a Vercel Firewall rate-limit rule is recommended. See docs/README.md.

Test plan

  • Library: npm test (810 tests), tsc, oxlint, fmt:check, build
  • Docs: npm run typecheck, npm test (184 unit tests: validation, SSRF classifier & fetcher, handler, parallel isolation), next build
  • npm run test:e2e: 22 Playwright tests on Chromium (landing, docs TOC/highlighting, playground generate → view → copy → download → modular → zip, errors, upload limits, theme, mobile no horizontal scroll)
  • Standalone build copied outside the repo serves correct output (default, modular, toJS + axios)
  • Vercel preview deploy

🤖 Generated with Claude Code

https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3


Generated by Claude Code

…ating empty files

Happens when the library is bundled (e.g. by Next.js) and its templates folder
is not next to the code. Also make bin/cli.mjs executable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3
- / landing, /docs (rendered from README.md), /playground: edit/upload/URL/examples
  spec input, all options, file tree + highlighted viewer, copy, download a file
  or everything as .zip, config/CLI snippet, shareable URL, light/dark, mobile
- POST /api/generate on Vercel: option whitelist, JSON/YAML parsing with size and
  complexity limits, SSRF-safe URL download (DNS pinning, redirect checks,
  private ranges blocked), timeouts, rate limit
- vercel.json, deploy guide in docs/README.md, CI job (typecheck, unit, build,
  trace check, Playwright e2e)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3
@vercel

vercel Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
swagger-typescript-api-es Error Error Sep 24, 2026 11:24am UTC

Copy link
Copy Markdown
Owner Author

Vercel status failed on 56cbce0, before the build started

The Vercel commit status went to failure about 1s after the deployment was created (11:24:00 → 11:24:01 UTC). That is before installCommand or next build could run, so this looks like Vercel rejecting the deployment rather than a build error in docs/.

The most likely cause is that the commits on this branch are authored by Claude <noreply@anthropic.com>, which is not a member of the Vercel team. Vercel blocks deployments whose commit author has no access to the project. I can't read the Vercel logs from here, so this is not confirmed.

To check and unblock:

  • run npx vercel inspect dpl_By4FyZupWyKyZ9fEsRaxFNHbjSBN --logs, or open the deployment in the Vercel dashboard;
  • if it says the commit author lacks access, redeploy from the dashboard, or push/merge a commit authored by you;
  • project settings needed: Root Directory docs, with "Include files outside the Root Directory" enabled (the default). docs/vercel.json installs and builds the library at the repo root first.

The GitHub Actions jobs (build (20.x), build (22.x), docs) are running now. I'm watching them and will fix anything they report.


Generated by Claude Code

@hunghg255
hunghg255 merged commit 13269ee into main Sep 24, 2026
4 of 5 checks passed

This branch had an error being deployed

1 failed deployment
Preview — 56cbce09 Deployed Sep 24, 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.

2 participants