Creating a Custom Integration

If you're looking to create a custom integration for Alokai, you're in the right place. This guide will walk you through the process of creating a custom integration from scratch.

To help you scaffold a project, you can use our CLI to generate the boilerplate for your integration. To do that, run the following command:

yarn alokai-cli integration generate <integration-name> --template=<template-name>
# Example: yarn alokai-cli integration generate my-integration --template=rest-api

After the command is finished, you can find the integration in the apps/storefront-middleware/integrations/<integration-name> directory.

Templates

The integration boilerplate is generated with a template that you can choose from. You can choose from the following templates:

rest-api (default)

Use this template for REST API based integrations where there is only API documentation available. With this template:

• A developer needs to create methods and interfaces for each method that needs to be implemented
• There is an Axios client implemented out-of-the-box that sends typical REST requests to third-party backends
• Ideal when you need full control over the API calls and data transformation

graphql

Use this template to communicate with GraphQL APIs. This template:

• Uses code generation to generate schema and expose the types automatically
• Uses the graphql-request library to make GraphQL requests
• Exposes a request method that allows you to send any GraphQL query or mutation
• Perfect for GraphQL-first backends where you want type safety and schema validation

openapi

Use this template when there is an OpenAPI specification available. This template:

• Automatically generates interfaces based on the OpenAPI specification
• Creates a proxy that allows you to use any methods implemented in the OpenAPI specification
• All methods are available out-of-the-box - the developer only needs to configure the integration
• Best choice when you have a well-documented OpenAPI/Swagger specification

sdk-proxy

Use this template when you want to wrap an existing SDK. This template:

• Similar to the OpenAPI template and uses the proxy pattern
• Wraps an existing SDK and exposes its methods
• Allows you to exclude methods that shouldn't be exposed for security or other reasons
• Ideal when there's already a robust SDK available and you want to expose it through Alokai

my-integration/
├── __tests__/          # Integration and unit tests
├── ai/                 # AI agent guidance and instructions
├── api/                # API method implementations
├── client/             # HTTP client configuration
├── types/              # TypeScript type definitions
├── config.ts           # Integration configuration
├── index.server.ts     # Server-side exports
├── index.ts            # Main integration exports
└── README.md          # This file

import type { IntegrationContext } from '../../types';

export interface ExampleMethodArgs {
  id: string;
}

export const exampleMethod = async (context: IntegrationContext, args: ExampleMethodArgs) => {
  // Make HTTP requests using the Axios client:
  // return await context.client.get(`/example-url?id=${args.id}`);
  
  // Or make POST requests:
  // return await context.client.post('/example-url', { data: args });
  
  return { data: 'Hello, Alokai Integrator!' };
};

+ import { config as myIntegrationConfig } from './integrations/my-integration';

export const config = {
  integrations: {
+   myIntegration: myIntegrationConfig,
  },
};

export * from '@/sdk/modules/checkout';
export * from '@/sdk/modules/commerce';
export * from '@/sdk/modules/custom-extension';
+ export * from '@/sdk/modules/my-integration';
export * from '@/sdk/modules/unified';
export * from '@/sdk/modules/unified-cms-mock';

import { getSdk } from '@/sdk';

export default async function MyComponent() {
  const sdk = await getSdk();
  
  // Call your integration methods
  const result = await sdk.myIntegration.exampleMethod({ id: '1' });
  
  return (
    <div>
      {/* Your component JSX */}
    </div>
  );
}

import { useSdk } from '@/sdk/alokai-context';

export default function MyClientComponent() {
  const sdk = useSdk();
  
  const handleClick = async () => {
    const result = await sdk.myIntegration.exampleMethod({ id: '1' });
    console.log(result);
  };

  return (
    <button onClick={handleClick}>
      Call Integration
    </button>
  );
}