Manual Setup

This guide covers manually wiring the Bloomreach Discovery integration without the module installer. For the recommended approach, see the Quick Start.

1. Install the API Client Package

Install the Bloomreach Discovery API client in your middleware project:

yarn add @vsf-enterprise/bloomreach-discovery-api

This package provides:

✅ Fully typed API methods generated from OpenAPI specifications
✅ Product & Category Search API
✅ Autosuggest API
✅ Content Search API
✅ Bestseller API
✅ Recommendations and Pathways API
✅ Email Widget API

2. Set Up Environment Variables

Add the following environment variables to your .env file:

# Required: Your Bloomreach account ID
BLOOMREACH_DISCOVERY_ACCOUNT_ID=your_account_id

# Required: Your Bloomreach domain key
BLOOMREACH_DISCOVERY_DOMAIN_KEY=your_domain_key

# Optional: Authentication key (required for authenticated accounts)
BLOOMREACH_DISCOVERY_AUTH_KEY=your_auth_key

# Optional: API environment ("staging" or "production", defaults to "production")
BLOOMREACH_DISCOVERY_ENVIRONMENT=production

3. Create Integration Configuration

Create the integration configuration file:

// apps/storefront-middleware/integrations/bloomreach-discovery/config.ts
import { ValidationError } from '@alokai/connect/middleware';
import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
import type { MiddlewareConfig } from '@vsf-enterprise/bloomreach-discovery-api';

const {
  BLOOMREACH_DISCOVERY_ACCOUNT_ID,
  BLOOMREACH_DISCOVERY_AUTH_KEY,
  BLOOMREACH_DISCOVERY_DOMAIN_KEY,
  BLOOMREACH_DISCOVERY_ENVIRONMENT,
} = process.env;

if (!BLOOMREACH_DISCOVERY_ACCOUNT_ID)
  throw new ValidationError('Missing env var: BLOOMREACH_DISCOVERY_ACCOUNT_ID');
if (!BLOOMREACH_DISCOVERY_DOMAIN_KEY)
  throw new ValidationError('Missing env var: BLOOMREACH_DISCOVERY_DOMAIN_KEY');

export const config = {
  configuration: {
    discoveryApi: {
      accountId: Number(BLOOMREACH_DISCOVERY_ACCOUNT_ID),
      authKey: BLOOMREACH_DISCOVERY_AUTH_KEY,
      domainKey: BLOOMREACH_DISCOVERY_DOMAIN_KEY,
      environment: BLOOMREACH_DISCOVERY_ENVIRONMENT === 'staging' ? 'staging' : 'production',
    },
  },
  extensions: (existing: ApiClientExtension[]) => [...existing],
  location: '@vsf-enterprise/bloomreach-discovery-api/server',
} satisfies Integration<MiddlewareConfig>;

4. Create Integration Index

Create an index file to export the configuration:

// apps/storefront-middleware/integrations/bloomreach-discovery/index.ts
export * from './config';

5. Create Integration Types

Create a types file to export the integration types:

// apps/storefront-middleware/integrations/bloomreach-discovery/types.ts
export type {
  Endpoints as BrDiscoveryEndpoints,
  IntegrationContext,
} from '@vsf-enterprise/bloomreach-discovery-api';

6. Register in Middleware Config

// apps/storefront-middleware/middleware.config.ts
import type { MiddlewareConfig } from '@alokai/connect/middleware';
import { config as brdConfig } from './integrations/bloomreach-discovery';

export const config = {
  integrations: {
    'bloomreach-discovery': brdConfig,
    // ... other integrations
  },
} satisfies MiddlewareConfig;

7. Create SDK Module

Key concept - SDK

The SDK provides type-safe methods to communicate with the middleware from your storefront application. Learn more in our Key concepts: SDK docs.

storefront-unified-nextjs/sdk/modules/bloomreach-discovery.ts

import type { BrDiscoveryEndpoints } from 'storefront-middleware/types';
import { defineSdkModule } from '@vue-storefront/next';

/**
 * `sdk.bloomreachDiscovery` allows you to call the Bloomreach Discovery API endpoints.
 * It provides access to search, recommendations, autosuggest, and more.
 */
export const bloomreachDiscovery = defineSdkModule(({ buildModule, config, getRequestHeaders, middlewareModule }) =>
  buildModule(middlewareModule<BrDiscoveryEndpoints>, {
    apiUrl: `${config.apiUrl}/bloomreach-discovery`,
    cdnCacheBustingId: config.cdnCacheBustingId,
    defaultRequestConfig: { headers: getRequestHeaders() },
    ssrApiUrl: `${config.ssrApiUrl}/bloomreach-discovery`,
  }),
);

Export from your modules index:

// storefront-unified-nextjs/sdk/modules/index.ts (or storefront-unified-nuxt/sdk-modules/index.ts)
export * from './bloomreach-discovery';
// ... other module exports

8. Use the SDK

The SDK module is now automatically included in your SDK configuration. Use it in your application:

import { getSdk } from '@/sdk';

const sdk = getSdk();

// Call Bloomreach Discovery API methods
const results = await sdk.bloomreachDiscovery.productSearchApi({
  q: 'running shoes',
  rows: 20,
});

For more usage examples, see the Quick Start guide.