256 lines
4.2 KiB
Markdown
256 lines
4.2 KiB
Markdown
# 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
|
|
|