@backpackjs/build

Transform Specification [Experimental]

backpackjs transform spec (v2)

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. In addition, blog, article, and page content data is accessable as read-only data.

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) => {
  return void || { products: Object[], collections: Object[] }
}

If you would like to persist your changes to product and collection data between transforms, the updated data should be returned in an object with the array fo transformed product data under the products key and the array of transformed collection data under the collections key. Returning data is optional, keys returned outside of products and collections will be ignored

Note: It is also permitted to return nothing, in which case the product and collection data that was passed into the transforme with be implicitly returned. 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.

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
• blogs: Object[]
  • blogs data sourced during the fetchBlogs task. This data is read-only and cannot be updated.
• articles: Object[]
  • articles data sourced during the fetchArticles task. This data is read-only and cannot be updated.
• pages: Object[]
  • pages data sourced during the fetchPages task. This data is read-only and cannot be updated.
• context: Object
  • Listr2 build context object
• options: Object
  • option values provided by the implementer in backpack.config.json
• log: Object
  • object with info, error and message methods used for logging
  • e.g.
    • log.info('this is a normal log');
    • log.error('this appears under the "Errors" heading');
    • log.message('this appears under the "Warning" heading')
• clients: Object
  • object with preconfigured graphql clients for accessing the Shopify, DatoCMS, and BackpackJS graphql apis used during the build