Web Getting Started

Shared Setup

Before starting either client, finish the common workspace setup first:

Install Prerequisites

Ensure your development environment has the necessary tools installed:

Install Node.js 20+
Install pnpm 9+
Install git

Clone Repository

Clone the repository and enter the project root to begin development:

# clone repository
git clone https://github.com/sunshineLixun/easystarter.git your-project-name

# enter project root
cd your-project-name

# remove default origin
git remote remove origin

# add your own origin
git remote add origin https://github.com/your-username/your-project-name.git

# push to origin
git push -u origin main

Install Dependencies

Run the following command to download and install all necessary project dependencies:

pnpm install

Configure web env vars

Copy the template file:

cp apps/web/.env.development.example apps/web/.env.development

Then open apps/web/.env.development and fill in the values:

Variable	Local default	Purpose
`VITE_SERVER_URL`	`http://localhost:3001`	Base URL the web client uses to call the server (Hono on Cloudflare Workers, port `3001` in dev).
`VITE_APP_URL`	`http://localhost:3000`	URL of the web app itself — used for OAuth callbacks.
`VITE_GA_MEASUREMENT_ID`	(empty)	Google Analytics measurement ID, optional.
`VITE_OPENPANEL_CLIENT_ID`	(empty)	OpenPanel analytics client ID, optional.

The VITE_ prefix means Vite bakes these values into the JS bundle at build time — never put server-side secrets here.

Configure server env vars

The server needs its own local env file. Copy the template:

cp apps/server/.dev.vars.example apps/server/.dev.vars

Start the server + web together

The web client calls the server at http://localhost:3001, so the server must be running. Run the combined script from the repo root:

pnpm dev:web+server

Or run them in separate terminals if you want isolated logs:

pnpm dev:server   # wrangler dev --port=3001
pnpm dev:web      # TanStack Start dev server

Default local development URLs:

Web: http://localhost:3000
Server: http://localhost:3001

Web & Server Scripts Reference

Root-level scripts that touch web or server (defined in the monorepo package.json):

pnpm dev:web — web client only
pnpm dev:server — server only (port 3001)
pnpm dev:web+server — both, in parallel (recommended for web development)
pnpm dev — turbo-runs every workspace (web + server + native)

Setup Checklist

Now that web + server are running, complete these steps in order before building any features:

Cloudflare — account credentials and D1 setup
Database — Drizzle ORM + D1 schema and migrations
Email Service — Resend for sign-up verification and password reset (recommended for international audiences)
Phone Sign-In — Alibaba Cloud SMS code sign-in (recommended for China)
Authentication — Better Auth, GitHub OAuth, Google OAuth
Object Storage — Cloudflare R2 for avatars and file uploads
Stripe Payments — Stripe Checkout, Billing Portal, and Webhooks
Creem Payments — Creem Checkout, Billing Portal, and Webhooks

To deploy, follow these steps in order:

Deploy Server — deploy Hono server to Cloudflare Workers
Deploy Web — deploy TanStack Start web app to Cloudflare Workers

On this page