> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Adopt an existing Vite or Next.js app with Forge, in place

> Turn the Vite or Next.js app you already have into a Forge static site without moving a file, check its static export, and mirror browser logs to disk.

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](https://docs.reliantlabs.io/forge/deploy/escape-hatches.md#adopt-an-app-that-already-exists) 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](https://docs.reliantlabs.io/guides/forge/deploy-static-site-cdn.md).

**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):

```bash terminal theme={null}
cd my-vite-app
reliant forge project new --in-place --kind site
git status --short
```

```text Output (trimmed) theme={null}
✅ Static site 'my-vite-app' adopted at .../my-vite-app
   frontend "web": the vite app at the root (path ".", builds into dist/)
   wrote forge.yaml, deploy/kcl/kcl.mod (+ its empty kcl.mod.lock), deploy/kcl/{dev,staging,prod}/main.k — no Go, no server
📁 Merged .gitignore: kept your entries, appended 10 forge entries under "# --- forge ---".

 M .gitignore
?? AGENTS.md
?? deploy/
?? forge.yaml
```

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:

```bash terminal theme={null}
reliant forge lint --static-export
```

```text Output (trimmed) theme={null}
❌ static-export — 2 errors
   ✗ next.config.ts:3 [static-export-not-exported] frontend "web" is bound to forge.OnHosted in env prod, forge.OnHosted in env staging, but its build is not a static export: next.config.ts does not set `output: "export"` ...
   ✗ next.config.ts:3 [static-export-next-image] next/image is imported (src/app/page.tsx:1), and its default loader is a server-side optimizer ...
```

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.

```ts next.config.ts theme={null}
const nextConfig: NextConfig = {
  output: "export",
  images: { unoptimized: true },
};
```

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:

```text Output (trimmed) theme={null}
✓ static-export
   · static-export clean — 1 static frontend(s) use nothing a static export cannot serve
✅ All 1 gating linters passed.
...
├ ● /posts/hello
└ ● /posts/launch
```

**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`:

```ts vite.config.ts theme={null}
server: {
  port: Number(process.env.PORT) || 5173,
  strictPort: Boolean(process.env.PORT),
},
```

`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:

```bash terminal theme={null}
npm install @reliantlabs/forge-web-runtime @bufbuild/protobuf @connectrpc/connect
```

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"`:

```tsx src/main.tsx theme={null}
import { installDevLogging } from '@reliantlabs/forge-web-runtime'

if (import.meta.env.DEV) {
  installDevLogging({ dev: true })
}
```

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:

```bash terminal theme={null}
reliant forge env up dev
grep '\[browser:' .forge/logs/dev/frontend_web.log
```

```text Output (trimmed) theme={null}
│  ○ web  http://localhost:3000  starting
│       ↳ .forge/logs/dev/frontend_web.log

[browser:info] my-vite-app booted
[browser:error] TypeError: Cannot read properties of undefined (reading 'name')
```

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](https://docs.reliantlabs.io/guides/forge/bring-existing-app-any-language.md)).
* **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](https://docs.reliantlabs.io/guides/observability/debug-frontend-errors-session-timelines.md)).
* **Session replay stays off.** Adoption writes `_session_replay = False` in each env. Turning it on needs browser telemetry initialized first.

## Troubleshooting

> [accordion] 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.

> [accordion] 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`.

> [accordion] --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

> [card] [Deploy a static site with a CDN](https://docs.reliantlabs.io/guides/forge/deploy-static-site-cdn.md)
>
> Cut a release and put the adopted site live on free static hosting.

> [card] [Connect Claude Code or Cursor over MCP](https://docs.reliantlabs.io/guides/forge/connect-claude-code-cursor-mcp.md)
>
> Give your editor's agent Forge's lint, skills and `shapes` as tools.

> [card] [Where the telemetry goes](https://docs.reliantlabs.io/hosting/observability/where-it-goes.md#browser-console-in-the-log-directory)
>
> The browser log file and what lands in it.

> [card] [Deploy without an account](https://docs.reliantlabs.io/forge/deploy-without-an-account.md)
>
> Publish an existing app with no signup and hand over a claim link.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.