Skip to content

DEVELOPMENT_GUIDE.md

Latest commit

 

History

History
374 lines (256 loc) · 12.5 KB

DEVELOPMENT_GUIDE.md

File metadata and controls

374 lines (256 loc) · 12.5 KB

Development Guide & Learning Resources

A comprehensive guide for developers working on the Tentix project, covering essential concepts, best practices, and learning resources for modern monorepo development.

structure

📚 Table of Contents

🛠 Core Technologies Overview

Bun Runtime & Package Manager

Bun is a fast JavaScript runtime and package manager that serves as the foundation of our development stack. It provides significant performance improvements over traditional Node.js and npm workflows.

Key Features:

  • Ultra-fast package installation - 28x faster than npm, 12x faster than Yarn
  • Built-in bundler - No need for separate build tools in many cases
  • Native TypeScript support - Direct execution of TypeScript files
  • Workspace management - First-class monorepo support

Important Notes:

  • This project exclusively uses Bun as the package manager
  • Do not use npm, yarn, or pnpm - they will cause dependency conflicts
  • Always use bun install instead of npm install

Turborepo Monorepo Management

Turborepo orchestrates our monorepo build system, providing intelligent caching and task execution.

Key Concepts:

  • Internal Packages - Shared libraries within the monorepo
  • Task Graphs - Dependency-aware task execution
  • Remote Caching - Shared build artifacts across team members
  • Incremental Builds - Only rebuild what has changed

Hono Web Framework

Hono powers our backend API with a focus on performance and developer experience.

Key Features:

  • RPC (Remote Procedure Call) - Type-safe client-server communication
  • Middleware ecosystem - Comprehensive request/response handling
  • Edge runtime compatibility - Works across different JavaScript runtimes
  • OpenAPI integration - Automatic API documentation generation

🔧 Development Prerequisites

Required Knowledge

Before contributing to this project, developers should be familiar with:

  1. TypeScript - Advanced type system usage, generics, and utility types
  2. React 19 - Latest features including concurrent rendering and server components
  3. Modern JavaScript - ES2022+ features, async/await, modules
  4. Monorepo concepts - Package dependencies, workspace management
  5. Database fundamentals - SQL, migrations, ORM concepts

Environment Setup

# Required versions
Node.js >= 20
Bun >= 1.2.16
PostgreSQL >= 14
Docker (optional but recommended)

# Verify installations
bun --version
node --version
psql --version

💡 Key Development Concepts

1. Workspace Management with Bun

Our monorepo uses Bun workspaces to manage dependencies and shared code:

{
  "name": "tentix-v2",
  "workspaces": ["frontend", "server", "packages/*"]
}

Best Practices:

  • Use workspace:* protocol for internal dependencies
  • Keep shared packages in the packages/ directory
  • Avoid circular dependencies between packages

2. Internal Package Strategy

We use Turborepo's Just-in-Time Packages approach for maximum development speed:

  • TypeScript files are consumed directly by applications
  • No build step required for internal packages
  • Faster development iteration cycles
  • Simplified configuration

Trade-offs to Consider:

  • Cannot use TypeScript paths configuration
  • Build caching is limited to applications
  • Type errors propagate across package boundaries

3. TypeScript Project References

For large-scale TypeScript development, we implement project references to:

  • Enforce project boundaries - Prevent arbitrary imports
  • Enable incremental compilation - Faster type checking
  • Improve IDE performance - Better intellisense and navigation
  • Support build orchestration - Dependency-aware compilation

Configuration Structure:

tsconfig.json (root)
├── tsconfig.options.json (shared compiler options)
├── frontend/tsconfig.json
├── server/tsconfig.json
└── packages/*/tsconfig.json

4. RPC Type Safety with Hono

Our API uses Hono's RPC feature for end-to-end type safety:

// Server-side route definition
const route = app.post("/api/tickets", zValidator("json", ticketSchema), (c) =>
  c.json({ success: true }),
);

// Export type for client consumption
export type AppType = typeof route;

// Client-side usage with full type safety
const client = hc<AppType>("http://localhost:3000");
const result = await client.api.tickets.$post({
  json: { title: "New ticket" },
}).then(r => r.json());

📋 Best Practices & Guidelines

Code Organization

  1. Feature-based structure - Group related files by feature, not by type
  2. Barrel exports - Use index files to create clean import paths
  3. Consistent naming - Use kebab-case for files, PascalCase for components
  4. Type definitions - Keep types close to their usage

Database Management

  1. Migration-first approach - Always create migrations for schema changes
  2. Seed data management - Use scripts for consistent test data
  3. Environment isolation - Separate databases for dev/test/prod
  4. Backup strategies - Regular backups before destructive operations

Security Considerations

  1. Environment variables - Never commit secrets to version control
  2. Input validation - Validate all user inputs using Zod schemas
  3. Authentication - Implement proper JWT token management
  4. Rate limiting - Protect APIs from abuse

Performance Optimization

  1. Bundle analysis - Regular monitoring of bundle sizes
  2. Database indexing - Optimize queries with proper indexes
  3. Caching strategies - Implement appropriate caching layers
  4. Lazy loading - Load components and data on demand

⚠️ Common Pitfalls & Solutions

1. Package Manager Conflicts

Problem: Using different package managers causes lockfile conflicts.

Solution:

  • Always use bun install
  • Delete node_modules and other lockfiles if switching from npm/yarn
  • Add .npmrc with package-manager=bun to enforce usage

2. TypeScript Configuration Issues

Problem: Complex tsconfig inheritance causing compilation errors.

Solutions:

  • Use project references for large codebases
  • Keep shared options in tsconfig.options.json
  • Avoid circular references between projects
  • Use tsc --build --verbose for debugging

3. Workspace Dependency Resolution

Problem: Internal packages not resolving correctly.

Solutions:

  • Verify workspace:* syntax in package.json
  • Run bun install after adding new dependencies
  • Check that package names match directory names
  • Use absolute imports with proper path mapping

4. Database Migration Issues

Problem: Schema changes breaking existing data.

Solutions:

  • Always backup before migrations
  • Test migrations on sample data first
  • Use reversible migration patterns
  • Document breaking changes clearly

🚀 Performance Considerations

Build Performance

  1. Incremental compilation - Use TypeScript project references
  2. Parallel execution - Leverage Turborepo's task parallelization
  3. Selective builds - Only build affected packages
  4. Cache optimization - Configure proper cache keys

Runtime Performance

  1. Bundle splitting - Separate vendor and application code
  2. Tree shaking - Eliminate unused code
  3. Image optimization - Use appropriate formats and sizes
  4. Database optimization - Optimize queries and use connection pooling

Development Experience

  1. Hot reloading - Fast feedback during development
  2. Type checking - Separate type checking from compilation
  3. Linting - Fast, incremental linting
  4. Testing - Parallel test execution

📖 Learning Resources

Essential Reading

Bun Ecosystem

  • Bun Official Documentation - Comprehensive guide to Bun runtime and package manager
  • Bun Workspaces Guide - Detailed workspace configuration and management
  • Performance Benchmarks - Understanding Bun's speed advantages

Monorepo Management

  • Turborepo Core Concepts - Internal packages, task graphs, and caching strategies
  • Repository Crafting Guide - Best practices for structuring monorepos
  • Package Compilation Strategies - Just-in-time vs compiled vs publishable packages

TypeScript Advanced Topics

  • Project References - Scaling TypeScript in large codebases
  • Module Resolution - Understanding how TypeScript finds modules
  • Performance Optimization - Techniques for faster compilation

Modern Web Development

  • Hono RPC Guide - Type-safe client-server communication
  • React 19 Features - Latest React capabilities and patterns
  • Database Design - PostgreSQL optimization and best practices

Recommended Learning Path

  • Set up development environment
  • Understand Bun basics and workspace concepts
  • Learn Turborepo fundamentals
  • Study project references implementation
  • Practice advanced TypeScript patterns
  • Configure optimal development setup
  • Master Hono RPC patterns
  • Implement type-safe API communication
  • Optimize build and development workflows
  • Learn deployment strategies
  • Implement monitoring and logging
  • Optimize performance and security

Hands-On Practice

  1. Start Small - Create a simple monorepo with 2-3 packages
  2. Experiment - Try different compilation strategies
  3. Measure - Compare build times and bundle sizes
  4. Iterate - Refine configuration based on learnings

Community Resources

  • Discord Communities - Join Bun, Turborepo, and Hono Discord servers
  • GitHub Discussions - Participate in project discussions
  • Stack Overflow - Search for specific technical issues
  • YouTube Tutorials - Visual learning for complex concepts

🔍 Troubleshooting Guide

Common Issues

  1. "Cannot find module" errors

    • Check workspace configuration
    • Verify package.json names match directory names
    • Run bun install to refresh dependencies

  2. TypeScript compilation errors

    • Use tsc --build --verbose for detailed output
    • Check project references configuration
    • Verify tsconfig inheritance chain

  3. Build performance issues

    • Enable Turborepo caching
    • Use project references for TypeScript
    • Optimize task dependencies

  4. Database connection issues

    • Verify environment variables
    • Check PostgreSQL service status
    • Validate connection string format

Debug Strategies

  1. Verbose logging - Enable detailed output for all tools
  2. Incremental testing - Isolate issues to specific components
  3. Clean rebuilds - Remove cache and node_modules when stuck
  4. Version verification - Ensure all tools are at required versions

📚 References

Official Documentation

Community Resources

Performance Studies

Happy Coding! 🎉

This guide is a living document. Please contribute improvements and updates as you learn and discover new best practices.