Local Development Setup

Step-by-step guide to get UberLotto v2 running on your local machine.

Prerequisites

Requirement	Version	Notes
Node.js	>= 18.0.0	LTS recommended
npm	Included with Node.js	Used for package management
Shopify CLI	Latest	Install via npm install -g @shopify/cli
Git	Latest	For cloning the repository

TIP

The project uses Node.js >= 18.0.0 as specified in package.json engines. Use nvm to manage Node.js versions.

Setup Steps

1. Clone the Repository

git clone <repository-url>
cd uberlotto-v2

2. Install Dependencies

npm ci

WARNING

Use npm ci (not npm install) for deterministic installs from the lockfile. This ensures all developers use identical dependency versions.

3. Configure Environment Variables

cp .env.example .env

Fill in all required values in .env. See the Environment Variables Reference for details on each variable.

4. Link Shopify Store

Connect your local project to a Shopify store:

shopify hydrogen link

This links the project to your Shopify store and configures the Hydrogen storefront. You'll be prompted to select the store and storefront to connect.

5. Start the Dev Server

npm run dev

This runs shopify hydrogen dev --codegen, which:

• Starts the Vite development server with HMR
• Spins up a local Oxygen runtime (Mini Oxygen)
• Watches GraphQL files and auto-generates TypeScript types
• Enables the PWA service worker in dev mode

The dev server will be available at http://localhost:3000.

6. Customer Account API Setup

To use the /account section locally, follow the Shopify Customer Account API setup:

1. Set up a public domain for local development (e.g., using ngrok or Cloudflare tunnel)
2. Configure the Customer Account API redirect URIs in Shopify Admin

See Shopify's Customer Account API guide for detailed instructions.

Common Development Commands

GraphQL Codegen

Generate TypeScript types from GraphQL queries:

npm run codegen

This runs shopify hydrogen codegen to scan all .ts/.tsx files for GraphQL queries and generates type definitions in storefrontapi.generated.d.ts and customer-accountapi.generated.d.ts.

TIP

Codegen runs automatically in watch mode during npm run dev. Run it manually after adding new GraphQL queries outside the dev server.

TypeScript Type Checking

npm run typecheck

Runs tsc --noEmit to check all TypeScript files without producing output.

Linting

npm run lint

Runs ESLint across the project. The config is in eslint.config.js and uses @typescript-eslint, React, and JSX a11y plugins.

Production Build

npm run build

Creates a production build with shopify hydrogen build --codegen. Output goes to the dist/ directory.

Preview Production Build

npm run preview

Runs shopify hydrogen preview --build to preview the production build locally using Mini Oxygen.

Project Structure at a Glance

After setup, the key directories are:

uberlotto-v2/
├── app/              # Application source code
│   ├── routes/       # File-based route definitions
│   ├── components/   # React components
│   ├── lib/          # Core utilities and context
│   ├── store/        # Zustand state stores
│   └── ...
├── public/           # Static assets
├── supabase/         # Database migrations
├── server.ts         # Oxygen worker entry point
├── vite.config.ts    # Vite + Hydrogen + PWA config
└── .env              # Environment variables (gitignored)

See the Project Structure guide for a detailed breakdown.

Vite Configuration

The project uses several Vite plugins configured in vite.config.ts:

Plugin	Purpose
@tailwindcss/vite	Tailwind CSS v4 integration
@shopify/hydrogen/vite	Hydrogen framework support
@shopify/mini-oxygen/vite	Local Oxygen runtime emulation
@react-router/dev/vite	React Router v7 file-based routing
vite-tsconfig-paths	TypeScript path alias resolution
vite-plugin-pwa	PWA manifest, service worker, offline support

PWA Dev Mode

The PWA service worker is enabled in development (devOptions.enabled: true). This allows testing offline behavior and install prompts during local development.

Troubleshooting

SESSION_SECRET environment variable is not set

Make sure your .env file exists and contains a valid SESSION_SECRET value. The app will throw at startup if this is missing.

GraphQL type errors after adding queries

Run npm run codegen to regenerate types, or restart the dev server which runs codegen in watch mode.

CJS/ESM compatibility errors

If you see ReferenceError: module is not defined for a dependency, add the package to the ssr.optimizeDeps.include array in vite.config.ts.