Guide: test the web app locally on a new branch

Step-by-step

1. Go to the repo root

cd /Users/xxx/jean/seed/Form-with-seed-docs

If you are on another branch/repo checkout, use that repo root instead.

2. Load the repo environment

eval "$(direnv export zsh)"

3. Create the local site config

Create:

frontend/apps/web/config.json

Example:

{
  "availableRegistrationSecret": "local-dev",
  "registeredAccountUid": "z6MkhGQJc96o3UNQ3JyUbCKfQo2bvaQ9KDNa9xxYHJFWWTwg"
}

Notes

registeredAccountUid is the site/account you want the web app to serve.

availableRegistrationSecret is optional, but useful for local flows.

This file is gitignored, so it is safe as local-only setup.

4. Start a backend in one terminal

Use dedicated local ports to avoid conflicts:

eval "$(direnv export zsh)" && ./dev run-backend -- -http.port=53101 -grpc.port=53102 -p2p.port=53100 -data-dir="$PWD/data/standalone-web"

Notes

If those ports are already in use, pick another trio.

Example alternative:

53201 / 53202 / 53200

5. Start the web app in a second terminal

From the repo root:

eval "$(direnv export zsh)" && cd frontend/apps/web && SEED_SIGNING_ENABLED=true SEED_IDENTITY_ENABLED=true SEED_IDENTITY_DEFAULT_ORIGIN="http://localhost:3000" SEED_BASE_URL="http://localhost:3000" DAEMON_HTTP_PORT=53101 DAEMON_HTTP_URL="http://localhost:53101" DAEMON_FILE_URL="http://localhost:53101/ipfs" VITE_DESKTOP_HTTP_PORT=53101 VITE_DESKTOP_GRPC_PORT=53102 VITE_DESKTOP_P2P_PORT=53100 pnpm exec remix vite:dev

Important

Even if you try to force a port, always trust the URL Vite prints.

In our case it often started on:

http://localhost:3000/

But if 3000 is busy, it may move to 3001 or another port.

6. Open the site in the browser

Open the exact URL printed by the terminal.

Examples:

http://localhost:3000/

http://localhost:3001/

For the feedback route specifically:

http://localhost:3000/feedback

or whatever port Vite printed.

How to open a concrete site

If you want the local web app to serve a specific site like:

hm://z6MkhGQJc96o3UNQ3JyUbCKfQo2bvaQ9KDNa9xxYHJFWWTwg

set:

{
  "registeredAccountUid": "z6MkhGQJc96o3UNQ3JyUbCKfQo2bvaQ9KDNa9xxYHJFWWTwg"
}

inside:

frontend/apps/web/config.json

Then restart the web app.

Common problems and fixes

Problem 1: “Failed to load configuration”

Cause:

no config.json

or wrong working directory

Fix:

make sure this file exists:

frontend/apps/web/config.json

restart the web app

Problem 2: cd: no such file or directory: frontend/apps/web

Cause:

you are already inside frontend/apps/web

Fix:

don’t cd frontend/apps/web again

check with:

pwd

Problem 3: browser says localhost refused to connect

Cause:

web server not actually running

or backend failed before web was useful

Fix:

check both terminals

confirm web printed a local URL

confirm backend did not die with port conflict

Problem 4: backend port already in use

Example:

listen tcp :53002: bind: address already in use

Fix:

choose different ports

or inspect what is using the port:

lsof -nP -iTCP:53102 -sTCP:LISTEN

Problem 5: Vite chunk file missing / dep optimizer errors

Example:

missing files in frontend/apps/web/node_modules/.vite/deps/...

Fix:

rm -rf frontend/apps/web/node_modules/.vite

Then restart the web server.

If still broken:

rm -rf frontend/apps/web/.react-router
rm -rf frontend/apps/web/node_modules/.vite

Then restart again.

Problem 6: site opens but not the one you expect

Cause:

wrong registeredAccountUid in config

Fix:

update frontend/apps/web/config.json

restart the web app

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime