Development Notes

Runtime

Next.js runs inside the Docker container Raikyakun-Mobile-Node.

The macOS workspace is mounted over SMB. Do not use macOS-side npm, yarn, next, or tsc results as the source of truth because node_modules and .next belong to the Linux container environment.

Use SSH into the container for runtime checks.

SSH

Connect to the mobile container:

ssh raikyakun-mobile

Run a command inside the app:

ssh raikyakun-mobile 'cd /usr/src/node && <command>'

The mobile development container is rebuilt often, so its SSH host key can change. For development-only SSH config, it is acceptable to disable known_hosts checks for this host:

Host raikyakun-mobile
  HostName 192.168.10.253
  Port 2225
  User codex
  StrictHostKeyChecking no
  UserKnownHostsFile /dev/null
  LogLevel ERROR

If the VPN address is preferred in your environment, use HostName 10.3.0.3 instead.

Dev Server

By default yarn dev is started by Docker Compose. The startup command checks for a node/.prod-mode marker file: if present it runs yarn build && yarn start (production build), otherwise yarn dev.

The server log (both modes) is mirrored inside the container at:

/tmp/next-dev.log

Switching dev / prod build mode

Use switch-mode.sh on the Docker host (run from the mobile/ directory):

./switch-mode.sh prod      # 本番ビルドへ (yarn build && yarn start)
./switch-mode.sh dev       # dev へ (yarn dev)
./switch-mode.sh status    # 現在のモード表示 (restart しない)
./switch-mode.sh package   # 本番ビルド成果物を tar に固める (restart しない)

prod/dev touches/removes node/.prod-mode then runs docker compose restart node. status/package do not restart.

prod does not return immediately: after the restart it polls the container log (/tmp/next-dev.log) and waits until yarn build finishes and next start reports "Ready" (or fails / times out after BUILD_TIMEOUT, default 900s). So once prod returns successfully you can run package right away — no manual wait needed.

package calls ./build and produces standalone.tar.gz / static.tar.gz / public.tar.gz in mobile/. It requires a completed prod build (node/build/standalone must exist) — run ./switch-mode.sh prod first. yarn start does not mutate the packaged directories, so running package while the prod server is up is safe. Deploy flow: prod → 動作確認 → package → 本番先へ3つの tar.gz を展開. (package という名前は、Node サーバーを使わない静的出力を指す Next.js の next export と紛らわしいため export を避けたもの。)

Notes:

yarn build takes a few minutes; the server is down during the build.
If yarn build fails the container restarts and rebuilds in a loop — run ./switch-mode.sh dev to recover.
Production build runs with NODE_ENV=production, so it reads .env.production (NEXT_PUBLIC_BASE_URL=https://mobile.raikyakun.app). To keep the dev URL while testing a prod build, add NEXT_PUBLIC_BASE_URL to environment: in docker-compose.yml.
node/.prod-mode is a per-machine local marker and is gitignored.

Check recent logs:

ssh raikyakun-mobile 'tail -n 120 /tmp/next-dev.log'

Follow logs:

ssh raikyakun-mobile 'tail -f /tmp/next-dev.log'

Page Check

Trigger a page compile and check the HTTP response from inside the container:

ssh raikyakun-mobile 'curl -I http://127.0.0.1:3000/'

TypeScript Check

Run TypeScript inside the container. The container user cannot write tsconfig.tsbuildinfo, so pass --incremental false to avoid EACCES:

ssh raikyakun-mobile 'cd /usr/src/node && node node_modules/typescript/lib/tsc.js --noEmit --incremental false --pretty false'

As of 2026-05-12, this command passes cleanly.

Lint Check

The mobile container does not provide sudo, and ESLint has not been initialized yet (running yarn lint triggers next lint's interactive setup prompt asking for Strict/Base/Cancel). As of 2026-05-12, lint is not yet configured for this project. When initializing, prefer Strict. Run as the container user (no sudo):

ssh raikyakun-mobile 'cd /usr/src/node && yarn lint'

Keep this file updated when the mobile verification workflow changes so both Codex and Claude Code use the same test knowledge.