Packages Documentation

Shared workspace packages and their APIs

📋 Overview

Izri uses a monorepo structure with shared packages that provide common functionality across the frontend and backend. This section documents each package, its purpose, and how to use it.

📦 Package List

Core Packages

@izri/database - Drizzle ORM, schema, and migrations
@izri/trpc - tRPC router definitions and context
@izri/shared - Shared utilities and types
@izri/auth - Authentication utilities (Better Auth)

Service Packages

AI Service - Python FastAPI service for AI operations
Repo Analyzer - Repository analysis tools

🔧 Using Packages

Import from Packages

// Database
import { db, users, projects } from '@izri/database'
import { eq } from 'drizzle-orm'

// tRPC
import { appRouter } from '@izri/trpc'
import type { AppRouter } from '@izri/trpc'

// Shared
import { formatDate, logger } from '@izri/shared'

// Types
import type { Project, User } from '@izri/database'

Adding Dependencies to Packages

# Add to specific package
pnpm --filter @izri/database add drizzle-orm

# Add dev dependency
pnpm --filter @izri/shared add -D @types/node

📚 Package Documentation

@izri/database

Database access layer with Drizzle ORM

Schema definitions
Database client
Migration workflow
Seed scripts
Query patterns

@izri/trpc

tRPC server implementation

Router structure
Procedure definitions
Context setup
Type exports

@izri/shared

Common utilities and types

Utility functions
Shared types
Constants
Helpers

@izri/auth

Authentication utilities

Better Auth setup
Session management
Auth helpers
Token utilities

AI Service

Python FastAPI service

FastAPI setup
AI model integration
Analysis endpoints
Test generation

Repo Analyzer

Repository analysis tools

Code analysis
Dependency detection
Framework detection
File structure parsing

🔄 Package Dependencies

graph TD
    A[@izri/shared] --> B[@izri/database]
    A --> C[@izri/trpc]
    A --> D[@izri/auth]
    B --> C
    B --> D
    C --> E[@izri/api]
    C --> F[@izri/web]
    D --> E
    A --> E
    A --> F

🚀 Development Workflow

Building Packages

# Build all packages
pnpm build:packages

# Build specific package
pnpm --filter @izri/database build

# Watch mode (during development)
pnpm --filter @izri/shared dev

Type Checking

# Check all packages
pnpm type:check:packages

# Check specific package
pnpm --filter @izri/trpc type:check

Testing

# Test all packages
pnpm test

# Test specific package
pnpm --filter @izri/database test

📦 Creating a New Package

# 1. Create package directory
mkdir packages/my-package

# 2. Initialize package
cd packages/my-package
pnpm init

# 3. Configure package.json
{
  "name": "@izri/my-package",
  "version": "1.0.0",
  "main": "./lib/index.js",
  "types": "./lib/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "clean": "rm -rf lib"
  }
}

# 4. Create tsconfig.json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./lib",
    "rootDir": "./src"
  },
  "include": ["src"]
}

# 5. Create src/ directory
mkdir src
echo "export const hello = 'world'" > src/index.ts

# 6. Build
pnpm build

# 7. Use in other packages
# Add to package.json dependencies:
# "@izri/my-package": "workspace:*"

🎯 Best Practices

Package Structure

src/: Source TypeScript files
lib/ or dist/: Compiled JavaScript (gitignored)
types/: Additional type definitions
tests/: Unit tests
package.json: Package configuration
tsconfig.json: TypeScript configuration
README.md: Package documentation

Naming Conventions

Package names: @izri/package-name
Use kebab-case for package names
Use descriptive, specific names
Avoid generic names like "utils" or "helpers" alone

Exports

// src/index.ts - Single export point
export * from './utils'
export * from './types'
export * from './constants'
export { default as something } from './something'

Versioning

All packages use workspace:* for internal dependencies
External dependencies use specific version ranges
Keep dependencies up to date
Document breaking changes

🔗 Related Documentation

Architecture: Monorepo Structure
Development: Development Guide
Backend: Backend Documentation

Explore individual packages →