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.

Plugins are registered explicitly before startPlatform is called. Unchained offers presets that register commonly used plugin bundles:

• base (Catalog price based pricing, Post delivery & Invoice payment, GridFS asset storage, essential workers)
• crypto (Cryptopay payments, currency-rate updating workers for ECB & Coinbase, currency-converting pricing plugin, ERC721 token lazy-minting on Ethereum)
• countries/ch, countries/eu, countries/uk, countries/us (country-specific tax calculation)
• all (base + crypto + countries/ch + all other available plugins including plugins for various payment gateways)

We recommend loading at least base.

A minimal Fastify boot file (boot.ts):

import Fastify from "fastify";
import { startPlatform } from "@unchainedshop/platform";
import { connect, unchainedLogger } from "@unchainedshop/api/fastify";
import { registerAllPlugins } from "@unchainedshop/plugins/presets/all";

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

try {
  // Register the 'all' plugins preset before starting the platform
  registerAllPlugins();

  // Core modules are configured internally, no modules argument is needed for built-ins
  const platform = await startPlatform({});

  // Connect Unchained to Fastify, setting up the basic endpoints like /graphql
  await connect(fastify, platform, {
    allowRemoteToLocalhostSecureCookies: process.env.NODE_ENV !== "production",
  });

  // 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);
}

startPlatform resolves to { unchainedAPI, graphqlHandler, db }:

• unchainedAPI: The Unchained Core instance (modules, services, bulkImporter, bulkExporter, options)
• graphqlHandler: The GraphQL Yoga request handler
• db: The MongoDB database handle

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

• modules: Record<string, { configure: (params: ModuleInput<any>) => any }>: Custom modules configuration point. Load your own modules in addition to the built-in core 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.
• bulkExporter: Enables you to define custom bulk export handlers ({ handlers: Record<string, BulkExportHandler> }), the counterpart to bulkImporter.
• 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: 3600000, // milliseconds (1 hour)
    },
    // 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.