Integrating your e-commerce backend with Builder.io makes working with your product content and data so much easier, and unlocks use cases like:
-
Symbols or Custom components that can accept a resource identifier, giving the content creator a way to search and choose a specific resource. One example could be a custom component that takes a product collection as an input and renders all its products in a grid.
-
Targeting content by a resource, for example, an announcement bar where its content only targets visitors who have a specific product in their cart, or are identified by a specific persona.
The most straightforward way to integrate your backend is using a @builder.io/commerce-plugin-tools, and here are some steps to build your own custom backend plugin:
- clone Builder repository and then navigate to the plugin example folder here:
git clone https://github.com/BuilderIO/builder.git
# start from a preconfigured plugin code by copying its content to another folder
cp -r plugins/swell plugins/[my-backend]
npm install @builder.io/commerce-plugin-tools
- Delete content of
src/plugin.tsx, so we replace it with the new backend operation, then start by
import { registerCommercePlugin } from '@builder.io/commerce-plugin-tools';
const pluginConfig = {
// id should match the name in package.json
id: `@foobar/plugin-builder`,
// will be used to prefix generated types
name: 'FooBar',
// a list of input definition that you might need to communicate with custom backend API ( optional )
settings: [
{
type: 'text',
name: 'storeApiKey',
helperText: 'you can get your store Api Key from your account at https://foobar.io/account',
}
],
ctaText: 'Connect your FooBar backend',
};
registerCommercePlugin(pluginConfig, (settings) => {
const storeApiKey = settings.get('storeApiKey');
const fooBarService = new FooBarService(storeApiKey);
// return a mapping between each resource and it's API functions.
return {
// for example to add product types
product: {
findById: id => fooBarService.findProductById(id),
search: text => fooBarService.searchProducts(text),
// should return BuilderRequest interface
// https://github.com/BuilderIO/builder/blob/master/plugins/shopify/src/interfaces/builder-request.ts
getRequestObject: id => ({
'@type': '@builder.io/core:Request',
request: {
// tell builder how to load this object
url: `https://foobarservice.com/products/${id}.json`,
},
options: {
product: id,
},
})
}
}
})
Now that we connected our API, we can check to see if it’s working correctly by running locally
npm install
npm run start
Start a server at http://localhost:1268
Go to the Builder plugin settings and add your local plugin https://localhost:1268/plugin.system.js?pluginId=@foobar/plugin-builder`
Now you should see new field types for products, such as:
- A single product picker with search
- A product list picker with search
- A custom field: product preview, that allows you to set the specific model editing url to be a computed value of the product in preview: for example
${space.siteUrl}/product/${previewProduct.handle}and allow the content editor to test their templates on multiple products.
Once you’re done testing your new integration, submit a pull request to Builder with the new code, we’ll help review it, and publish it to npm. Or, if you’d like it to be a private plugin, talk to us, and we can support private plugins as part of an enterprise plan.
See more:
Swell.is plugin source code for a more concrete example.
Extensibility docs for more ways on how Builder can be extended.