loto/docs/deployment-guide.md

Deployment Guide

Production Deployment (GitHub Pages)

Automatic Deploy

The app auto-deploys from the master branch via .github/workflows/deploy.yml.

Workflow:

1. Push to master
2. GitHub Actions runs npm run build
3. Static export written to out/ directory
4. Pages deployed to https://{user}.github.io/loto

Note: basePath is set to /loto in production (next.config.mjs:23).

Manual Deploy (if needed)

npm run build
# out/ directory ready for upload

Then deploy out/ folder to GitHub Pages or any static host.

Development Environment

Local Dev

npm install
npm run dev

Access at http://localhost:3000 (no basePath).

HMR works automatically.

Code-Server Dev

For browser-based development (VS Code in browser):

1. Start code-server with Node.js environment:

code-server --no-auth

2. Create .env.local in project root:

CODESERVER_HOST=your-machine.example.com
CODESERVER_PORT=3000

Replace your-machine.example.com with your actual hostname/IP (must match the proxy URL you'll access).

3. Run dev server:

npm run dev:codeserver

This sets NEXT_DEV_PROFILE=codeserver, triggering the code-server config path in next.config.mjs.

4. Access via browser: Navigate to:

https://your-codeserver-host/absproxy/3000/

Key Points:

• /absproxy/{port} (NOT /proxy/{port}) preserves basePath through the proxy.
• HMR socket connects to CODESERVER_HOST for live reload.
• If HMR fails, manually refresh the page (CSS/JS changes still apply server-side).

Manual Refresh Workaround

If HMR over proxy is unreliable:

1. Make code changes
2. Manually refresh browser (F5)
3. Dev server has already compiled the changes

This is normal in proxy environments.

Build & Output

Build Command

npm run build

Generates:

• out/ — Complete static HTML export
• .next/ — Build cache (not needed for deployment)

Export Settings

• output: "export" in next.config.mjs
• No server-side rendering
• All pages pre-rendered to HTML + JS bundles

Asset Hosting

• assetPrefix matches basePath (prod: /loto, dev/codeserver: empty or /absproxy/{port})
• CSS, JS, fonts all prefixed correctly
• GitHub Pages serves from repository root, so /loto paths resolve correctly

Environment Variables

Required (code-server only)

• CODESERVER_HOST — hostname for HMR proxy
• CODESERVER_PORT — port (default 3000)

Optional

• NEXT_DEV_PROFILE — set to "codeserver" to enable proxy mode (usually set by npm run dev:codeserver)

Not Used at Runtime

• No database URL, API keys, or secrets (all client-side, localStorage)
• .env.local is .gitignored and safe for local config

Troubleshooting

Issue	Cause	Fix
404 on subpages after deploy	basePath mismatch	Verify basePath="/loto" in prod; local dev should be empty
HMR not connecting (code-server)	CODESERVER_HOST not set	Add CODESERVER_HOST=... to .env.local
Assets 404 (code-server)	Wrong proxy URL	Use /absproxy/{port}, not /proxy/{port}
Page blank after refresh	State not persisted	Check browser localStorage is enabled
Stale CSS (code-server)	HMR failed	Manually refresh page (F5)

CI/CD Pipeline

.github/workflows/deploy.yml:

• Triggers on push to master
• Installs dependencies (npm install)
• Builds app (npm run build)
• Deploys out/ folder to GitHub Pages

No manual steps required; push to master and GitHub Pages updates automatically.

Performance Checklist

• Static export (no server overhead)
• Tailwind purged for production size
• localStorage reduces bundle—no API calls
• Images minimal (mostly CSS gradients)
• Fonts: Geist via Google Fonts CDN

Bundle analysis: Run npm run build && ls -lh out/ to inspect file sizes.

Security Considerations

• No sensitive data in code (no API keys, secrets)
• .env.local is local-only, not committed
• localStorage scoped to origin
• No external API calls (offline-capable)
• GitHub Pages HTTPS by default

Last reviewed: 2026-04-26