PrizeCart Monorepo

A monorepo for the PrizeCart Shopify app, featuring a Node.js API backend and React frontend with shared TypeScript types.

Project Structure

prizecart/
├── api/                 # Node.js + Express API backend
├── app/                 # React frontend application
├── shared/              # Shared TypeScript types and utilities
├── docs/                # Project documentation
└── package.json         # Root workspace configuration

Quick Start

Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0

Installation

# Install all dependencies across workspaces
npm run install:all

# Or install individually
npm install
npm --prefix api install
npm --prefix app install
npm --prefix shared install

Development

# Start both API and app in development mode
npm run dev

# Start only the API
npm run dev:api

# Start only the app
npm run dev:app

Building

# Build all packages
npm run build

# Build specific packages
npm run build:api
npm run build:app

Workspace Packages

@prizecart/api - Backend API

• Port: 3888 (default)
• Tech Stack: Node.js, Express, TypeScript
• Key Features:
  • Shopify OAuth integration
  • Webhook handling
  • Prize draw logic
  • JWT authentication

@prizecart/app - Frontend Application

• Port: 3000 (default)
• Tech Stack: React, TypeScript
• Key Features:
  • Customer prize draw interface
  • Prize claim form
  • Responsive design

@prizecart/shared - Shared Types

• Purpose: TypeScript type definitions shared between API and app
• Key Exports:
  • Data models (Merchant, Customer, Prize, Order, etc.)
  • API request/response types
  • Utility types and interfaces
  • Express type augmentations

Type Sharing

The monorepo uses TypeScript path mapping to share types between packages:

import type { DrawRequest, DrawResponse } from "@prizecart/shared";
// In any file, import shared types
import { Customer, Merchant, Prize } from "@prizecart/shared";

Available Shared Types

Data Models

• User, Merchant, Customer
• Prize, Order, DrawSession, Claim
• Product, ShippingAddress

API Types

• DrawRequest, DrawResponse
• ClaimRequest, MerchantInstallRequest
• ApiResponse<T>, JWTPayload

Utility Types

• Environment, PrizeCategory, UserRole
• AppConfig, DatabaseConfig, ShopifyConfig
• PaginationParams, PaginatedResponse<T>

Development Workflow

1. Adding New Types: Add them to shared/types/ and export from shared/index.ts
2. API Development: Use shared types for request/response validation
3. Frontend Development: Import shared types for component props and API calls
4. Type Safety: All packages benefit from shared type definitions
5. Code Quality: All code is automatically linted and formatted through pre-commit hooks

Environment Configuration

Create .env files in the api/ directory:

# api/.env
PORT=3888
NODE_ENV=development
MONGODB_URI=mongodb://localhost:27017/prizecart
JWT_SECRET=your-jwt-secret
SHOPIFY_API_KEY=your-shopify-api-key
SHOPIFY_API_SECRET=your-shopify-api-secret
ALLOWED_CORS_DOMAINS=localhost:3000

Scripts

Root Level

• npm run dev - Start both API and app
• npm run build - Build all packages
• npm run clean - Clean all build artifacts
• npm run install:all - Install dependencies for all workspaces

API Package

• npm --prefix api run dev - Start API in development mode
• npm --prefix api run build - Build API
• npm --prefix api run start - Start production API

App Package

• npm --prefix app run start - Start React app
• npm --prefix app run build - Build React app
• npm --prefix app run test - Run tests

Contributing

1. Make changes to shared types in shared/ directory
2. Update API and app to use new shared types
3. Ensure type safety across all packages
4. Test both API and app functionality

Troubleshooting

Type Resolution Issues

If you encounter type resolution issues:

1. Ensure all packages are installed: npm run install:all
2. Rebuild shared package: npm --prefix shared run build
3. Restart TypeScript language server in your IDE

Build Issues

If builds fail:

1. Clean all build artifacts: npm run clean
2. Reinstall dependencies: npm run install:all
3. Rebuild packages: npm run build

Code Formatting and Linting

This project uses ESLint with Antfu's configuration for consistent code formatting and linting across the entire monorepo. The setup includes automatic formatting, pre-commit hooks, and environment-specific rules.

ESLint Configuration

The project uses a modern flat config ESLint setup (eslint.config.js) with:

• Antfu's ESLint Config: Base configuration with TypeScript and React support
• Next.js Integration: Specific rules for Next.js best practices and core web vitals
• Custom Rules: Project-specific preferences including double quotes, semicolons, and 2-space indentation
• Environment-Specific Rules: Different rule sets for frontend (app/), backend (api/), and shared (shared/) code

Available Linting Scripts

Run these commands from the project root:

# Lint all files in the monorepo
npm run lint

# Automatically fix all auto-fixable linting issues
npm run lint:fix

# Lint only backend (API) files
npm run lint:api

# Lint only frontend (app) files
npm run lint:app

# Lint only shared files
npm run lint:shared

# Lint only staged files (used by pre-commit hook)
npm run lint:staged

Pre-commit Hooks

The project uses Husky to enforce code quality before commits:

• Automatic Setup: Pre-commit hooks are automatically installed when you run npm install
• Staged File Linting: Only files staged for commit are linted (fast and efficient)
• Auto-fixing: Fixable issues are automatically corrected before commit
• Commit Blocking: Commits are blocked if there are unfixable linting errors
• Clear Feedback: The hook provides clear output about any issues found

The pre-commit hook runs lint-staged, which applies eslint --fix to all staged JavaScript and TypeScript files.

IDE Setup and Integration

VS Code (Recommended)

1. Install ESLint Extension: Install the official ESLint extension from the VS Code marketplace
2. Auto-fix on Save: The project includes VS Code settings for automatic fixing on save
3. Flat Config Support: Ensure you're using ESLint extension v2.4.0+ for flat config support

Other IDEs

For other editors, ensure your ESLint plugin supports:

• Flat config format (eslint.config.js)
• Auto-fix on save functionality
• TypeScript and React file support