Skip to content

docs(guide): 改教真正生效的 VITE_SERVER_URL,删除不存在的 MSW 开关 #3532

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yinlianghui merged 1 commit into from
Aug 7, 2026
Merged

docs(guide): 改教真正生效的 VITE_SERVER_URL,删除不存在的 MSW 开关 #3532

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 6 additions & 7 deletions content/docs/guide/console.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@ The **Console** is the reference application for [ObjectUI](/docs/guide). It ren
```bash
# From the repository root
pnpm install
pnpm console # starts the dev server (Vite)
pnpm dev # starts the console dev server (Vite)
```

The console opens at **http://localhost:5175** with MSW (Mock Service Worker) providing a simulated backend.
The console opens at **http://localhost:5180** (the port is fixed in `apps/console/vite.config.ts`). There is no bundled mock backend — `apps/console/.env.development` points `VITE_SERVER_URL` at `http://localhost:3000`, so an ObjectStack server has to be listening there. See [Running with a Real Backend](#running-with-a-real-backend) to target a different one.

## Key Features

Expand Down Expand Up @@ -88,12 +88,13 @@ export default defineStack({

## Running with a Real Backend

To connect to a real ObjectStack server instead of MSW:
`VITE_SERVER_URL` is the setting that decides which backend the console talks to — the data adapter, auth, i18n and action endpoints all hang off it.

1. Set the `VITE_API_URL` environment variable:
1. Point it at your server. An inline value overrides `apps/console/.env.development`:
```bash
VITE_API_URL=http://localhost:3000 pnpm console
VITE_SERVER_URL=http://localhost:3000 pnpm dev
```
Leave it empty (`VITE_SERVER_URL=`) to use the same origin — the right setting when an ObjectStack server serves the console itself.
2. The console will use the ObjectStack client to discover metadata and perform CRUD operations against the server.

## Folder Structure
Expand All @@ -118,8 +119,6 @@ apps/console/
hooks/
useBranding.ts # Delegates to @object-ui/layout
useObjectActions.ts # CRUD action handlers
mocks/
browser.ts # MSW browser worker
```

## See Also
Expand Down
23 changes: 12 additions & 11 deletions content/docs/guide/deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,31 +158,32 @@ ObjectUI uses Vite's `import.meta.env` for build-time configuration. Prefix all

| Variable | Default | Description |
|----------|---------|-------------|
| `VITE_USE_MOCK_SERVER` | `"true"` | Enable MSW mock server for local development. Set to `"false"` for production builds that hit a real API. |
| `VITE_API_URL` | — | Base URL for the ObjectStack API (e.g. `https://api.example.com`). |
| `VITE_SERVER_URL` | `""` (same origin) | Absolute origin of the ObjectStack backend, e.g. `https://demo.objectstack.ai`. The one setting that matters — the data adapter, auth, i18n and action endpoints all hang off it. An empty value means same-origin, which is correct when the ObjectStack server serves the console itself; on a static host with no backend behind it, every `/api/v1/*` request then 404s. |
| `NODE_ENV` | `"development"` | Set automatically to `"production"` by `vite build`. |

Because Vite inlines `import.meta.env` at **build time**, `VITE_SERVER_URL` has to be present when the build runs. Setting it only in a static host's runtime environment changes nothing — the value is already baked into the bundle.

Create a `.env.production` file for production defaults:

```bash
VITE_USE_MOCK_SERVER=false
VITE_API_URL=https://api.example.com
# Leave empty for same-origin; set an absolute origin for a split-origin deploy.
VITE_SERVER_URL=https://demo.objectstack.ai
```

For platform-specific configuration, set environment variables in each platform's dashboard or CLI:

```bash
# Vercel
vercel env add VITE_API_URL production
vercel env add VITE_SERVER_URL production

# Railway
railway variables set VITE_API_URL=https://api.example.com
railway variables set VITE_SERVER_URL=https://demo.objectstack.ai

# Netlify
netlify env:set VITE_API_URL https://api.example.com
netlify env:set VITE_SERVER_URL https://demo.objectstack.ai
```

> **Tip:** The console app ships with MSW enabled by default. Always set `VITE_USE_MOCK_SERVER=false` in production to disable the mock service worker.
> **Tip:** A split-origin deployment (console and backend on different origins) needs two things from the backend: CORS for the SPA origin (`Access-Control-Allow-Origin: <spa-origin>`, `Access-Control-Allow-Credentials: true`), and auth cookies marked `SameSite=None; Secure` so they survive cross-site requests.

## Build Optimization

Expand Down Expand Up @@ -244,13 +245,13 @@ export default defineConfig({

### Production Build Command

Build without the mock server and verify the output:
Bake the backend origin into the bundle and verify the output:

```bash
VITE_USE_MOCK_SERVER=false pnpm build
VITE_SERVER_URL=https://demo.objectstack.ai pnpm build
```

This is equivalent to the `build:server` script defined in the console app.
`pnpm build` runs `turbo run build` across the workspace. Turbo runs in strict env mode, but it detects the console as a Vite package and passes `VITE_*` through automatically, so an inline `VITE_SERVER_URL` does reach the build. To build the console alone, use `pnpm build:console`.

## Health Checks

Expand Down