docs/SHARED_PACKAGES_MIGRATION_GUIDE.md

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)

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

Using npm

npm install @workspace/shared-types

Step 2: Update Imports

Before

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

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

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

After

// 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

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

tsconfig.json

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

---

Package-Specific Migration

@workspace/shared-types

Use for: Common TypeScript types

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

@workspace/shared-auth

Use for: Authentication and authorization

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

@workspace/shared-utils

Use for: Utility functions

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

@workspace/shared-config

Use for: Configuration management

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

@workspace/api-client

Use for: API client functionality

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

@workspace/validation

Use for: Data validation

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

@workspace/blockchain

Use for: Blockchain utilities

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