diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..fef9e5c --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,266 @@ +# Development Guide + +This monorepo uses [Turborepo](https://turbo.build/) to manage builds, development, and testing across multiple packages and applications. + +## Repository Structure + +``` +xtablo-source/ +├── apps/ +│ ├── main/ # Main application (@xtablo/main) +│ └── external/ # External application (@xtablo/external) +├── packages/ +│ ├── shared/ # Shared utilities and logic (@xtablo/shared) +│ └── ui/ # UI component library (@xtablo/ui) +``` + +## Prerequisites + +- Node.js >= 18 +- pnpm >= 10.19.0 + +## Getting Started + +```bash +# Install dependencies +pnpm install + +# Start development (packages are source-only, no build needed) +pnpm dev +``` + +## Available Commands + +### Building + +```bash +# Build all apps (packages are source-only, consumed directly by bundlers) +pnpm build + +# Build only apps (main, external) +pnpm build:apps +``` + +**Note:** The `@xtablo/shared` and `@xtablo/ui` packages are source-only packages. They export TypeScript source files directly and are consumed by app bundlers (Vite) without a separate build step. This is faster and simpler for development. + +### Development + +```bash +# Run all apps in development mode +pnpm dev + +# Run specific app +pnpm dev:main # Main app only +pnpm dev:external # External app only +``` + +**Note:** Since packages are source-only, there's no need to run them in watch mode. Changes to package files are instantly picked up by the app's bundler (Vite) through hot module replacement. + +### Testing + +```bash +# Run all tests +pnpm test + +# Run tests in watch mode +pnpm test:watch + +# Run tests for specific package +cd apps/main && pnpm test +cd apps/main && pnpm test:watch +cd apps/main && pnpm test:coverage +``` + +### Linting & Formatting + +```bash +# Check all packages +pnpm lint + +# Fix linting issues +pnpm lint:fix + +# Format code +pnpm format + +# Type checking +pnpm typecheck +``` + +### Cleaning + +```bash +# Clean all build artifacts +pnpm clean + +# Clean specific app +cd apps/main && pnpm clean +``` + +## Turborepo Features + +### Smart Caching + +Turborepo caches build outputs and skips unnecessary work: + +- Build outputs are cached based on input files +- If nothing changed, builds are instant +- Cache is shared across the team (when configured) + +### Parallel Execution + +Tasks run in parallel when possible: + +```bash +# Runs lint on all packages simultaneously +pnpm lint +``` + +### Task Dependencies + +Turborepo automatically handles task dependencies: + +- `build` depends on `^build` (builds dependencies first, though packages are source-only) +- Tasks run in topological order based on package dependencies + +### Filtering + +Run commands for specific packages: + +```bash +# Build only main app and its dependencies +turbo build --filter=@xtablo/main + +# Build only packages +turbo build --filter='./packages/*' + +# Build everything except external +turbo build --filter='!@xtablo/external' +``` + +## Package Development Workflow + +### 1. Working on Packages + +Since packages are source-only, just run your app and edit package files directly: + +```bash +# Just run your app - changes to packages are instantly reflected +pnpm dev:main + +# Or run all apps +pnpm dev +``` + +The app's bundler (Vite) will automatically detect changes in `packages/shared` and `packages/ui` and hot-reload them. + +### 2. Adding a New Package + +1. Create the package in `packages/` +2. For source-only packages (like shared/ui), add these scripts to `package.json`: + ```json + { + "scripts": { + "lint": "biome check .", + "lint:fix": "biome check --write .", + "format": "biome format --write .", + "typecheck": "tsc --noEmit" + } + } + ``` +3. Set up exports in `package.json`: + ```json + { + "main": "./src/index.ts", + "types": "./src/index.ts", + "exports": { + ".": "./src/index.ts" + } + } + ``` +4. Add to workspace in `pnpm-workspace.yaml` (if not already included by glob) +5. Run `pnpm install` to link the package + +### 3. Testing Changes Across Packages + +When making changes that affect multiple packages: + +```bash +# Type check everything +pnpm typecheck + +# Run all tests +pnpm test + +# Lint everything +pnpm lint +``` + +## Performance Tips + +1. **Source-Only Packages**: Packages consume TypeScript directly for instant feedback +2. **Selective Builds**: Use filters to build only the apps you need +3. **Clean When Stuck**: Run `pnpm clean` if you encounter weird caching issues +4. **Hot Module Replacement**: Vite provides instant updates when editing package files + +## Troubleshooting + +### Build Errors + +If you encounter build errors: + +```bash +# Clean everything and rebuild +pnpm clean +pnpm install +pnpm build +``` + +### Type Errors in Apps + +If apps show type errors for packages: + +```bash +# Check TypeScript configuration in packages +cd packages/shared && pnpm typecheck +cd packages/ui && pnpm typecheck + +# Restart your IDE's TypeScript server +# In VS Code: Cmd+Shift+P > "TypeScript: Restart TS Server" +``` + +### Cache Issues + +If builds seem stale: + +```bash +# Clear Turbo cache +rm -rf node_modules/.cache/turbo + +# Clean and rebuild +pnpm clean +pnpm build +``` + +## CI/CD Considerations + +For CI/CD pipelines: + +```bash +# Install dependencies +pnpm install --frozen-lockfile + +# Build everything +pnpm build + +# Run all checks +pnpm lint +pnpm typecheck +pnpm test +``` + +## Additional Resources + +- [Turborepo Documentation](https://turbo.build/repo/docs) +- [pnpm Workspaces](https://pnpm.io/workspaces) +- [TypeScript Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) diff --git a/README.md b/README.md index 4afad3d..659a09e 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ xtablo-source/ │ ├── main/ # Main UI application │ └── external/ # External booking widget microfrontend ├── packages/ -│ ├── ui-components/ # Shared UI components (buttons, inputs, etc.) +│ ├── ui/ # Shared UI components (buttons, inputs, etc.) │ └── shared/ # Shared utilities, hooks, contexts, and types ├── api/ # TypeScript/Node.js API ├── backend/ # Python backend @@ -22,72 +22,54 @@ xtablo-source/ ### Prerequisites -- Node.js 18+ and pnpm +- Node.js 18+ and pnpm 10.19.0+ - For other services: Python 3.11+, Go 1.21+ -### Installation - -Install all dependencies: +### Quick Start ```bash +# Install dependencies pnpm install + +# Start development (packages are source-only, no build needed) +pnpm dev ``` -This will install dependencies for all apps and packages in the workspace. +For detailed development workflows, see [DEVELOPMENT.md](./DEVELOPMENT.md). -### Development - -Run all apps in development mode: +### Common Commands ```bash -turbo dev -``` +# Development +pnpm dev # Run all apps +pnpm dev:main # Run main app only +pnpm dev:external # Run external app only -Run specific app: +# Building +pnpm build # Build all apps +pnpm build:apps # Build apps only -```bash -# Main UI app (http://localhost:5173) -turbo dev --filter @xtablo/main +# Testing & Quality +pnpm test # Run all tests +pnpm lint # Check all packages +pnpm lint:fix # Fix linting issues +pnpm typecheck # Type check everything -# External microfrontend (http://localhost:5174) -turbo dev --filter @xtablo/external -``` - -### Building - -Build all apps: - -```bash -turbo build -``` - -Build specific app: - -```bash -turbo build --filter @xtablo/main -turbo build --filter @xtablo/external -``` - -### Linting and Formatting - -```bash -# Lint all packages -turbo lint - -# Format all packages -turbo format +# Cleaning +pnpm clean # Clean all build artifacts ``` ## Packages -### @xtablo/ui-components +### @xtablo/ui Shared UI components library used across the main and external apps. Contains all base UI components like buttons, inputs, dialogs, etc. **Usage:** ```typescript -import { Button, Input, Dialog } from "@xtablo/ui-components"; +import { Button } from "@xtablo/ui/components/button"; +import { Input } from "@xtablo/ui/components/input"; ``` ### @xtablo/shared @@ -129,22 +111,20 @@ This monorepo uses Turborepo for: - **Dependency management**: Automatic build ordering based on package dependencies - **Code sharing**: Easy sharing of components and utilities between apps -## Scripts +## Development Workflow -- `turbo dev` - Start all apps in development mode -- `turbo build` - Build all apps -- `turbo lint` - Lint all packages -- `turbo format` - Format all packages -- `turbo typecheck` - Type check all packages -- `turbo test` - Run tests for all packages -- `turbo clean` - Clean all build artifacts and node_modules +For comprehensive development documentation including: + +- Package development workflow +- Testing strategies +- Troubleshooting guide +- CI/CD setup + +See [DEVELOPMENT.md](./DEVELOPMENT.md) ## Adding a New Package -1. Create a new directory under `packages/` -2. Add a `package.json` with name `@xtablo/package-name` -3. Update `pnpm-workspace.yaml` if needed (already configured for `packages/*`) -4. Install in your app: `pnpm --filter @xtablo/your-app add @xtablo/package-name@workspace:*` +See the "Adding a New Package" section in [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed instructions. ## Migration Notes @@ -154,19 +134,21 @@ This project was migrated from a single UI app to a Turborepo monorepo with the - **After**: - `apps/main/` - Main application - `apps/external/` - Separate microfrontend for booking widgets - - `packages/ui-components/` - Shared UI components + - `packages/ui/` - Shared UI components - `packages/shared/` - Shared utilities and logic -All import paths have been updated to use workspace packages (`@xtablo/ui-components`, `@xtablo/shared`). +All import paths have been updated to use workspace packages (`@xtablo/ui`, `@xtablo/shared`). ## Contributing When adding new shared code: -1. Add to the appropriate package (`ui-components` for UI, `shared` for logic/utils) -2. Export from the package's `index.ts` +1. Add to the appropriate package (`ui` for UI components, `shared` for logic/utils) +2. Export from the package's appropriate entry point 3. Use the workspace import in your apps +For more details, see [DEVELOPMENT.md](./DEVELOPMENT.md) + ## License [Your License Here] diff --git a/apps/external/package.json b/apps/external/package.json index 3594da0..59a0bb3 100644 --- a/apps/external/package.json +++ b/apps/external/package.json @@ -10,7 +10,8 @@ "lint": "biome check .", "lint:fix": "biome check --write .", "format": "biome format --write .", - "preview": "vite preview" + "preview": "vite preview", + "clean": "rm -rf dist .vite tsconfig.tsbuildinfo node_modules/.vite" }, "devDependencies": { "@biomejs/biome": "2.2.5", diff --git a/apps/external/tsconfig.json b/apps/external/tsconfig.json index 355ae89..2ab9471 100644 --- a/apps/external/tsconfig.json +++ b/apps/external/tsconfig.json @@ -24,9 +24,6 @@ } }, "include": ["src"], - "references": [ - { "path": "../../packages/ui" }, - { "path": "../../packages/shared" } - ] + "references": [] } diff --git a/apps/main/package.json b/apps/main/package.json index 1728c49..9fcd83e 100644 --- a/apps/main/package.json +++ b/apps/main/package.json @@ -18,7 +18,8 @@ "cf-typegen": "wrangler types", "test": "vitest run --mode dev --passWithNoTests", "test:watch": "vitest watch --passWithNoTests", - "test:coverage": "vitest run --coverage --passWithNoTests" + "test:coverage": "vitest run --coverage --passWithNoTests", + "clean": "rm -rf dist .vite tsconfig.tsbuildinfo node_modules/.vite" }, "devDependencies": { "@biomejs/biome": "2.2.5", diff --git a/apps/main/src/providers/UserStoreProvider.tsx b/apps/main/src/providers/UserStoreProvider.tsx index e45580b..704b61b 100644 --- a/apps/main/src/providers/UserStoreProvider.tsx +++ b/apps/main/src/providers/UserStoreProvider.tsx @@ -1,5 +1,5 @@ import { useQuery } from "@tanstack/react-query"; -import { useSession } from "@xtablo/shared"; +import { useSession } from "@xtablo/shared/contexts/SessionContext"; import { api } from "../lib/api"; import { Tables } from "@xtablo/shared/types/database.types"; import React from "react"; diff --git a/apps/main/stats.html b/apps/main/stats.html index 32b6cbf..52342af 100644 --- a/apps/main/stats.html +++ b/apps/main/stats.html @@ -4929,7 +4929,7 @@ var drawChart = (function (exports) {