Skip to main content
You will take a Vite or Next.js app you already have and make it a Forge static site where it stands: dev, staging and prod environments declared beside your code, a check that the build is a static export, and the browser’s console written to a file next to your other logs. None of your source files are moved or rewritten. Forge reads the framework from 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 status shows 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 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)
A Next.js app is detected the same way (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 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)
Set both in 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
A route like 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: 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
Call it once, in dev only. In Vite, that is 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
The receiver is a file Forge’s own site starters ship. Scaffold a throwaway site with reliant forge project new ref --kind site --frontend-kind vite-spa (or nextjs) and copy it across:
  • Vite: src/lib/devlog-plugin.ts, added to vite.config.ts as plugins: [react(), devLogPlugin()]. It applies only to vite serve.
  • Next.js: src/app/%5F_forge/log/route.ts. The %5F keeps Next from treating _forge as 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:
terminal
Output (trimmed)
The second line is an uncaught error: no 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 app and 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 = False in each env. Turning it on needs browser telemetry initialized first.

Troubleshooting

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.
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.
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.