EchoRead

EchoRead is a Vite + React app for English reading practice with Gemini-powered text-to-speech.

Architecture

• Frontend: Vite builds the SPA into dist/
• Backend: server.js serves the SPA and exposes POST /api/tts
• TTS provider: Gemini via @google/genai
• Production auth: Cloud Run service account + Vertex AI

Local Development

Prerequisites:

• Node.js 24

1. Install dependencies: pnpm i
2. Create .env.local from .env.example
3. For local development, set GEMINI_API_KEY
4. Start the API server: pnpm dev:server
5. In another terminal, start the frontend dev server: pnpm dev

Local Production Smoke Test

1. Build the frontend: pnpm build
2. Start the Cloud Run-compatible server: pnpm start
3. Open http://localhost:8080

Deploy to Google Cloud Run

Set your active project first:

gcloud config set project PROJECT_ID

Enable required services:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  aiplatform.googleapis.com

Create a service account for Cloud Run:

gcloud iam service-accounts create echoread-run \
  --display-name="EchoRead Cloud Run"

Grant Vertex AI access:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:echoread-run@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Deploy from source:

gcloud run deploy echoread \
  --source . \
  --region asia-northeast1 \
  --allow-unauthenticated \
  --service-account echoread-run@PROJECT_ID.iam.gserviceaccount.com \
  --set-env-vars GOOGLE_CLOUD_PROJECT=PROJECT_ID,GOOGLE_CLOUD_LOCATION=global,GOOGLE_GENAI_USE_VERTEXAI=true,NODE_ENV=production

Notes

• Do not expose GEMINI_API_KEY to the browser.
• In production, prefer Vertex AI over a direct API key.
• The current library is stored in browser localStorage, so it is device-local.