Introduction

Hydra is a next-generation storefront accelerator built on the FLEX platform, specifically designed to unlock your headless commerce platform’s full potential. Purpose-built by commerce specialists, Hydra provides enterprise-grade solutions for SAP Commerce and VTEX platforms.

What is Hydra?

Hydra is a high-performance e-commerce storefront accelerator that combines modern web technologies with deep commerce platform integrations. Unlike generic headless solutions, Hydra is crafted by specialists who understand the unique challenges of enterprise commerce implementations.

Key Features

• Enterprise-Ready: Built specifically for SAP Commerce and VTEX platforms
• Modern Tech Stack: Leverages Next.js 15, React 19, and TypeScript
• Performance Optimized: SSR and SSG capabilities for exceptional Lighthouse scores
• Design System: Integrated Tailwind CSS with shadcn/ui components
• Content Management: Seamless Contentful CMS integration
• Developer Experience: Type-safe APIs and automated code generation

Architecture Overview

Hydra follows a modern headless architecture that separates the presentation layer from your commerce backend:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Content        │    │   Commerce      │
│   (Next.js)     │◄──►│   Management     │    │   Backend       │
│                 │    │   (Contentful)   │    │   (SAP/VTEX)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Technology Stack

Layer	Technology	Purpose
Frontend	Next.js 15	React framework with App Router
UI Library	React 19	Latest React features and optimizations
Styling	Tailwind CSS + shadcn/ui	Utility-first CSS with component library
Type Safety	TypeScript	Full type safety across the application
Content	Contentful CMS	Headless content management
Commerce	SAP Commerce / VTEX	Backend commerce platform

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18 or later)
• npm or yarn package manager
• Git for version control

Quick Start

1. Clone the Hydra repository:

   git clone https://github.com/flex-platform/hydra-web.git
   cd hydra-web

2. Install dependencies:

   npm install
   # or
   yarn install

3. Environment Configuration: Copy the example environment file and configure your settings:

   cp .env.local.example .env.local

4. Configure Environment Variables: Update your .env.local file with the required credentials:

   # SAP Commerce Configuration
   SAPCC_API_URI=your-sap-api-uri
   SAPCC_OAUTH_CLIENT_ID=your-client-id
   SAPCC_OAUTH_CLIENT_SECRET=your-client-secret
   SAPCC_MEDIA_HOST=your-media-host
   
   # Contentful Configuration
   CONTENTFUL_ENVIRONMENT=master
   CONTENTFUL_SPACE_ID=your-space-id
   CONTENTFUL_DELIVERY_API_TOKEN=your-delivery-token
   CONTENTFUL_PREVIEW_API_TOKEN=your-preview-token
   CONTENTFUL_MANAGEMENT_API_TOKEN=your-management-token

5. Start the development server:

   npm run dev
   # or
   yarn dev

6. Open your browser: Navigate to http://localhost:3000 to see your Hydra storefront.

Project Structure

Hydra follows Next.js 15 App Router conventions with additional commerce-specific organization:

hydra-web/
├── app/                    # Next.js App Router directory
│   ├── (routes)/          # Route groups
│   ├── api/               # API routes
│   ├── globals.css        # Global styles
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Home page
├── components/            # Reusable React components
│   ├── ui/                # shadcn/ui components
│   ├── commerce/          # Commerce-specific components
│   └── common/            # Shared components
├── lib/                   # Utility functions and configurations
│   ├── cms/               # Content management utilities
│   ├── commerce/          # Commerce platform integrations
│   └── utils/             # Helper functions
├── public/                # Static assets
├── types/                 # TypeScript type definitions
└── styles/                # Additional stylesheets

Core Concepts

1. Commerce Integration

Hydra provides pre-built integrations for major commerce platforms:

SAP Commerce Integration

• OCC API Integration: Direct integration with SAP’s OmniCommerce Connect APIs
• Authentication: OAuth2 flow for secure API access
• Product Catalog: Full product browsing and search capabilities
• Cart Management: Shopping cart and checkout functionality

VTEX Integration

• Headless Authentication: Built-in VTEX Headless Authentication
• VTEX API Integration: Full VTEX Store Framework API integration
• B2B and B2C Support: Flexible customer experience models

2. Content Management

Hydra integrates seamlessly with Contentful CMS:

• Content Types: Pre-defined content models for commerce
• Type Generation: Automated TypeScript type generation
• Preview Mode: Content preview for editors
• Localization: Multi-language content support

3. Performance Optimization

Built for speed and scalability:

• Server-Side Rendering (SSR): Dynamic content with optimal performance
• Static Site Generation (SSG): Pre-built pages for maximum speed
• Image Optimization: Automatic image optimization and lazy loading
• Code Splitting: Automatic code splitting for optimal bundle sizes

Development Workflow

Content Management Workflow

1. Generate Content Types:

   npm run cms:generate-types

   This command generates TypeScript types from your Contentful content model.

2. Legacy Type Generation (for older Contentful SDK versions):

   npm run cms:generate-types-legacy

Commerce Development

Hydra provides utilities for common commerce operations:

// Example: Fetching products
import { getProducts } from '@/lib/commerce/products';

const products = await getProducts({
  categoryId: 'electronics',
  pageSize: 20,
  currentPage: 1
});

Styling and Components

Hydra uses Tailwind CSS with shadcn/ui for consistent design:

// Example: Using a shadcn/ui component
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader } from '@/components/ui/card';

export function ProductCard({ product }) {
  return (
    <Card>
      <CardHeader>
        <h3>{product.name}</h3>
      </CardHeader>
      <CardContent>
        <p>{product.price}</p>
        <Button>Add to Cart</Button>
      </CardContent>
    </Card>
  );
}

Configuration

SAP Commerce Setup

To configure SAP Commerce integration:

1. Access your SAP Backoffice
2. Navigate to Auth > OAuth Clients
3. Create or locate your OAuth client credentials
4. Update your environment variables with the credentials

Contentful Setup

To configure Contentful CMS:

1. Access your Contentful space
2. Navigate to Settings > API keys
3. Create or use existing Content delivery/preview tokens
4. Update your environment variables

Support and Community

• GitHub: https://github.com/flex-storefront/Flex-Web-Hydra
• Live Preview: https://hydra.base1.com

---

Ready to transform your commerce experience? Start building with Hydra today and unlock the full potential of your headless commerce platform.