# Shared Packages Migration Guide

**Date**: 2025-01-27
**Purpose**: Guide for migrating projects to use shared packages
**Status**: Complete

---

## Overview

This guide provides instructions for migrating projects to use shared packages from `workspace-shared/`.

---

## Available Packages

1. **@workspace/shared-types** - TypeScript types
2. **@workspace/shared-auth** - Authentication utilities
3. **@workspace/shared-utils** - Utility functions
4. **@workspace/shared-config** - Configuration schemas
5. **@workspace/api-client** - API client utilities
6. **@workspace/validation** - Validation schemas
7. **@workspace/blockchain** - Blockchain utilities

---

## Migration Steps

### Step 1: Install Shared Package

#### Using pnpm (Recommended)

```bash
cd your-project
pnpm add @workspace/shared-types@workspace:*
```

#### Using npm

```bash
npm install @workspace/shared-types
```

### Step 2: Update Imports

#### Before

```typescript
// Local types
import { User, ApiResponse } from './types';

// Local utilities
import { formatDate, validateEmail } from './utils';

// Local auth
import { verifyToken } from './auth';
```

#### After

```typescript
// Shared types
import { User, ApiResponse } from '@workspace/shared-types';

// Shared utilities
import { formatDate, validateEmail } from '@workspace/shared-utils';

// Shared auth
import { verifyToken } from '@workspace/shared-auth';
```

### Step 3: Remove Duplicate Code

1. Identify code replaced by shared packages
2. Remove duplicate implementations
3. Update all references
4. Test thoroughly

### Step 4: Update Configuration

#### package.json

```json
{
  "dependencies": {
    "@workspace/shared-types": "workspace:*",
    "@workspace/shared-utils": "workspace:*",
    "@workspace/shared-auth": "workspace:*"
  }
}
```

#### tsconfig.json

```json
{
  "compilerOptions": {
    "paths": {
      "@workspace/*": ["../workspace-shared/packages/*/src"]
    }
  }
}
```

---

## Package-Specific Migration

### @workspace/shared-types

**Use for**: Common TypeScript types

```typescript
import { User, ApiResponse, DatabaseConfig } from '@workspace/shared-types';
```

### @workspace/shared-auth

**Use for**: Authentication and authorization

```typescript
import {
  verifyJWT,
  hashPassword,
  checkPermission
} from '@workspace/shared-auth';
```

### @workspace/shared-utils

**Use for**: Utility functions

```typescript
import {
  formatDate,
  generateUUID,
  validateEmail
} from '@workspace/shared-utils';
```

### @workspace/shared-config

**Use for**: Configuration management

```typescript
import {
  loadEnv,
  validateConfig,
  getConfig
} from '@workspace/shared-config';
```

### @workspace/api-client

**Use for**: API client functionality

```typescript
import {
  createApiClient,
  addInterceptor
} from '@workspace/api-client';
```

### @workspace/validation

**Use for**: Data validation

```typescript
import {
  userSchema,
  validateUser
} from '@workspace/validation';
```

### @workspace/blockchain

**Use for**: Blockchain utilities

```typescript
import {
  createProvider,
  formatEther,
  getContract
} from '@workspace/blockchain';
```

---

## Best Practices

### Version Management
- Use `workspace:*` for development
- Pin versions for production
- Update regularly

### Code Organization
- Import only what you need
- Avoid deep imports
- Use type-only imports when possible

### Testing
- Test after migration
- Verify functionality
- Check for breaking changes

---

## Troubleshooting

### Package Not Found

**Issue**: `Cannot find module '@workspace/shared-types'`

**Solution**:
- Run `pnpm install`
- Check package.json
- Verify workspace configuration

### Type Errors

**Issue**: Type errors after migration

**Solution**:
- Check type compatibility
- Update type definitions
- Review breaking changes

### Build Errors

**Issue**: Build fails after migration

**Solution**:
- Check import paths
- Verify dependencies
- Review build configuration

---

## Migration Checklist

- [ ] Install shared packages
- [ ] Update imports
- [ ] Remove duplicate code
- [ ] Update configuration
- [ ] Test functionality
- [ ] Update documentation
- [ ] Review dependencies
- [ ] Verify build
- [ ] Deploy to staging
- [ ] Monitor for issues

---

**Last Updated**: 2025-01-27