Key Concepts

The Widget Platform is built around a small set of interconnected ideas. Understanding how they relate helps you make better decisions as you build. This page explains each concept and why it works the way it does.

Widget

A self-contained component that appears on a community page. Widgets can display text, images, charts, forms, or any HTML content. They are placed onto pages using the No-Code Builder.

Widgets can be built-in (provided by the platform) or custom (created by your team from HTML/CSS/JS code stored in a Git repository). Custom widgets run inside Shadow DOM, which isolates their styles and markup from the rest of the page — so your widget's CSS never conflicts with the community theme, and the theme never overrides your styles.

No-Code Builder

The visual editor inside your community. Community managers use it to drag and drop widgets onto pages, rearrange them, and configure their settings — all without writing code.

When a custom widget is published, it automatically appears in the No-Code Builder's widget library, ready to be added to any page.

Connector

A secure, reusable configuration for calling an external API. Widget code runs in the browser, so making API calls directly would expose API keys and tokens to anyone using your community. Connectors solve this by routing requests through the platform's backend, where secrets are injected server-side — the browser never sees the credentials.

Each connector defines a destination URL, an HTTP method, authentication settings, and optional headers, query parameters, and payload templates. Once created, you call a connector from widget code using its unique permalink. The platform handles the rest: resolving secrets, applying authentication, forwarding the request, and returning the response.

Learn more about Connectors

Secret

A securely stored credential — such as an API key, token, or client secret — that connectors use for authentication. Secrets are managed through the platform UI and referenced in connector configurations using the get_secret() function in Jinja2 templates. They are never exposed to the browser.

Learn more about Secrets

SDK (Widget SDK)

A JavaScript library that widget code uses to interact with the platform. Its primary use is calling connectors from inside a widget.

In a widget HTML file, include the SDK <script> tag first, then use window.WidgetServiceSDK in a following script block:

<script src="https://static.customer-hub.northpass.com/widget-sdk/latest/index.umd.js"></script>
<script>
  const sdk = new window.WidgetServiceSDK();

  (async () => {
    const data = await sdk.connectors.execute({
      permalink: "weather-api",
      method: "GET",
      queryParams: { q: "London" }
    });
  })();
</script>

The SDK is also available as an npm package for bundled apps.

SDK Documentation

Extensions Registry

The extensions_registry.json file at the root of your code repository. It defines all the custom widgets in that repository — their names, types, settings, and content locations.

{
  "widgets": [
    {
      "type": "my_company_banner",
      "title": "Welcome Banner",
      "version": "1.0.0",
      "source": {
        "path": "widgets/banner",
        "entry": "index.html"
      }
    }
  ]
}

Registry Reference

Publishing Pipeline

The automated process that turns code in your repository into live widgets. When you push to a watched branch, the platform detects the change, fetches your files, validates them against security rules, and publishes them — typically in seconds. This push-to-publish model means there is no manual deploy step: your Git workflow is your deployment workflow. The trade-off is that anything pushed to the watched branch goes live immediately, which is why separate staging communities exist for pre-production testing.

Build & Publish

Content Security

Because custom widgets run real code inside your community, the platform checks every push for security issues before publishing. Scans detect patterns like crypto mining, data exfiltration, phishing, obfuscated code, and exposed credentials. Builds that contain flagged content are rejected — previously published content remains live until a clean push succeeds. This means a bad push never takes down existing widgets; it simply blocks the update.

Content Security

Permalink

A URL-friendly identifier automatically generated from a connector's name. For example, a connector named "Weather API" gets the permalink weather-api. You use this permalink when calling the connector from widget code.

Branch-Based Environments

A workflow where different Git branches serve different versions of your widgets to different communities. Each repository watches one branch at a time per community — switching the branch replaces all widgets from that repository. Use separate communities (dev, staging, production) to run multiple environments from the same repository without interfering with each other.

Production impact

Changing the watched branch takes effect immediately for all users of that community. Never switch the watched branch to test changes — use a separate staging community instead.

Preview and Promote

How It All Fits Together

A typical workflow touches most of these concepts: you define a widget in the Extensions Registry, push to a watched branch, the Publishing Pipeline validates and publishes it, and it appears in the No-Code Builder. If the widget needs external data, you create a Connector with Secrets for authentication and call it via the SDK. Branch-Based Environments let you preview safely before going live, and Content Security ensures nothing harmful reaches your community.

Next Steps

• Your First Widget — hands-on widget tutorial
• Your First Script — hands-on script tutorial
• Your First Stylesheet — hands-on stylesheet tutorial
• Build Your First Connector — hands-on tutorial for connectors
• Extensions — all guides and reference for widgets, scripts, and stylesheets
• Connectors — all guides and reference for external API integration