Skip to main content

Platform Configuration

To customize an Unchained Engine project, follow these topics:

  1. Boot up: Wire Unchained with a web server and boot the app
  2. Configure the Core: Configure behavior of the core modules
  3. Plugin: Configure which plugins should load
  4. Extend

Boot Configuration​

The main entry point for an Unchained Engine project is startPlatform imported from @unchainedshop/platform. Calling it will initialize the Unchained Core, add default messaging templates, and set up the background worker.

To make things a bit more simple, Unchained offers different presets for loading functionalities out-of-the box:

  • base (Simple Catalog Price based Pricing strategies, Manual Delivery & Invoice Payment, GridFS Asset Storage)
  • crypto (Currency-Rate Updating Workers for ECB & Coinbase, Currency-Converting Pricing Plugin, Event ERC721 Token Lazy-Minting on Ethereum, Payment through Unchained Cryptopay)
  • countries/ch (Switzerland Tax Calculation and Migros PickMup Integration)
  • all (All of the above + all other available plugins including plugins for various payment gateways)

We recommend loading at least base.

To see it in context, it's best to see an example using Unchained with Fastify, which is being used as a template for unchainedshop/unchained-app-based projects (boot.ts):

import Fastify from "fastify";
import { startPlatform } from "@unchainedshop/platform";
import { connect, unchainedLogger } from "@unchainedshop/api/fastify";
import defaultModules from "@unchainedshop/plugins/presets/all.js";
import connectDefaultPluginsToFastify from "@unchainedshop/plugins/presets/all-fastify.js";

// Set up the Fastify web server in insecure mode and set the unchained default logger as request logger
const fastify = Fastify({
  loggerInstance: unchainedLogger("fastify"),
  disableRequestLogging: true,
  trustProxy: true,
});

try {
  // Init Unchained Platform with the 'all' plugins preset
  const platform = await startPlatform({
    modules: defaultModules,
  });

  // Use the connect from @unchainedshop/api to connect Unchained to Fastify, setting up the basic endpoints like /graphql
  connect(fastify, platform, {
    allowRemoteToLocalhostSecureCookies: process.env.NODE_ENV !== "production",
    initPluginMiddlewares: connectDefaultPluginsToFastify
  });
  
  // Tell Fastify to start listening on a port, thus accepting connections
  await fastify.listen({
    host: "::",
    port: process.env.PORT ? parseInt(process.env.PORT) : 3000,
  });
} catch (err) {
  fastify.log.error(err);
  process.exit(1);
}

To configure various aspects of the platform, startPlatform accepts a configuration object with various parameters:

  • modules: Record<string, { configure: (params: ModuleInput<any>) => any }>: Modules configuration point. Load your own modules, a preset or a combination of a preset and your own modules.
  • services: Record<string, any>: Custom services configuration point. Allows you to extend the functionality of the engine with cross-module business-process functions.
  • typeDefs: Object (GraphQL Schema that gets merged with the default schema)
  • resolvers: Object (GraphQL Resolvers that get merged with the default API)
  • schema: Object (GraphQL Executable Schema that gets merged with the default schema, do not use it together with typeDefs & resolvers specified!)
  • context: Special function to extend the underlying GraphQL context. Check the OIDC Example for how you could use it to add custom Auth functionality.
  • options: Module-specific configuration options (see Module Options below)
  • rolesOptions: IRoleOptionConfig: Enables you to customize the existing roles and actions, adjusting fine-grained permissions.
  • bulkImporter: Enables you to define custom bulk import handlers for a clear separation of data import and e-commerce engine. For more information about the bulk import API, refer to the Bulk Import Guide.
  • workQueueOptions: SetupWorkqueueOptions Configuration regarding the work queue, for example disabling it entirely in multi-pod setups
  • adminUiConfig: Customize the Unchained Admin UI, for example configuring a Single-Sign-On Link for external Auth support via oAuth.

Module Options​

The options parameter accepts module-specific configuration:

await startPlatform({
  options: {
    // Assortments module
    assortments: {
      slugify: (title) => customSlugify(title),
    },
    // Products module
    products: {
      slugify: (title) => customSlugify(title),
    },
    // Delivery module
    delivery: {
      filterSupportedProviders: async ({ providers, order }, unchainedAPI) => providers,
      determineDefaultProvider: async ({ providers, order }, unchainedAPI) => providers[0],
    },
    // Payment module
    payment: {
      filterSupportedProviders: async ({ providers, order }, unchainedAPI) => providers,
      determineDefaultProvider: async ({ providers, order }, unchainedAPI) => providers[0],
    },
    // Orders module
    orders: {
      ensureUserHasCart: true,
      orderNumberHashFn: (order, index) => `ORD-${index}`,
      lockOrderDuringCheckout: true,
    },
    // Users module
    users: {
      mergeUserCartsOnLogin: true,
      autoMessagingAfterUserCreation: true,
      validatePassword: async (password) => password.length >= 8,
      validateEmail: async (email) => email.includes('@'),
    },
    // Enrollments module
    enrollments: {
      enrollmentNumberHashFn: (enrollment, index) => `ENR-${index}`,
    },
    // Quotations module
    quotations: {
      quotationNumberHashFn: (quotation, index) => `QUO-${index}`,
    },
    // Files module
    files: {
      transformUrl: (url, params) => url,
      privateFileSharingMaxAge: 3600,
    },
    // Worker module
    worker: {
      blacklistedVariables: ['SECRET_KEY'],
    },
  },
});

For detailed documentation of each module's options, see the respective module documentation under Modules.

These options are extended by YogaServerOptions so you can pass all options you can normally pass to createYoga, add plugins Yoga GraphQL Plugins or configure batching and other more advanced GraphQL features. Check the Yoga documentation for more information.

Getting Help​