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 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/lib/fastify/index.js";
import defaultModules from "@unchainedshop/plugins/presets/all.js";
import connectDefaultPluginsToFastify from "@unchainedshop/plugins/presets/all-fastify.js";
import { fastifyRouter } from "@unchainedshop/admin-ui/fastify";

// 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 and a healthCheckEndpoint we can use for health checks in containerized environments
  const platform = await startPlatform({
    modules: defaultModules,
    healthCheckEndpoint: "/.well-known/yoga/server-health",
  });

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

  // Connect custom rest endpoints of all the plugins with Fastify, for example
  // /rest/payment/datatrans, a webhook endpoint for the Datatrans Payment Provider
  connectDefaultPluginsToFastify(fastify, platform);

  // Bind the official @unchainedshop/adminui to /, a simple statically built SPA that uses the GraphQL endpoint of Unchained Engine
  fastify.register(fastifyRouter, {
    prefix: "/",
  });

  // 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 }>: Custom modules configuration point. Allows you to extend the functionality of the engine.
  • services: Record<string, any>: Custom services configuration point. Allows you to extend the functionality of the engine.
  • typeDefs: Object (GraphQL Schema that gets merged with the default schema)
  • schema: Object (GraphQL Schema that gets merged with the default schema)
  • resolvers: Object (GraphQL Resolvers that get merged with the default API)
  • context: Special function to extend the underlying GraphQL context. Check the OIDC Example for how you could use it to add custom Auth.
  • options: Options for various submodules of Unchained. See the rest of the configuration section for details.
  • plugins: Optional
  • 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 here.
  • workQueueOptions: SetupWorkqueueOptions Configuration regarding the work queue, for example disabling it entirely in multi-pod setups
  • adminUiConfig: Customize the Unchained Admin UI

These options are extended by YogaServerOptions so you can pass a list of Yoga GraphQL Plugins or configure batching etc.

Next Steps​

...

Getting Help​