Integrations Pages Migration Plan: Next.js → Astro

adaptive-wobbling-thimble.md

Integrations Pages Migration Plan: Next.js → Astro

Status

• ✅ Phase 1: Data Infrastructure & Home Page - Complete
• ⏳ Phase 2: Category & Search Pages - In Progress
• ⏳ Phase 3: Detail & Collection Pages - Not Started

---

Overview

This document outlines migrating integration pages from a Next.js codebase to Astro with static generation powered by Contentful loaders. The plan covers four main routes: home page, category pages, integration details, and collections.

Phase 1: Data Infrastructure & Home Page ✅

Objective: Establish working home page with Contentful data integration.

Status: Complete

Contentful Loaders

Four loaders created in /src/loaders/contentful/index.ts:

1. integrationsCategories - Fetches all categories with locale-specific composite keys
2. integrationsIntegrations - Retrieves integration entries with nested category data
3. integrationsCollections - Gathers app collection data with nested integrations
4. integrationsHome - Single entry (ID: 2IisDadJQcEYvJaUSjeaYM) containing header, featured items, and prefooter content

All use composite key pattern: {entryId}:{locale} for organization.

Components & Routes

Created home page components:

• Page header with title/subtitle
• 3-column category grid with icon mapping from @doist/icons/brand
• Featured integrations section (reusing existing card components)
• App collections display
• CTA prefooter section
• Search bar for filtering integrations

The /src/pages/integrations/index.astro route queries collections by locale suffix and renders the complete layout.

Phase 2: Category & Search Pages

Objective: Enable category filtering, language selection, and search functionality.

Components

Develop category-specific components:

• Desktop sidebar navigation
• Mobile category dropdown
• Language filter picker
• Responsive integrations grid
• Search results display

Filtering Service

Implement /src/services/integrations-filter.ts supporting:

• Category slug matching (with special "all" case)
• Language code filtering via supportedLanguages field
• Query-based search matching name and tags

Dynamic Route

Create /src/pages/integrations/category/[category].astro generating paths for all category slugs across locales. The page applies filters and renders appropriate layout based on viewport.

Phase 3: Detail & Collection Pages

Objective: Complete integration detail pages and collection pages.

Integration Details

Develop components for:

• Header with logo, title, action buttons
• Details section with rich text rendering, feature lists, and image carousels
• Sticky side information (categories, languages, links)
• Installation modal (React component for interactivity)

Routes

• Integration detail: /src/pages/integrations/apps/[integration].astro with SEO metadata and JSON-LD structured data
• Collection: /src/pages/integrations/collection/[collection].astro with header and integration grid

Technical Implementation

Create rich text rendering service using "@contentful/rich-text-html-renderer" and structured data helper for SoftwareApplication schema type.

Technical Specifications

Data Architecture: Composite key organization ({id}:{locale}) enables efficient multi-locale querying.

Build Process: Astro loaders fetch all data at build time using per-locale API calls to manage memory usage.

Filtering Logic: Category → Language → Search sequence applied to integration collections.

Navigation: Search form submits to /integrations/category/all?search={query} preserving language parameters.

Images: Responsive optimization with 1x/2x densities, lazy loading for screenshots, and Cloudinary video conversion for GIFs.

Internationalization: Astro.currentLocale maps to Contentful locales; URLs generated via getRelativeLocaleUrl().

Critical Deliverables by Phase

Phase 1: ✅ Contentful loaders, home page components and route, search bar

Phase 2: Category page route, filtering service, search integration

Phase 3: Detail pages, rich text service, structured data implementation