defineExtension

info

Extensions are registered in the application using the front-commerce.config.ts file. Read Register an extension to learn more.

defineExtension

defineExtension allows you to define extensions settings

defineExtension(configuration);

Arguments:

Name	Type	Description
configuration	ExtensionConfig	The extension configuration

Example:

defineExtension({
  name: "acme",
  meta: import.meta,
  theme: "./extensions/acme/theme",
});

ExtensionConfig

ExtensionConfig is the definition interface of an extension.

name

Required string
Specifies the unique name of the extension.

Example:

{
  "name": "acme"
}

meta

Since version 3.4

Required string
Specifies the ImportMeta information of the extension.

Example:

{
  "meta": import.meta
}

important

The import.meta should be from the root of your extension. If you defined your extension under a sub-directory, then you should re-export it from the root instead.

📁 hello-v3/
│   ├── 📁 app/
│   ├── 📄 front-commerce.config.ts
│   ├── 📁 extensions/
│   │   ├── 📁 acme-extension/
│   │   │   ├── 📄 index.ts  # this is where the import.meta should be located
│   │   │   ├── 📁 extension-def/
│   │   │   │   └── 📄 index.ts
│   │   │   ├── 📁 graphql/
│   │   │   └── 📁 routes/
└──  package.json

configuration

Required object
Define configuration

providers

Required ConfigProvider[]
Define configuration provider

This allows you to register configuration providers for your application.

For example, you can register a CSP provider to allow additional domains:

extensions/acme-extension/config/cspProvider.ts

import { defineConfig } from "@front-commerce/core/config";

export default defineConfig({
  name: "AcmeCSP",
  values: {
    contentSecurityPolicy: {
      __dangerouslyDisable: false,
      directives: {
        defaultSrc: [],
        scriptSrc: ["https://acme.com"],
        frameSrc: ["https://acme.com"],
        styleSrc: ["https://acme.com"],
        imgSrc: ["https://acme.com"],
        fontSrc: ["https://acme.com"],
        connectSrc: ["https://acme.com"],
      },
    },
  },
});

extensions/acme-extension/index.ts

import { defineConfig } from "@front-commerce/core/config";
import acmeCSPProvider from "./config/cspProvider";

export default defineExtension({
  configuration: {
    providers: [acmeCSPProvider()],
  },
});

theme

Optional string|string[]
Specifies the path to the theme that should be loaded by the application.

Example:

{
  "theme": "./extensions/acme/theme"
}

graphql

Optionnal

Configuration for registering GraphQL modules in the unified GraphQL schema.

schema

Optional string|string[]
Defines path(s) to the GraphQL schema file(s) to be loaded in the application.

Example:

{
  "schema": [
    "./extensions/acme/graphql/foo/**/schema.gql", // accepts a globby pattern
    "./extensions/acme/graphql/bar/Feature.gql" // accepts a direct path
  ]
}

codegen

Optional

CodegenConfig["generates"][] | CodegenConfig["generates"]
configuration for code generation.

translations

Optional string
Specifies the path to the translations directory that should be compiled by the application.

Example:

{
  "translations": "./extensions/acme/translations"
}

unstable_lifecycleHooks

caution

This feature is unstable and may change in the future.

Optional

Specifies the lifecycle hooks that should be executed by the application. These hooks allow you to register custom logic at specific points of the application lifecycle.

Example:

{
  unstable_lifecycleHooks: {
    onServerInit: async (globalServices) => {
      // Do something when the server is initialized
    };
    onServerServicesInit: async (serverServices, request, config) => {
      // Do something when the request is initialized
    };
    onFeaturesInit: async (hooks) => {
      // Do something when the features are initialized
    };
  }
}

onServerInit

Since version 3.6

Called when the server is initialized with the following params:

• Global Services - Generally used to register new services

onServerServicesInit

Called on each request with the following params:

• Server Services - Generally used to register new services
• Request - The request object
• ResolvedConfig - The resolved configuration object

afterServerServicesInit

Called after the onServerServicesInit hook with the following params:

• Server Services - Generally used to register new services
• Request - The request object
• ResolvedConfig - The resolved configuration object

onFeaturesInit

Called when the features are initialized with the following params:

• FeatureHooks - The features hooks object

onShopFallback

Called when a request doesn't match any configured shop URL (shop fallback scenario). This hook allows extensions to customize the redirect behavior when no shop matches the current URL.

The hook receives a context object with the following properties:

• request - The incoming Request object
• config - The resolved shop configuration
• user - The user context
• services - The server services

The hook should return one of the following:

• { type: "shopId", shopId: string } - Redirect to a specific shop by its ID
• { type: "url", url: string } - Redirect to a custom URL
• { type: "skip" } - Do not redirect, continue with the request
• null or undefined - Use the default behavior (redirect to first configured shop)

Example:

{
  unstable_lifecycleHooks: {
    onShopFallback: async ({ request, config }) => {
      const acceptLanguage = request.headers.get("Accept-Language");
      if (acceptLanguage?.startsWith("fr")) {
        return { type: "shopId", shopId: "fr_fr" };
      }
      return null; // Use default behavior
    };
  }
}