Using custom extensions in the Affinity Home Page Builder

Custom extensions let you build and register your own UI components when using the Affinity Home Page Builder.

This guide explains how to render your custom extension on your Affinity Home Page.

Before you start

• You must build and host your custom extension before registering it. The extension must be available at a publicly accessible HTTPS URL.
• This guide applies only to the Affinity Home Page Builder . See Customizing the Affinity customer portal if you use the original next order page version of Affinity.
• You must contact the Recharge Support team to request access to this feature.

Overview

Custom extensions are Web Components that you:

• Register in the Affinity Page Builder
• Add as sections to portal pages
• Render in the customer portal

Step 1 - Build a custom extension

Build your custom extension as a Web Component. You can use any framework or library (React, Vue, Svelte, or vanilla JavaScript), as long as the final output is a Web Component.

Requirements

• HTTPS only: The customer portal runs in a secure context. The browser blocks non-HTTPS resources.

• Default export: Export the Web Component class as the default export. Do not use named exports.

• Load time: Ensure the extension loads within 5 seconds. The portal removes extensions that exceed this limit.

• Valid tag name: Use a tag name that matches the custom element defined in your component.

Example

class MyWidget extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `<p>Hello from my custom extension!</p>`;
  }
}

export default MyWidget;

See custom extension example for a reference example.

Step 2 - Access the Affinity Home Page Builder

Access the page builder from your customer portal settings:

1. In the merchant portal, click Storefront, then select Customer portal.
2. Under Themes, click your theme’s Home page to expand the options.
3. From the expanded list, choose Recommended: Design your own custom home page under the Affinity customer portal theme.
4. Click Customize.

Step 3 - Register a custom extension

1. In your Recharge merchant portal, select Storefront and click Customer portal.

2. Depending on where you want the custom extension to render, select Header, Main column, or Right column and click Add a section.

3. Select the Custom extensions tab.

4. Click Create a custom extension.

   

5. Use the table below to complete the custom extension fields.

   Field	Required	Description
   File URL	Yes	Provide an HTTPS URL to the compiled JavaScript file (e.g., a CDN or Cloudflare R2 URL). You must build and host your extension before registering it here.
   Tag name	Yes	Define the Web Component tag (for example, my-widget). The tag must: Start with a lowercase letter Include a hyphen Use only lowercase letters, digits, hyphens, dots, or underscores
   Extension name	Yes	Enter an internal name for the portal (customers do not see this value)
   Extension description	No	Enter an internal description (customers do not see this value)
   Integrity Hash	No	Provide a cryptographic hash to verify file integrity. The browser rejects the file if the hash does not match
   Events	No	List events that trigger the component’s refresh() method

6. Click Save to save your extension.

Event behavior

When a configured event fires:

• The portal calls the component’s refresh() method
• The portal does not pass any data to refresh()
• The component fetches its own data

Step 4 - Add the extension to your page

After you register the extension, the Page Builder adds the extension as a section:

1. Click Add a section in the Page Builder.
2. Open the Custom extensions tab. You should now see your custom extension on this tab.
3. Select your extension to add it to the home page.
4. Click and drag the custom extension section to reposition it on the home page.

Step 5 - Test and publish

New extensions start in test mode:

• The portal shows them only in preview
• Customers cannot see them

Once you've verified the extension works as expected, make the extension visible:

1. Click on the custom extension section.
2. Enable Make this extension visible to customers.
3. Click Done to publish your changes.