Transform Specification

[Experimental]

backpackjs transform spec (v2) [Experimental]

Transforms are functions that take product and collection data sourced earlier in the backpack build process and allow implementers to alter or augment that data before it's passed on to the storefront and used to create and render product and collection pages.

Implementers declare which transforms should run in the backpack.config.json file under the transforms key as an array of identifiers. Transforms are run in the order they are declared in the config. Declarations can take one of two forms:

• identifier: String

• [identifier: String, options: Object]

If included, options are passed to the transform function. An identifier can be one of the following:

• name of npm package exporting transform function

  • e.g. @backpackjs/transform-shopify

• path to file exporting transform function

  • e.g. ./transforms/shopify.js

The location the identifier points to must export a function that receives an object as an argument and returns an object containing the product and collection data modified by the transform function.

• module.exports = (input: Object) => { products: Object[], collections: Object[] }

The returned data should be an object with the transformed product data under the products key and the transformed collection data should be under the collections key. Additional keys returned will be ignored.

Note: It is valid to return the initially passed in product and collection data unchanged. Usually, this would be done in a situation where you need to run some kind of side-effect or produce an artifact using updated product and collection data (e.g. products-feed with augmented data), but don't update any data.

Product and collection data returned from a transform at a minimum must have:

• a unique handle property

  • only needs to be unique amongst type (i.e. product and collection), a collection and product can share the same handle

• a publishedAt property

  • must be date string in ISO 8601 format or null for unpublished product or collection

Arguments

The transform function is passed a single inputs object argument:

input: Object

• products: Object[]

  • product data returned from the pervious transform function, or in the case of the first transform, the product data sourced earlier in the build

• collections: Object[]

  • collection data returned from the pervious transform function, or in the case of the first transform, the collection data sourced earlier in the build

• options: Object

  • options provided by the implementer in backpack.config.json

• log: Object

  • object with error and message methods used for logging strings or array of strings

  • e.g.

    • log.error('this was a mistake');

    • log.message(['merged 43 products', 'merged 4 collections'])

• graphql: Object

  • object with tag and client keys

  • tag is an alias to the gql export from the @apollo/client package
  • client is a preconfigured apollo graphql client attached to the backpackjs graphql api