package.json and the build config, and writes only forge.yaml and deploy/kcl/. Escape hatches describes the same command from the reference side.
Before you begin
- Reliant v1.21.3 or later. Inside Reliant, Forge runs as
reliant forge. This guide was run on Forge v1.6.1. Any v1.x has--in-place --kind site. - Node 20.19 or later, and the app committed to git, so
git statusshows exactly what Forge adds. - No account is needed for anything on this page. Deploying comes after, in Deploy a static site with a CDN.
1
Adopt the app
Run this at the app’s root, the directory with A Next.js app is detected the same way (
package.json and vite.config or next.config. Pass --name when the directory name is not the product name (a worktree, for example):terminal
Output (trimmed)
the nextjs app at the root ... builds into out/). Forge never overwrites a file you have: create-next-app ships its own AGENTS.md, and Forge kept it. Each env’s main.k declares the app with path = ".", and binds it to its dev server in dev and to hosted static hosting in staging and prod.2
Make the build a static export
Hosting serves files, so Set both in A route like
npm run build must produce plain HTML, JS and CSS. A Vite SPA already does. A stock Next.js app is a server until you say otherwise, and the lint names each problem with its file and line:terminal
Output (trimmed)
next.config.ts. Remove cacheComponents: true too, which create-next-app 16 adds: an export refuses it with Invariant: PPR cannot be enabled in export mode, and the lint does not catch it yet.next.config.ts
posts/[slug] then fails with static-export-dynamic-segment until it exports generateStaticParams(). Re-run the lint and npm run build until both pass:Output (trimmed)
3
Let the dev server use Forge's port (Vite)
reliant forge env up dev sets PORT and prints that URL, but a stock Vite config ignores it and serves on 5173. Read it in server:vite.config.ts
next dev reads PORT already.4
Mirror the browser console to disk
Two halves: Call it once, in dev only. In Vite, that is The receiver is a file Forge’s own site starters ship. Scaffold a throwaway site with
installDevLogging() in the browser posts each console line, uncaught error and unhandled rejection to /__forge/log, and a receiver on the dev server prints them, which env up tees to .forge/logs/dev/frontend_web.log. Install the runtime and the two peers it loads:terminal
src/main.tsx; in Next.js, a "use client" component’s useEffect rendered from layout.tsx, guarded by process.env.NODE_ENV !== "production":src/main.tsx
reliant forge project new ref --kind site --frontend-kind vite-spa (or nextjs) and copy it across:- Vite:
src/lib/devlog-plugin.ts, added tovite.config.tsasplugins: [react(), devLogPlugin()]. It applies only tovite serve. - Next.js:
src/app/%5F_forge/log/route.ts. The%5Fkeeps Next from treating_forgeas a private folder. It is POST-only and returns 404 in production, so the export leaves it out.
5
Verify the log reaches disk
Start the dev server, load the page in a browser, then grep:The second line is an uncaught error: no
terminal
Output (trimmed)
console call in your source, so only the log shows it. A production npm run build contains no /__forge/log. Stop the stack with reliant forge env down dev.What this does not do
- No code at request time. Server actions,
cookies(), middleware and dynamic route handlers have nowhere to run on static hosting. A Next.js app that needs them is a server: adopt it with--kind appand its Dockerfile instead (Deploy an existing app from its Dockerfile). - Dev only. The log receiver exists only on the dev server, so a deployed site writes nothing to
.forge/logs/. Production browser errors come from browser telemetry (Debug frontend errors with session timelines). - Session replay stays off. Adoption writes
_session_replay = Falsein each env. Turning it on needs browser telemetry initialized first.
Troubleshooting
Could not resolve "@bufbuild/protobuf/wkt" imported by "@reliantlabs/forge-web-runtime"
Could not resolve "@bufbuild/protobuf/wkt" imported by "@reliantlabs/forge-web-runtime"
The runtime’s entry point loads
@bufbuild/protobuf and @connectrpc/connect, which npm does not install for you. Install both, then restart the dev server (reliant forge env down dev, then up) so Vite rebuilds its dependency cache.does not provide an export named 'forgeDevLog'
does not provide an export named 'forgeDevLog'
Newer Forge skills name a
forgeDevLog() Vite plugin from @reliantlabs/forge-web-runtime/vite. Published runtime releases up to 0.13.20 do not have it yet. Use the copied devlog-plugin.ts. When env up still prints ok while the log shows error when starting dev server, the dev server did not start: read frontend_web.log.--dry-run prints what --kind app would write, and needs --kind app
--dry-run prints what --kind app would write, and needs --kind app
Sites have no dry run. Commit first, adopt, and read
git status: everything Forge wrote is new or under the # --- forge --- block of .gitignore.Next steps
Deploy a static site with a CDN
Cut a release and put the adopted site live on free static hosting.
Connect Claude Code or Cursor over MCP
Give your editor’s agent Forge’s lint, skills and
shapes as tools.Where the telemetry goes
The browser log file and what lands in it.
Deploy without an account
Publish an existing app with no signup and hand over a claim link.