arthur/xtablo-source
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions 7

Improve turbo setup

Browse source
This commit is contained in:
Arthur Belleville 2025-10-23 21:05:49 +02:00
parent 58e3696c14
commit 00c844e8d5
No known key found for this signature in database
14 changed files with 712 additions and 82 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

266
DEVELOPMENT.md Normal file
View file

@ -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)

102
README.md
View file

@ -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]

3
apps/external/package.json vendored
View file

@ -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",

5
apps/external/tsconfig.json vendored
View file

@ -24,9 +24,6 @@
}
},
"include": ["src"],
"references": [
{ "path": "../../packages/ui" },
{ "path": "../../packages/shared" }
]
"references": []
}

3
apps/main/package.json
View file

@ -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",

2
apps/main/src/providers/UserStoreProvider.tsx
View file

@ -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";

2
apps/main/stats.html
View file

File diff suppressed because one or more lines are too long

2
apps/main/vite.config.d.ts vendored
View file

@ -1,2 +0,0 @@
declare const _default: import("vite").UserConfig;
export default _default;

187
docs/.turbo-setup-summary.md Normal file
View file

@ -0,0 +1,187 @@
# Turborepo Setup Summary
This document summarizes the Turborepo configuration improvements made to the xtablo monorepo.
## Overview
The monorepo now has a clear, efficient Turborepo setup with:
- **Source-only packages** (`@xtablo/shared`, `@xtablo/ui`) - no build step needed
- **Smart caching** for all tasks (build, test, lint, typecheck)
- **Clear task dependencies** and parallel execution
- **Comprehensive documentation** for all workflows
## Key Changes
### 1. Turborepo Configuration (`turbo.json`)
**Improvements:**
- Added explicit `inputs` for better cache invalidation
- Removed unnecessary `^build` dependencies for `dev`, `typecheck`, and `test` tasks
- Added `outputLogs` configuration for cleaner output
- Added `test:watch` task for interactive testing
**Task Configuration:**
- `build`: Only apps build, packages are source-only
- `dev`: No dependencies, instant start with HMR
- `lint`, `format`, `typecheck`, `test`: Run independently without waiting for builds
### 2. Package Configuration
#### Shared Package (`packages/shared/package.json`)
- **Removed:** `build`, `dev`, `clean` scripts
- **Kept:** `lint`, `lint:fix`, `format`, `typecheck`
- **Exports:** Point directly to TypeScript source files in `src/`
#### UI Package (`packages/ui/package.json`)
- **Removed:** `build`, `dev`, `clean` scripts
- **Kept:** `lint`, `lint:fix`, `format`, `typecheck`
- **Exports:** Point directly to TypeScript source files in `src/`
#### TypeScript Configuration
- Removed `composite`, `incremental`, and `outDir` from package tsconfigs
- Packages don't output built files anymore
### 3. Root Scripts (`package.json`)
**Added:**
- `build:apps` - Build only applications
- `dev:main` - Run main app only
- `dev:external` - Run external app only
- `lint:fix` - Fix linting issues across all packages
- `test:watch` - Run tests in watch mode
**Removed:**
- `build:packages` - No longer needed
- `clean:packages` - No longer needed
### 4. App Scripts
**Main App (`apps/main/package.json`):**
- Added `clean` script to remove build artifacts
**External App (`apps/external/package.json`):**
- Added `clean` script to remove build artifacts
### 5. Documentation
Created comprehensive documentation:
1. **DEVELOPMENT.md** (267 lines)
- Complete development guide
- Package development workflow
- Troubleshooting section
- CI/CD considerations
2. **TURBO_CHEATSHEET.md**
- Quick reference for common commands
- Turbo filter examples
- Common workflows
- Troubleshooting tips
3. **Updated README.md**
- Simplified quick start
- References to detailed documentation
- Updated commands and structure
## Benefits
### Performance
- ⚡ **Faster dev startup**: No package build step required
- 🔥 **Instant HMR**: Vite hot-reloads package changes immediately
- 📦 **Smaller cache**: No package build artifacts to cache
### Developer Experience
- 🎯 **Simpler workflow**: Just `pnpm dev` to start
- 📚 **Clear documentation**: Three levels of docs (README, DEVELOPMENT, CHEATSHEET)
- 🧹 **Less complexity**: Fewer build steps to manage
### Maintainability
- 🔧 **Fewer moving parts**: Source-only packages are simpler
- 📝 **Better DX**: TypeScript types always in sync
- 🚀 **Future-proof**: Modern bundler-native approach
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ xtablo-source │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Apps (Build with Vite) │ │
│ │ │ │
│ │ ├── @xtablo/main (main UI app) │ │
│ │ └── @xtablo/external (booking widget) │ │
│ └──────────────────────────────────────────────────────┘ │
│ ▲ │
│ │ │
│ imports (HMR) │
│ │ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Packages (Source-Only, No Build) │ │
│ │ │ │
│ │ ├── @xtablo/shared (hooks, utils, types) │ │
│ │ └── @xtablo/ui (components) │ │
│ │ │ │
│ │ Exports: ./src/**/*.ts(x) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## Quick Commands
```bash
# Development
pnpm dev # Start all apps
pnpm dev:main # Start main app
# Build
pnpm build # Build all apps
pnpm build:apps # Same as above
# Quality
pnpm typecheck # Type check everything
pnpm lint # Lint everything
pnpm lint:fix # Fix linting issues
pnpm test # Run all tests
pnpm test:watch # Run tests in watch mode
# Cleanup
pnpm clean # Clean build artifacts
```
## Migration Notes
If you have existing `dist/` folders in packages:
```bash
rm -rf packages/*/dist packages/*/tsconfig.tsbuildinfo
```
No other migration is needed - packages now export source files directly.
## Next Steps
1. Run `pnpm install` to ensure workspace links are updated
2. Run `pnpm typecheck` to verify everything compiles
3. Run `pnpm dev` to start development
4. Read [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed workflows
## Resources
- 📚 [DEVELOPMENT.md](./DEVELOPMENT.md) - Full development guide
- 📋 [TURBO_CHEATSHEET.md](./TURBO_CHEATSHEET.md) - Quick reference
- 📖 [Turborepo Docs](https://turbo.build/repo/docs)
- 🔗 [pnpm Workspaces](https://pnpm.io/workspaces)

179
docs/TURBO_CHEATSHEET.md Normal file
View file

@ -0,0 +1,179 @@
# Turborepo Quick Reference
## 🚀 Quick Start
```bash
pnpm install # Install dependencies
pnpm dev # Start development (packages are source-only)
```
## 📦 Package Commands
| Command | Description |
| ------------------- | ----------------------------------------- |
| `pnpm build` | Build all apps (packages are source-only) |
| `pnpm build:apps` | Build only apps |
| `pnpm dev` | Start all apps in dev mode |
| `pnpm dev:main` | Start main app only |
| `pnpm dev:external` | Start external app only |
| `pnpm test` | Run all tests |
| `pnpm test:watch` | Run tests in watch mode |
| `pnpm lint` | Lint all packages |
| `pnpm lint:fix` | Fix linting issues |
| `pnpm format` | Format all code |
| `pnpm typecheck` | Type check everything |
| `pnpm clean` | Clean build artifacts |
## 🎯 Turbo Filters
```bash
# Build specific package
turbo build --filter=@xtablo/main
turbo build --filter=@xtablo/shared
# Build all packages in a directory
turbo build --filter='./packages/*'
turbo build --filter='./apps/*'
# Build everything except one package
turbo build --filter='!@xtablo/external'
# Build a package and its dependencies
turbo build --filter=@xtablo/main...
# Build a package and its dependents
turbo build --filter=...@xtablo/shared
```
## 🔧 Package Development
### Work on packages + app
Packages are source-only (no build step), so just run your app:
```bash
# Just run your app - package changes are instantly reflected via HMR
pnpm dev:main
# Edit packages/shared or packages/ui - changes hot-reload automatically
```
### Add dependency to a package
```bash
# Add external dependency
pnpm --filter @xtablo/main add react-query
# Add workspace dependency
pnpm --filter @xtablo/main add @xtablo/shared@workspace:*
# Add dev dependency
pnpm --filter @xtablo/shared add -D typescript
```
## 🧹 Cleanup
```bash
# Clean everything
pnpm clean
# Clean Turbo cache
rm -rf node_modules/.cache/turbo
# Nuclear option (rebuild from scratch)
pnpm clean && pnpm install && pnpm build
```
## 📊 Performance
```bash
# Run with timing
turbo build --summarize
# Run without cache
turbo build --force
# Dry run (see what would run)
turbo build --dry-run
```
## 🐛 Troubleshooting
### "Module not found" errors
```bash
pnpm install # Reinstall dependencies
pnpm typecheck # Check for type errors
```
### Type errors in apps
```bash
cd packages/shared && pnpm typecheck
cd packages/ui && pnpm typecheck
# Restart your IDE's TypeScript server
```
### Stale cache
```bash
rm -rf node_modules/.cache/turbo
pnpm clean
pnpm build
```
### Everything broken
```bash
pnpm clean
rm -rf node_modules pnpm-lock.yaml
pnpm install
pnpm build
```
## 📝 Common Workflows
### Start new feature
```bash
pnpm dev:main # Start your app (packages are source-only)
```
### Test changes across packages
```bash
pnpm build # Build everything
pnpm typecheck # Check types
pnpm test # Run tests
pnpm lint # Check linting
```
### Before committing
```bash
pnpm lint:fix # Fix linting
pnpm format # Format code
pnpm typecheck # Check types
pnpm test # Run tests
```
## 🏗️ Project Structure
```
xtablo-source/
├── apps/
│ ├── main/ (@xtablo/main) - Main application
│ └── external/ (@xtablo/external) - External booking widget
├── packages/
│ ├── shared/ (@xtablo/shared) - Source-only: utilities, hooks, types
│ └── ui/ (@xtablo/ui) - Source-only: UI components
└── turbo.json (Turbo configuration)
```
**Note:** Packages are source-only (export TypeScript directly). Apps consume them via Vite bundler.
## 🔗 Useful Links
- [Full Development Guide](./DEVELOPMENT.md)
- [Turborepo Docs](https://turbo.build/repo/docs)
- [pnpm Workspaces](https://pnpm.io/workspaces)

5
package.json
View file

@ -6,11 +6,16 @@
"packageManager": "pnpm@10.19.0",
"scripts": {
"build": "turbo build",
"build:apps": "turbo build --filter='./apps/*'",
"dev": "turbo dev",
"dev:main": "turbo dev --filter=@xtablo/main",
"dev:external": "turbo dev --filter=@xtablo/external",
"lint": "turbo lint",
"lint:fix": "turbo lint:fix",
"format": "turbo format",
"typecheck": "turbo typecheck",
"test": "turbo test",
"test:watch": "turbo test:watch",
"clean": "turbo clean && rm -rf node_modules"
},
"devDependencies": {

2
packages/shared/package.json
View file

@ -14,8 +14,6 @@
"./utils/*": "./src/utils/*"
},
"scripts": {
"build": "tsc",
"dev": "tsc --watch",
"lint": "biome check .",
"lint:fix": "biome check --write .",
"format": "biome format --write .",

5
packages/ui/tsconfig.json
View file

@ -17,9 +17,6 @@
"jsx": "react-jsx"
},
"include": ["src"],
"exclude": ["node_modules", "dist"],
"references": [
// { "path": "../shared" }
]
"exclude": ["node_modules", "dist"]
}

31
turbo.json
View file

@ -4,21 +4,40 @@
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", ".next/**", "!.next/cache/**"]
"inputs": [
"src/**",
"tsconfig.json",
"tsconfig.*.json",
"vite.config.ts",
"package.json"
],
"outputs": ["dist/**", ".next/**", "!.next/cache/**", "tsconfig.tsbuildinfo"],
"outputLogs": "new-only"
},
"dev": {
"cache": false,
"persistent": true
},
"lint": {
"dependsOn": ["^build"]
"inputs": ["src/**", "biome.json", "package.json"],
"outputLogs": "new-only"
},
"format": {},
"typecheck": {
"dependsOn": ["^build"]
"format": {
"inputs": ["src/**", "biome.json", "package.json"],
"outputLogs": "errors-only"
},
"typecheck": {
"inputs": ["src/**", "tsconfig.json", "tsconfig.*.json", "package.json"],
"outputLogs": "new-only"
},
"test": {
"dependsOn": ["^build"]
"inputs": ["src/**", "**/*.test.ts", "**/*.test.tsx", "vitest.config.ts", "package.json"],
"outputs": ["coverage/**"],
"outputLogs": "new-only"
},
"test:watch": {
"cache": false,
"persistent": true
},
"clean": {
"cache": false