Skip to main content

​
Marketplace Module Migration Guide

This guide explains how to update code that uses the older marketplace module patterns to use the new consolidated structure.

​
Overview of Changes

We’ve made the following major changes to the marketplace module:
  1. Consolidated Types: All marketplace types are now in types.ts (domain types) and components/types.ts (UI types)
  2. Deprecated data-service.ts: The duplicate functionality has been deprecated in favor of marketplace-service.ts
  3. Consolidated Builder Image Components: Multiple implementations merged into a single component
  4. Aligned with Domain Architecture: Followed the standard pattern of actions.ts, api.ts, schemas.ts, types.ts, and utils.ts
  5. Standardized Component Structure: Every component in its own directory with consistent file naming
  6. Documented API and Architecture: Created comprehensive documentation in Mintlify

​
Migration Steps

​
Step 1: Update Type Imports

Before: 
import { AnalyticsSummary } from '@/lib/marketplace/api';
// or
import { BuilderProfileData } from '@/components/profile/builder-profile';
// or
import { BuilderCardProps } from '@/components/marketplace/builder-card';
After: 
// For domain/business logic types
import { AnalyticsSummary, BuilderProfileData } from '@/lib/marketplace/types';

// For UI component types
import { BuilderCardProps } from '@/components/marketplace/components/types';

​
Step 2: Update API Function Imports

Before: 
import { fetchBuilders } from '@/lib/marketplace/data-service';
After: 
// For client-side code
import { fetchBuilders } from '@/lib/marketplace/api';

// For server-side code
import { fetchBuilders } from '@/lib/marketplace/marketplace-service';

​
Step 3: Use Barrel Exports

Before: 
import { fetchBuilders } from '@/lib/marketplace/api';
import { MarketplaceFilters } from '@/lib/marketplace/types';
After: 
import { fetchBuilders, MarketplaceFilters } from '@/lib/marketplace';

​
Step 4: Migrate from Deprecated Builder Image Components

Before: 
// Using one of the deprecated components
import { BuilderImage } from '@/components/marketplace/builder-image';
// or
import { SimplifiedBuilderImage } from '@/components/marketplace/simplified-builder-image';
// or
import { FixedBuilderImage } from '@/components/marketplace/fixed-builder-image';

function BuilderProfile({ builder }) {
  return (
    <div>
      <BuilderImage src={builder.avatarUrl} name={builder.name} size="large" />
      {/* or */}
      <SimplifiedBuilderImage url={builder.avatarUrl} name={builder.name} />
      {/* or */}
      <FixedBuilderImage imageUrl={builder.avatarUrl} builderName={builder.name} />
    </div>
  );
}
After: 
// Using the consolidated component
import { BuilderImage } from '@/components/marketplace/components/builder-image';

function BuilderProfile({ builder }) {
  return (
    <div>
      <BuilderImage 
        src={builder.avatarUrl} 
        alt={builder.name} 
        size="lg" 
      />
    </div>
  );
}
The consolidated component has a consistent, streamlined API:
  • src: The image URL (equivalent to src, url, imageUrl in legacy components)
  • alt: Alt text, usually the builder’s name
  • size: One of ‘sm’ | ‘md’ | ‘lg’ (small, medium, large)
  • className: Optional custom CSS classes

​
Code Patterns

​
Client-Side API Functions

Use the functions in api.ts for all client-side API calls: 
// In a React component or client-side code
import { fetchBuilders } from '@/lib/marketplace';

async function loadBuilders() {
  const builders = await fetchBuilders(1, 10, { featured: true });
  return builders;
}

​
Server-Side Functions

Use the functions in data/marketplace-service.ts for server-side operations: 
// In an API route or server component
import { fetchBuilders } from '@/lib/marketplace/data/marketplace-service';

export async function GET(req: Request) {
  const builders = await fetchBuilders(1, 10, { featured: true });
  return Response.json(builders);
}

​
Migration Timeline

  • Immediate: Begin migration to new structure for all new code
  • Within 2 Weeks: Update existing imports to use consolidated types and barrel exports
  • Within 4 Weeks: Replace all uses of deprecated components with consolidated implementations
  • Next Sprint: The data-service.ts file will display console warnings when used
  • Next Major Release (v2.5): All deprecated components and services will be removed

​
Testing Your Migration

After migrating, verify your changes by:
  1. Checking that all imports resolve correctly with npm run typecheck
  2. Running unit tests with npm test
  3. Visually confirming components render correctly in development environment
  4. Testing performance improvements from consolidated implementation

​
Testing Error Handling

The consolidated components include robust error handling that should be thoroughly tested:

​
1. Test BuilderImage Error Scenarios

// Test scenario: Missing image source
<BuilderImage 
  src={null}
  alt="John Doe"
/>

// Test scenario: Invalid image URL format
<BuilderImage 
  src="invalid-url"
  alt="John Doe"
/>

// Test scenario: Valid but non-existent image
<BuilderImage 
  src="/non-existent-image.jpg"
  alt="John Doe"
/>

// Test scenario: Network error during loading
// (Can be simulated in browser devtools by blocking the image request)
<BuilderImage 
  src="https://example.com/image.jpg"
  alt="John Doe"
/>

​
2. Component Validators

Use these validation functions to test components before and after migration: 
// Test helper: Validate BuilderImage behavior
function validateBuilderImage(component: HTMLElement) {
  // Should always have a visible element (image or fallback)
  const hasVisibleContent = Boolean(
    component.querySelector('img:not([style*="display: none"])') || 
    component.querySelector('div[class*="absolute"]')
  );
  
  // Should have the correct size classes
  const hasCorrectSizing = component.className.includes('h-12') || 
    component.className.includes('h-16') || 
    component.className.includes('h-24');
  
  return hasVisibleContent && hasCorrectSizing;
}

​
3. Visual Testing

Verify that the BuilderImage component correctly handles errors by checking:
  • Fallback displays initials when no image is available
  • No error messages or broken image icons appear
  • Different size variants maintain proportions
  • Custom classes are correctly applied
  • Component transitions smoothly when images fail to load

​
Benefits of Migration

Migrating to the consolidated marketplace architecture provides several benefits:
  1. Reduced Bundle Size: Elimination of duplicate code reduces overall bundle size
  2. Type Safety: Consolidated type system prevents type-related errors
  3. Consistent APIs: Standardized component APIs improve developer experience
  4. Better Maintainability: Simpler codebase structure makes future changes easier
  5. Performance: Optimized components with proper error handling and fallbacks