DEV Community: Gadget

In Gadget framework v1.7.0, Shopify TOML becomes the source of truth for your app

Gadget — Sun, 05 Apr 2026 18:54:41 +0000

With Gadget framework v1.7.0, the Shopify TOML file becomes your source of truth for any Shopify app configuration.

If you are building a Shopify app with Gadget, upgrading to Gadget framework v1.7.0 moves your app onto a TOML-first configuration model. After the migration runs, Shopify’s TOML file becomes the source of truth for your app configuration.

That might sound like a small change, but it has real consequences. Gadget apps already had Shopify TOML files before v1.7.0, but those files did not fully describe how the app was configured. Parts of the connection still flowed through Gadget’s legacy install path, especially around webhook registration.

With v1.7.0, your Shopify app configuration now aligns with Shopify’s own app platform model: the TOML is canonical, Gadget writes to it, and the Shopify CLI deploys it.

The TOML was already there, but it wasn’t the whole story

Before v1.7.0, a Gadget Shopify app could already have a TOML file that looked something like this:

client_id = "094c8f4584ca2d23a54c9565f648be88"
name = "my-product-quiz"
application_url = "https://my-product-quiz--development.gadget.app/api/shopify/install-or-render"
embedded = true

[auth]
redirect_urls = [ "https://my-product-quiz--development.gadget.app/api/connections/auth/shopify/callback" ]

[webhooks]
api_version = "2026-01"

[[webhooks.subscriptions]]
compliance_topics = [ "customers/data_request", "customers/redact", "shop/redact" ]
uri = "https://my-product-quiz--development.gadget.app/api/webhooks/shopify"

That file was a real Shopify TOML. But it was not yet the full contract for the app.

You can see that in a few places:

GraphQL API scopes are not managed in the TOML.
Webhook configuration was minimal, with compliance topics pointing to a Gadget-managed endpoint. Model and global action webhook subscriptions were still handled outside the TOML model.

The TOML existed, but it was not the file you would look at to fully understand how a Gadget Shopify app was wired up.

What changes in v1.7.0

Once your app is upgraded to framework v1.7.0 and the migration runs, the TOML becomes the canonical definition of the connection.

Scopes now live in TOML:

[access_scopes]
scopes = "read_products,write_products,read_orders"

Webhook subscriptions for enabled models now live there too:

[webhooks]
api_version = "2024-10"

[[webhooks.subscriptions]]
topics = ["products/create", "products/update", "products/delete"]
uri = "https://webhooks.gadget-services.net/shopify/v1?domain=my-product-quiz--development.gadget.app"

When you want a global action to respond to a Shopify webhook, the action code links to a TOML-managed subscription through a triggerKey:

export const options = {
  triggers: {
    shopify: {
      triggerKey: "productUpdates",
    },
    api: false,
  },
};

With the corresponding TOML entry:

[[webhooks.subscriptions]]
topics = ["products/update"]
uri = """
https://webhooks.gadget-services.net/shopify/v1/\
productUpdates?domain=\
my-product-quiz--development.gadget.app\
"""

Filtering and payload shaping move into TOML too:

[[webhooks.subscriptions]]
topics = ["products/update"]
filter = "vendor:Nike"
include_fields = ["id", "title", "vendor", "updated_at"]
uri = """
https://webhooks.gadget-services.net/shopify/v1/\
shopifyProduct-update?domain=\
my-product-quiz--development.gadget.app\
"""

That is the core shift in v1.7.0: configuration that used to be partly implicit or managed through Gadget’s legacy path is now expressed directly in Shopify’s app manifest.

One exception: metafield webhooks are not managed in your TOML. This is because they are set as part of the webhookSubscriptionsCreate GraphQL request that Gadget does for you to enable webhooks.

You can still use Gadget’s connection flow

This does not mean every change has to become a manual TOML edit.

You can still use Gadget’s connection flow in the editor. The difference is that those changes now write through to the TOML instead of being registered via API.

So if you prefer to work in the editor, you still can. If you want to edit the TOML directly, you can do that too. Either way, there is now one canonical config file.

Why this is a better model

For teams shipping Shopify apps, this mostly comes down to clarity.

Gadget and Shopify are working from the same definition. Changes made in the editor and changes made in code converge in one place. And when Shopify exposes something through TOML, Gadget apps can take advantage of it without needing a parallel Gadget-specific surface first.

That is a better fit for the way modern Shopify apps are built: explicit, CLI-friendly, and easy to reason about in source control.

Migration is automatic

If you already have a Shopify app on Gadget, you don’t need to migrate your TOML files manually.

The migration happens automatically when you upgrade your app to Gadget framework v1.7.0.

The one thing you should do before upgrading is make sure your app is in source control. Commit your current state so you have a clean diff of the TOML and related changes that come with the migration. After that, upgrade and let the migration run. No other steps should be required.

There is one important operational detail: development stores will need to manually re-register webhooks after the upgrade. This isn’t needed in production; production stores are automatically re-registered when you deploy v1.7.0 to prod.

Learn more

For more details on the upgrade, environment-specific TOML behavior, and the underlying connection model, see the docs.

If you run into migration issues, get in touch with us on Discord.

We set out to save money on observability. Instead, we (accidentally) rebuilt our incident response workflow.

Gadget — Tue, 24 Mar 2026 16:24:18 +0000

The Gadget infrastructure team shares how using agents to migrate our observability stack to Grafana and ClickHouse ended up transforming how we handle production debugging and incident response.

This post was supposed to be about how we migrated Gadget’s observability stack from Axiom to ClickHouse and Grafana, and saved a bunch of money. We did that, but the big story is actually how the collection of agent skills we built to help us with this migration ended up fundamentally transforming how we approach incident response and production debugging at Gadget.

So we will still talk a bit about the migration, what the process looked like and some of the tools we used, but what we really want to share is how agents have become our primary mechanism for incident response.

Over the course of a couple of weeks, we went from manually searching through logs and traces and dashboards, to delegating these investigatory tasks to Claude. And it’s all thanks to the agent skills and MCP server we built to help us with our migration.

I use the dashboards way less and do zero log searching myself; it's all Claude. We learned how to use ClickHouse well, wrote the skill, and then stopped thinking about it.
‍
In a way, learning how to use ClickHouse for infra/observability/operations wasn't useful because it enables data visualization with dashboards. It was useful because it let us set guardrails for our MCP server and ClickHouse skill.

-Kirin Rastogi, Infrastructure Engineer @ Gadget

(And to be clear, we did save money. The entire migration took about a week and was finished 1.5 weeks ahead of schedule. Our monthly observability bill dropped from ~$20k to ~$8k.)

Observe our observability

Gadget is a platform for full-stack web apps, providing developers with hosted development and production environments and APIs to “summon” infrastructure as needed. Our infrastructure and platform powers thousands of ecommerce and web apps, which means we, Gadget’s infra team, need our observability dial turned up all the way to 11.

We are heavily biased towards log-based alerting, which means we need to search and aggregate log entries and trace spans for our dashboards. We use Prometheus-style metrics for our infrastructure in GCP, but we are log-centric when it comes to application monitoring, which might be a bit different from metrics-based observability commonly used by other infra teams.

(We are not log-based because we are a team of beavers based in Ottawa, Canada, a common misconception. This setup is largely an artifact of early decisions and technical debt. Log-based observability is dead simple to set up, and we’ve built alerts based on detecting “needle in the haystack” events across our platform. When Kirin joined the Gadget team, he had one question: “How do you live like this?”

(We’re working on it.)

Traces are handled by our OTel collector. k8s pod logs flow through Vector and make use of custom VRL (Vector Remap Language) scripts that transform our raw container output into OTel-formatted ClickHouse rows.

Once more, with agents

Our observability stack now includes agent skills and rule files. These skills were initially built to assist with the migration from Axoim to Clickhouse and Grafana, and now they power incident response. Claude loads the ClickHouse skill, queries logs and traces via MCP, and runs through an RCA playbook. All the same tooling that was built to migrate dashboards is now the first thing engineers reach for when something breaks.

Instead of manually digging through dashboards, agents are our first entry point to incident investigation. Dashboards are primarily used for secondary validation and to power our alerts.

We didn’t set out to do this, but our agent skills have massively reduced incident response times. RCA investigations have gone from taking days to hours, and from weeks to days for more complex issues. Plus any member of the team can investigate any issue and actually come up with useful and actionable ideas and results; there is way less “Who built this?” and way more “Here’s how we can fix this.” Now Andy can dig into skipper controller assignments even though skipper is Scott’s baby.

(skipper is Gadget’s Kubernetes-based sandbox orchestrator: it assigns tenant-specific app workloads to sandbox pods, routes requests to the right instance, and scales pods up or down as demand changes. In our infra stack, it sits between the platform API and the user’s sandbox runtime, giving us per-tenant isolation with efficient pod reuse.)

We’ll talk more about how and why we built these skills later. Let’s quickly chat about the migration from Axoim.

It’s not you, it’s me

We had a flippin’ great deal on Axoim for the past 3 years. We liked using it: APL, their query language, made exploration easy compared to raw SQL, and the Axoim team worked with us to optimize our queries over large time windows.

But our monthly bill was about to increase from ~$20K to $25-30K a month. We also needed to build an observability dashboard for our users which would further increase our costs if we stuck with Axoim.

So we decided to migrate to ClickHouse, which could also power our in-platform observability dashboard for users, and Grafana.

Why Grafana and ClickHouse?

Because everyone uses Grafana, and everyone can’t be wrong. (But actually. Also, it does make it easier for new Gadget employees to onboard.)

We already use Grafana to monitor Kubernetes test failures in CI, and we use it via pgwatch for PostgreSQL monitoring. Most of the Gadget team is ex-Shopify or ex-Stripe, and both companies use Grafana. It is our cozy, familiar observability blanket. Our “observabili-blanket”. We know how to use it, agents know how to configure it, and there is plenty of material available to figure out what we don’t already know.

There is a small penalty for choosing Grafana: its customizability comes at the expense of setting it up yourself. Thankfully, Claude was a massive help there. More on that later.

We had no prior experience with ClickHouse, but we knew that column storage made it well-suited for logs and traces, plus ClickHouse is extremely compressable so we could optimize our storage costs.

We ultimately chose ClickHouse’s hosted solution: clickhouse.cloud. They manage the infrastructure; we control the schema. This PaaS approach gave us the operational benefits we needed without managing storage clusters ourselves. We’re a small team and don’t need even more infra to manage at this time.

And because we use ClickHouse, we didn’t need to fight with PromQL, an added bonus.

Fixing the OTel collector

Step one of the actual migration was transforming our OTel (Open Telemetry) data. We were, perhaps, a bit messy when initially defining attributes for our data sources. In Axoim, we could use a single virtual field to check all 4 variants of environment_id. That wouldn’t fly in ClickHouse’s typed JSON columns. We needed one canonical path per concept. (Claude initially struggled to migrate the queries because the data was a mess.)

So we tackled two big pieces of work: we migrated our attributes to follow OTel semantic conventions and normalized our attributes so we have a single source of truth for a given value.

OTel convention migration

We started by remapping our legacy OTel attribute names to current semantic conventions across 13 different categories such as network, HTTP, database, deployment, and exception.

It looked a little something like this:

Standardized naming made it easier for agents and humans to understand our data streams during incidents.

Normalizing the attributes

Axoim allowed us to gracefully handle duplicate attributes. (Or maybe just ignore the duplicate attributes, gracefully.) It would be more difficult to filter and group at runtime on ClickHouse, so we normalized our attributes:

environment_id, environmentId, billing.str.environment_id, function.tenant were all consolidated into gadget.environment_id
application_id, applicationId, billing.str.application_id were all consolidated into gadget.application_id

We also split attributes into smaller segments using the OTTL (Open Telemetry Transformation Language) UserAgent function:

Example, url.full decomposed into url.domain, url.path, url.query, url.scheme, url.port, url.fragment

Claude wrote all of the transform logic, and we thoroughly reviewed and tested all changes.

# explode the user agent attribute
- context: span
  conditions:
    - attributes["user_agent.original"] != nil
  statements:
    - merge_maps(
        cache,
        UserAgent(attributes["user_agent.original"]),
        "upsert"
      )
    - set(
        attributes["user_agent.name"],
        cache["user_agent.name"]
      ) where
        attributes["user_agent.name"] == nil and
        cache["user_agent.name"] != nil
    - set(
        attributes["user_agent.version"],
        cache["user_agent.version"]
      ) where
        attributes["user_agent.version"] == nil and
        cache["user_agent.version"] != nil
    - set(
        attributes["user_agent.os.name"],
        cache["user_agent.os.name"]
      ) where
        attributes["user_agent.os.name"] == nil and
        cache["user_agent.os.name"] != nil
    - set(
        attributes["user_agent.os.version"],
        cache["user_agent.os.version"]
      ) where
        attributes["user_agent.os.version"] == nil and
        cache["user_agent.os.version"] != nil

That covered the work to clean up our tracing data, but we still had a couple more hurdles before we tackled the dashboards.

Another semi-related hurdle: forking Grafana’s ClickHouse plugin

But first, a final small detour.

ClickHouse provides these schemas for OTel tables. We decided to use JSON types for LogAttributes, SpanAttributes, and ResourceAttributes instead of the suggested Map(String, String) type, because of the feature-richness of the JSON type, including the ability to type-hint paths upfront and read JSON subpaths as separate columns.

But because the suggested format is Map(String, String), Grafana’s ClickHouse plugin expects that format. So Yandu forked the Grafana plugin and updated it to support our JSON columns.

But what about the log data?

These same transformations had to be done on log data as well. We use a VRL script to do things like normalize log severity to consistent SeverityNumber and SeverityText pairs from a collection of integer codes, strings, and, as we like to so elegantly put it, “unknown” formats.

We also extract and parse service names, removing k8s suffixes, and do the same attribute normalization performed on the OTel collector. Deduplication was also required and we dropped 11 specific log messages also found in traces so the pipelines output totally unique data.

With the data attributes standardized and normalized (and more readable), we were ready to start building our dashboards in Grafana. The data transformation enabled us to use Claude to hammer through the next stages of the migration: migrating queries from Axiom’s APL to SQL, and building our dashboards.

Kirin: master of agent skills and rebuilding dashboards

The migrations could finally begin!

We didn’t just throw Claude at the problem right away. Scott manually ported the first dashboards: a subset of our operator central board and an inspector dashboard for individual k8s pods. Manually doing a first pass was useful. We learned how we want to structure our Grafana queries and the best query patterns for our use cases. (Kirin was able to port over our alert rules with the help of Claude and careful manual reviews and testing, while Scott worked on the first dashboard.)

And now that we had an initial pattern, we could unleash Claude. These Grafana dashboard definitions were pulled down and committed to source control. We created agent skills and rules that then referenced the examples.

Kirin set out to build an agent skill to help with the migrations. The original goal was to build a skill that speeds up migrations by running through the following high-level steps:

Read existing Axoim dashboards
Translate APL queries to SQL
Execute queries against ClickHouse to verify correctness
Update YAML files locally
Push to Grafana and compare results

He used Claude and our manually built example (along with intimate knowledge about the shape of our data and pipeline) to build a collection of reference docs to assist us in the migration. This skill transformed into the foundation of our incident response procedure.

It also supercharged our dashboard migrations. Migration time dropped from 4 hours to 20 minutes per dashboard.

The biggest change to my workflow has been thinking of complex prompts that handle the whole task with all information up front. Including details like what to do, how to test it, and guidance on how to do it (although usually it is better than me at this part). That way, I can work on something else after. Going back and forth with an agent because you missed details earlier means that you are wasting time, and possibly bloating the context. If you can describe what to do succinctly, it will act more efficiently and correctly.

-Kirin Rastogi, Infrastructure Engineer @ Gadget

Claude yeets (carefully migrates) queries from APL to SQL

Translating APL to SQL would have been a horrible manual experience.

Once again, we were making use of Axoim’s virtual fields and stored query fragments to smooth over our disorganized data attributes, and now we need to translate those queries to read from ClickHouse.

(During the migration process, we ran the two observability stacks in parallel, then did a simple in-code switchover once we were confident that ClickHouse and Grafana were working properly.)

There were a couple of non-obvious translations that needed to happen, including migrating from APL’s extend and chained summarize map to nested SQL expressions. Here’s an example of this translation on one of our APL queries:

['core-tracing']
| where
    name == 'RunActivity:createAttemptAndRunBackgroundActionWithVisibility'
| extend
    scheduled_start = todatetime(
      ['attributes.custom']['background-action.next-attempt-starts-after']
    )
| extend
    actual_start = todatetime(
      ['attributes.custom']['background-action.start-date']
    )
| where
    datetime_diff("second", actual_start, scheduled_start) >= 0
| summarize
    value = percentile(
      datetime_diff("second", actual_start, scheduled_start),
      50
    ) by bin_auto(_time), environment_id
| summarize
    max(percentile(value, 90)) by bin_auto(_time)

Translated to SQL:

WITH
  extended AS (
    SELECT
      Timestamp,
      parseDateTimeBestEffort(
        SpanAttributes['background-action.next-attempt-starts-after']
      ) AS scheduled_start,
      parseDateTimeBestEffort(
        SpanAttributes['background-action.start-date']
      ) AS actual_start,
      toString(SpanAttributes['gadget.environment_id']) AS environment_id
    FROM otel.otel_traces_v2
    WHERE $__timeFilter(Timestamp)
      AND SpanName = 'RunActivity:createAttemptAndRunBackgroundActionWithVisibility'
  ),
  per_env AS (
    SELECT
      $__timeInterval(Timestamp) AS time,
      environment_id,
      quantile(0.5)(
        dateDiff('second', scheduled_start, actual_start)
      ) AS value
    FROM extended
    WHERE dateDiff('second', scheduled_start, actual_start) >= 0
    GROUP BY time, environment_id
  )
SELECT
  time,
  quantile(0.9)(value) AS value
FROM per_env
GROUP BY time
ORDER BY time

A game of spot-the-differences is pretty much just one big circle.

This is where agents were helpful. We could capture these transformation patterns repeated throughout our APL queries and use Claude to correctly and uniformly translate them to SQL queries.

Scott's pro tip: Grafana silently treats non-string GROUP BY columns as metric values instead of labels, which breaks visualizations. You'll stare at a graph wondering why all your series collapsed into one line, and the fix is wrapping the column in toString().

-Scott Côté, Infrastructure Engineer @ Gadget

You can take a look at our since-removed-from-the-codebase-because-the-migration-is-complete skill in this gist. It contains common operator migrations from APL to SQL, and was incredibly useful for us (and for Claude).

Where we are now: AI-powered incident response

Claude handled the migration so well, so we leaned in. We invested time in building skills and testing existing MCP servers so agents can help us with production debugging and incident response.

In its current form, our /clickhouse skill now has:

28 best-practice rule files documenting topics like: primary key design, data types, partitioning, JSON usage, JOIN patterns, skipping indices, materialized views (incremental + refreshable), batch sizing, async inserts, mutation avoidance, and OPTIMIZE/FINAL avoidance.
Namespace-specific schemas for our various services: gadget, sandbox, skipper, dateilager, and ingress-nginx, each with their own attribute reference and query examples. Each namespace schema documents which SpanName values exist, what LogAttributes/SpanAttributes paths are populated, and ready-to-run example queries.
System diagnostics for OOM, cascade failures, and connection pileups. What are our current memory and query counts? Who in the system is traditionally a memory hog? All this, and much more, answerable by an agent.
A core schema reference, documenting otel_logs_v1 and otel_traces_v2 column layouts and other key operational knowledge around query shape (toDateTime(Timestamp) is the PRIMARY KEY, putting it anywhere except first is 18-24x slower) and other restrictions (there is a 30-minute window limit on traces. It’s a big table, and wider windows reliably timeout).
Instructions for running ClickHouse queries using our gadget-admin MCP server. The MCP server uses a read-only ClickHouse user granted a small quota of resources so that MCP requests don’t saturate the ClickHouse cluster.

And then there’s the 8-phase RCA investigation playbook. The playbook automates root-cause analysis for environment crashes and has become the entry point for incident response for unknown issues in production. It works through the following steps:

Error timeline: Dig into the shape of the incident: when did errors start/peak/resolve?
Traffic pattern: What's generating load: webhook flood, BGA backlog, or organic traffic?
Rate limit analysis: Which rate limits were hit, which consumer classes?
Database budget: Budget consumption at 10-second resolution, by model and operation type.
Concurrency controller: PID controller behavior: crashing, oscillating, or stuck at 1?
Traffic composition: Deep-dive into what's generating traffic, webhook amplification ratios, and pre/post-crash comparison.
Error deep-dive: Timeout counts with span-layer deduplication (each timeout propagates through ~4 span layers, so divide by ~4 for unique count).
Recovery Verification: Confirm intervention worked, non-background action traffic continuity, recon rate normalization, and background action traffic resumption.

An agent can use the skill to automate deep dives into incidents, saving us from manually traversing dashboards and walking through the same steps.

Here are some real-life examples of prompts we used to debug and resolve issues:

/clickhouse why did the number of assignments by skipper controllers get so skewed such that 1 controller is assigning more functions than others -- this looks to have started around Mar 5, 2026, 9:00:00 PM EST
/clickhouse why is this temporal workflow failing? Destructively-delete-app-313876
/clickhouse figure out why these errors have gone off in the past hour: Remote procedure call failed: Timeout opening websocket connection to Gadget API
/clickhouse go over all our ClickHouse tables in production and figure out which ones haven't received reads and/or writes in the past 7 days so we can clean them up.

We use the skill for debugging, incident response, to clean up unused infra... it’s a core piece of our daily workflow that just didn’t exist a couple of months ago.

Want to talk observability and incident response, or have questions about how we use agents? Gadget’s ops team is always hanging out in our developer Discord!

Thanks to Scott, Kirin, Yandu Oppacher, and the rest of the infrastructure team for contributing!

Building HubSpot app Home and Settings pages

Gadget — Fri, 13 Mar 2026 18:58:57 +0000

This post guides you through creating a comprehensive App Home and Settings experience for a HubSpot integration using Gadget. Building on the previous custom object template, it unveils HubSpot's new App Home Page, offering a centralized view of your custom object.

Building the HubSpot App Home and Settings Page on Gadget

HubSpot's much-awaited and overdue feature: The App Home Page! (And also, a Settings page).

When creating ad hoc HubSpot apps for internal use, one thing never felt right to me was the lack of a centralized overview page for the integration. Having only an app card to view data feels restrictive. If you wanted to shoehorn in a method to have an overview of all data handled by the app with just the app card, you would need to create a clunky solution or compromise the clarity of the app card.

That's why, for this app template, we built up from the previous HubSpot Private app template as it's a great use case for having an app homepage to display all of the teams in an organization, grouped by company.

Where we left off

In the last post, we built a HubSpot app card on Gadget that lets users group contacts from a company into named teams that were then stored as a custom object (customObjectTeam) in Gadget. The app card is scoped to a single company record: you pick contacts, name the team, and save.

That works well for creation. But it leaves an obvious gap: there's nowhere to get a bird's-eye view of every team across the entire portal, no easy way to clean up stale data, and no easy way to organize any WebUI modification tools inside HubSpot. That's what this post is about.

The App Home Page

HubSpot's App Home Page (currently in public beta, sign up at https://app.hubspot.com/l/product-updates/new-to-you?rollout=237984) gives your app a proper landing page, which you can quickly access from the Marketplace icon under Your recently visited apps, or directly at https://app.hubspot.com/app/{HubID}/{appId}.

The app Home Page is built identically to a card extension, a React component using hubspot/ui-extensions, registered with hubspot.extend<"home"> and configured via an *-hsmeta.json file with "location": "home". HubSpot recommends using certain hubspot ui-extension components and props to fit the UI expectations of a Home page, same idea with the Settings page.

What it shows

The homepage gives a full organizational view: every company, every team under it, and every contact in each team, all in one scrollable page.

Company logos are pulled from HubSpot and displayed inline. Every company name and contact name is a deep link directly to their HubSpot record so this page doubles as a quick-navigation tool.

The data architecture

The key design choice here is that Gadget only stores IDs. The customObjectTeam model holds teamName, portalId, a parentCompany number, and teamContacts (a JSON array of HubSpot contact IDs). No personal identifiers, no logo image files.

When the homepage loads, the GET /hubspot/all-teams route:

Queries Gadget for all customObjectTeam records belonging to the portal.
Collects all unique parentCompany IDs and fires a single batch request to the HubSpot CRM companies API for names and logos.
Collects all unique contact IDs across every team and fires a single batch request to the HubSpot CRM contacts API for names, titles, and emails.
Assembles and returns a response grouped by company, with ID arrays replaced by fully hydrated objects.

// Fetch all teams for this portal
    const teams = await api.customObjectTeam.findMany({
      filter: { portalId: { equals: portalIdNumber } },
      select: {
        id: true,
        teamName: true,
        teamContacts: true,
        parentCompany: true,
        portalId: true,
      },
    });

    // Get unique company IDs
    const uniqueCompanyIds = [
      ...new Set(
        teams
          .map((t) => t.parentCompany)
          .filter((id): id is number => id != null)
          .map(String)
      ),
    ];

    // Batch-fetch company names and logos from HubSpot
    const companyNames: Record<string, string> = {};
    const companyLogos: Record<string, string> = {};
    if (uniqueCompanyIds.length > 0) {
      try {
        const batchResponse = await hubspotClient.crm.companies.batchApi.read({
          inputs: uniqueCompanyIds.map((id) => ({ id })),
          properties: ["name", "hs_logo_url"],
          propertiesWithHistory: [],
        });
        for (const company of batchResponse.results) {
          companyNames[company.id] =
            company.properties.name || `Company ${company.id}`;
          if (company.properties.hs_logo_url) {
            companyLogos[company.id] = company.properties.hs_logo_url;
          }
        }
      } catch (err) {
        logger.warn({ err }, "Failed to fetch company names from HubSpot; using IDs as fallback");
      }
    }

    // Collect all unique contact IDs across all teams
    const uniqueContactIds = [
      ...new Set(
        teams.flatMap((t) =>
          Array.isArray(t.teamContacts)
            ? (t.teamContacts as (string | number)[]).map(String)
            : []
        )
      ),
    ];

Two API calls to HubSpot, regardless of how many companies or teams exist. This same route is reused by both the Homepage and the Settings page.

Auth

Like the App card, the Homepage authenticates by first calling POST /hubspot/auth to get a short-lived JWT, then passing it as a Bearer token on subsequent requests. The token is validated server-side by requireHubspotJwt, which checks the signature, confirms the session isn't expired, and extracts the portalId to scope all database queries.

The Settings Page

The settings page lives at Marketplace → My Apps → [your app] → Settings and is configured with "type": "settings" in its *-hsmeta.json. It shares the same React + hubspot/ui-extensions toolkit as the homepage and card, with one important constraint: no hubspot/ui-extensions/crm components, since settings isn't tied to any CRM object.

Where the homepage is read-only, the settings page is where you manage your teams. It loads the same GET /hubspot/all-teams data, but adds two actions per team:

Removing contacts

Clicking Manage Contacts on a team opens a modal panel. Inside is a checkbox list of every contact on that team. Selecting contacts and hitting Remove

Selected calls POST /hubspot/remove-contacts, which:

Verifies the team belongs to the current portal (no cross-portal writes).
Filters the teamContacts array to exclude the selected IDs.
Saves the updated array back to the Gadget record.

The UI updates immediately in state, no reload needed.

Deleting teams

Delete Team uses a two-step confirm pattern: the first click swaps the button for Confirm Delete and Cancel, requiring a second deliberate action before anything is actually deleted. This calls POST /hubspot/delete-team, which performs the same portal ownership check before calling api.customObjectTeam.delete.

Deleted teams disappear from the list immediately. Companies with no remaining teams are removed too.

What this unlocks

Adding the homepage and settings page to the custom objects template completes a proper app loop:

Create teams from the company app card
View all teams org-wide on the app homepage
Manage (remove contacts, delete teams) from the settings page

The separation of concerns is clean: the card is scoped to one company record, the homepage is a read-only portal-wide view, and the settings page is where administrative actions live. None of them needed new models, just new routes and UI extensions on top of the same customObjectTeam model and GET-all-teams endpoint.

The full template is available here!

We ran vinext (Next.js on Vite) inside a Gadget app

Gadget — Mon, 09 Mar 2026 21:07:00 +0000

Use vinext in Gadget to get a drop-in replacement for your Next apps on Gadget's infrastructure.

Cloudflare dropped something pretty fun the other week: they rebuilt a drop-in replacement for Next.js on top of Vite. It took them about a week and only cost $1100 in tokens.

The project is called vinext. It keeps the Next.js API but swaps the underlying toolchain for Vite, which means dramatically faster builds and smaller client bundles. The announcement blog post is worth a read if you care about those numbers.

My immediate reaction was: can we use this to power a Gadget frontend?

Gadget already uses Vite for its frontend tooling. If vinext also runs on Vite, we should be able to get it running. So I spent some time experimenting to get a Next-style frontend running inside a Gadget project.

As it turns out you can get something working pretty quickly!

So I figured I’d share the steps I took to set things up. This isn’t meant to be a strict tutorial, it’s more of a “here are the steps I took and how I used agents to do this ” guide.

Also, this is very experimental on both the vinext and Gadget side of things.

You can also check out the video:

The idea

A normal Gadget app contains everything you need to power a modern full-stack web app.

You get a managed Postgres database, a Node backend, authentication and multi-tenancy, and a generated API client. The frontend is a Vite + React Router project that is already wired up to that backend, and has built-in auth and session management.

The experiment was simple: keep all of that exactly the same, but replace the default frontend runtime with vinext.

Conceptually, the architecture becomes:

The backend still behaves like a normal Gadget app. The frontend just adopts the Next programming model running on Vite.

Starting with a normal Gadget app

I began by creating a new Gadget web app and pulled it down locally using the ggt CLI. Relevant for the vinext migration, all new apps have a package.json file, a vite.config.mts, and a web directory containing the frontend (in addition to everything needed to power and configure the database and backend).

The web directory is where everything interesting happens.

Normally, Gadget frontends use React Router. In this experiment that router disappears and the frontend becomes a vinext app instead.

Once that swap happens, the project suddenly feels a lot like a Next app. Instead of client-side routing handled by React Router, the project now uses vinext’s Next-style page routing. Page components, layouts, and routing conventions look exactly like what you’d expect from a new NextJS app.

What’s nice is that all the Gadget primitives still work exactly the same way. For example, grabbing the authenticated user in a component still looks like this:

const user = useUser();

That hook comes from Gadget and continues to work normally as long as the GadgetProvider is setup properly. vinext is just responsible for routing and rendering.

Making Vite happy

The only part of the integration that required a bit of experimentation was the Vite configuration.

The project needs both the Gadget Vite plugin and the vinext plugin so the frontend can run the vinext runtime while still talking to the Gadget backend. (The Tailwind plugin was used too. It didn’t need to be touched.)

It seems like authentication needed a small passthrough configuration so auth-related requests resolve correctly during development. This was the major hangup I ran into during the migration experiment, and Codex helped me resolve it. It’s definitely possible (probable, even) that there’s a more “Next-native” way to handle this.

vite.config.mts

/**
 * Vite plugin that prevents vinext/RSC from handling Gadget backend routes.
 *
 * The @vitejs/plugin-rsc registers a catch-all middleware that writes a
 * response for ALL requests (returning 404 for unmatched App Router routes).
 * This prevents Gadget's platform from handling backend paths like /auth/*
 * (OAuth flows).
 *
 * This plugin patches the middleware stack after all plugins have registered,
 * wrapping every async handler so that backend paths call next() instead of
 * being handled by the RSC renderer.
 */
function gadgetBackendPassthrough(): Plugin {
  const backendPrefixes = ["/auth/"];

  function isBackendPath(url: string): boolean {
    const pathname = url.split("?")[0];
    return backendPrefixes.some((prefix) => pathname.startsWith(prefix));
  }

  return {
    name: "gadget-backend-passthrough",
    configureServer(server) {
      // Return a post-middleware setup function. This runs after all
      // plugins' configureServer hooks, including vinext and RSC.
      // By listing this plugin AFTER vinext, our setup function runs
      // after the RSC middleware is already in the stack.
      return () => {
        const stack = server.middlewares.stack;

        for (const layer of stack) {
          const fn = layer.handle;
          if (!fn || (fn as any).__gadgetWrapped) continue;

          // Wrap all 3-param middleware handlers (req, res, next)
          // to skip backend paths. This catches the RSC handler
          // regardless of its name.
          if (fn.length === 3 || fn.length === 2) {
            const original = fn;
            const wrapped = function (req: any, res: any, next: any) {
              const url = req.originalUrl ?? req.url ?? "";
              if (isBackendPath(url)) {
                return next();
              }
              return original(req, res, next);
            };
            (wrapped as any).__gadgetWrapped = true;
            layer.handle = wrapped;
          }
        }
      };
    },
  };
}

Once those pieces are in place, vinext spins up and I can build like I would any other NextJS app, but using my Gadget API client to call my app APIs.

Letting an agent do the migration

Rather than doing everything by hand, I let an agent (Codex) handle most of the conversion.

I started with a fresh NextJS app and used the cloudflare/vinext agent skill to convert it to vinext. If you have an existing app, you could convert it instead. The skill one-shot the transformation. I tested locally and used the converted project as a reference for migrating my Gadget app.

From there, it was mostly a matter of copying the frontend structure into the Gadget project and adapting it so it used the Gadget API client and authentication hooks. The agent took care of all of it for me. There was a bit of back and forth around using the Vite Tailwind plugin (my reference app used PostCSS instead). And the only other hangup was the auth passthrough.

Look ma, no Next!

Once everything is wired together, you can build a NextJS-style app on Gadget. But, you know, without actually using NextJS.

You still get access to Gadget’s infra-less setup: define data models, Gadget generates the API client, and call those APIs directly from vinext pages. Authentication flows through Gadget. Multi-tenancy still works. The hosted development environment’s backend and database are unchanged.

The frontend just happens to speak the Next API.

vinext is still very early, but the idea behind it is compelling. If the Next programming model can run comfortably on top of Vite, it opens up a lot of flexibility in how those applications can be built and hosted.

Gadget happens to fit that model well. Because the platform already exposes backend services through a generated client, the frontend runtime becomes relatively interchangeable (so long as it uses Vite!). vinext just restructures how you build the UI layer.

This experiment worked better than expected. But let's be real: I migrated a fresh NextJS app and a fresh Gadget app. I didn’t have a bunch of existing, complex logic. I wasn’t exactly pushing the boundaries of vinext here.

But as a proof of concept, running vinext inside a Gadget project is very possible.

Want to chat more or have questions? I’m usually hanging out in our dev Discord.

Building Hubspot custom objects in Gadget

Gadget — Tue, 17 Feb 2026 19:07:03 +0000

Extend HubSpot with custom objects powered by Gadget’s managed infrastructure, no Hubspot plan upgrade required!

While working on internal automations in HubSpot, I hit a wall.

At Gadget, we have a partner program, and we wanted to optimize and automate this process as "we" - (Franco, Head of Partnerships) handled this process manually. As you can imagine, having to manage a massive spreadsheet of partners to ensure every referral is tracked and associated with a partner account is not the preferred way to start each and every morning.

I was tasked with finding a solution in HubSpot because tracking relationships between partners makes sense to do in a CRM (Customer ‘Relationship’ Management) tool.

But I hit a wall. I was unable to create more than 2 objects in Hubspot, and by default, HubSpot already contains 2 objects, Customers and Companies.

So I checked what plan we would need to get one more object, and the price increase was the definition of “sticker shock”.

My next thought was “why not build the Hubspot extension in Gadget?”, which then expanded to “This would be an amazing template for users to plug-and-play for internal apps.”

That's how we got here with the HubSpot Static Object template. The goal here is to:

Save you a hefty annual subscription
Build your own custom automations
And keep your data if you end your subscription for that extra custom object

Watch a full walkthrough on deploying the app template here:

This template is built from the internal issues we had at Gadget and refined for other HubSpot users facing steep price increases to unlock additional functionality. The app template uses Gadget to rapidly provision Postgres-backed data models, automatically generate CRUD APIs, and manage authentication and environment configuration out of the box.

On top of this foundation, Node is used as an orchestration layer to handle HubSpot-specific workflows such as JWT validation, conditional business logic, and coordinated read/write operations between HubSpot and the Gadget database, making it well suited for managing team-level data within a larger organization as a custom object.

For example, you may have 2 separate customers under the same domain or company and in HubSpot, that is not easy to distinguish, nor is it practical to make and manage a separate variant Company object of that Company account.

This template creates a custom object to manage groups within a company. Let's walk through it step by step!

The first step to a custom object is determining the fields and data required. This will be seen in the templates api/models/customObjectTeam model that contains the fields:

teamName - Name of the team
teamContacts - Array of HubSpot contact IDs
parentCompany - HubSpot company ID
portalId - HubSpot portal/account ID

These fields allow us to define a teamName and track associated contacts within the array.

When you create a model in Gadget it automatically creates the Postgres table and CRUD actions to handle Create, Update, and Delete, which are also included in the customObjectTeam model.

The template exposes this custom object to HubSpot through a small set of Node-based API routes that act as an orchestration layer between HubSpot and Gadget’s data models.

The primary routes are api/routes/hubspot/GET-teams.ts and api/routes/hubspot/POST-action.ts, which handle reading, creating, and updating team records stored in Gadget’s Postgres database. These routes are responsible for coordinating HubSpot requests, applying conditional business logic, and translating HubSpot-specific identifiers into the internal data model.

By handling this logic in Node, the template keeps complex workflow and integration behavior outside of HubSpot while still allowing HubSpot to act as the primary interface for users. All route access is secured using JWT-based authentication, which is enforced consistently across these endpoints.

The app card uses JWT auth to securely query the Gadget backend from Hubspot using HubSpot’s v3 authentication spec, which is handled in api/routes/hubspot/POST-auth.ts and keeps the connection secure.

Breaking down api/routes/hubspot/POST-auth.ts, it:

Extracts the Bearer token from the Authorization header
Verifies the JWT signature using GADGET_ENVIRONMENT_JWT_SIGNING_KEY
Checks that the session exists and hasn't expired (10-minute window)
Throws an error if any validation fails

By externalizing custom objects into Gadget, you regain control over your data model, your automations, and your long-term costs without giving up HubSpot as the system of record for relationships. If you’ve ever hit the same wall we did, this approach offers a practical, extensible way forward.

Diagnose issues in production and development, with the operations dashboard

Gadget — Tue, 20 Jan 2026 18:22:17 +0000

Gadget's new operations dashboard provides charts and tables that help devs investigate errors and inefficient application code.

The operations dashboard helps you understand how your app behaves, providing up-to-date information about your app’s performance, errors, and resource usage, while you build and after you deploy.

Because Gadget runs every development environment on real cloud infrastructure, operational signals appear early. Slow queries, inefficient actions, background action retries, and excess resource usage (especially excessive Shopify syncs) don’t wait for production. The operations dashboard surfaces those signals in a single interface, so you can understand performance and cost as you build and after you have deployed to production.

The database view in the ops dashboard:

A clear picture of how your application runs

The ops dashboard provides visibility into your application’s performance, errors, and resource usage through a collection of pre-built charts and tables. Together, they show how real requests move through your system.

Instead of interpreting isolated metrics, you can see how traffic, execution time, failures, and infrastructure usage change over time, and how they relate to one another.

Because charts share a selected time range, you might notice a spike in database activity driven by a specific query pattern, then look at the same time window to see how that change affected background processing, search indexing, or overall compute usage. Keeping these signals aligned makes it easier to reason about cause and effect across the hosted infrastructure.

So, what does the dashboard show me?

The operations dashboard includes pre-built charts that span the full lifecycle of a running application:

App overview: HTTP status codes, errors, actions run, CPU time, and number of platform operations performed.
Worker health: Worker CPU usage, memory consumption, event loop utilization, and how they all scale. (Read the docs to learn more about workers and the Gadget runtime environment.)
Database usage: Query volume, storage, read and write volume, and how they correlate to rate limits, index usage, and file storage size.
Search usage: Request volume, read/write activity, storage and index usage.
Background actions: Number of action attempts, and enqueued, failed, cancelled, and running action counts.
Traffic behaviour: Route requests, bandwidth, and average page load times.
Shopify activity (Shopify apps only): Number of Shopify API calls, rate limit errors, webhooks, syncs, and active installs.

These charts are displayed on a shared timeline, making it easy to move between application behavior, infrastructure usage, and cost without losing context.

If you want to learn more about individual tables, we have descriptions of each table in our docs.

How engineers actually use the operations dashboard

Engineers don’t usually open the ops dashboard to look at a single metric. They use it to understand why the system is behaving a certain way and what changed. The dashboard is designed to help engineers reason about performance, errors, and resource usage together, instead of in isolation.

A few common workflows:

Tracing a performance regression After a deploy, request times start creeping up. By looking at traffic, execution time, and database activity on the same timeline, you can quickly see whether the slowdown is coming from increased user activity or long-running logic in your actions or routes.
Understanding background work under load As traffic increases, background actions may start to queue or take longer to complete. The dashboard makes it easy to see when workers are spending more time under load, whether jobs are piling up, how often background actions need to be retried, and how that correlates with CPU and memory usage.
Catching inefficiencies early in development Because the same dashboard is available in development environments, you might notice an unexpected spike in database reads, retries, or search indexing while building a feature. Seeing that behavior early makes it easier to fix inefficient queries or actions before they become production problems.
Investigating errors with context When errors increase, the dashboard shows what else was happening at the same time: traffic changes, worker saturation, rate limits, or resource pressure. That context helps distinguish between transient issues and problems rooted in application behavior.‍
Making informed performance and cost tradeoffs By connecting resource usage to real application activity, engineers can see whether increased compute or database usage is driven by real demand or avoidable work. That makes it easier to decide where optimization is worth the effort and where additional resources are the right tradeoff.

Instead of jumping between logs, metrics, and dashboards, the operations dashboard gives engineers a single, shared view of how their application behaves as it’s built and as it scales.

Resource usage you can reason about

Because Gadget runs every environment on hosted cloud infrastructure, resource usage matters before you hit production. The ops dashboard surfaces how your application uses compute, database, storage, and network resources while you build and test your app, so cost isn’t something you only discover after deploying.

By connecting resource usage to application behavior, the dashboard helps explain changes in your monthly spend. You can see whether increases are driven by real demand, background work, inefficient queries, or long-running actions, and make informed tradeoffs as you iterate. This makes it easier to understand how changes in traffic or code affect your monthly bill before they become a surprise.

The same dashboard is available in development and production environments. Because all Gadget environments run on the same managed runtime, the signals you see while building are the same ones that matter in production.

The result is fewer surprises and an application that’s easier to operate as it scales.

Under the hood, the dashboard is powered by ClickHouse and backed by precomputed materialized views, so you can explore high-volume operational data interactively without slow queries or long load times. The result is a fast, always-on view of how your application behaves across every development and production environment.

Have questions or want to dig deeper? Ask us in our developer Discord or check out our documentation.

Want to learn more about how to use the operations dashboard? See Gadget CTO, Harry Brundage, explain each chart and how to use them:

Building HubSpot apps in 2025: What’s new, what’s changing, and how to get started.

Gadget — Tue, 06 Jan 2026 15:53:33 +0000

HubSpots developer ecosystem is changing a lot, so let's break down what is changing for developers like yourself.

HubSpot’s developer ecosystem has expanded rapidly over the last two years. With the release of HubSpot’s Developer Platform, they are transitioning away from legacy CRM extensions, which were all crammed in the side-bar, toward a much more capable environment by taking apps out of the side panel with App Cards, alongside a modernized HubSpot CLI, and a long-awaited local development workflow.

Whether you’re building a lightweight internal integration or a full commercial app for the marketplace, understanding these changes is essential. This post summarizes the key improvements, how the new platform differs from the legacy model, and what new tooling options are available to developers in 2025.

The new HubSpot app environment

HubSpot’s new development environment is designed to be significantly more extensible, structured, and consistent than the previous generation of “sidebar-only” CRM extensions.

Extensible App Cards

Extensible UI options like the App Card are the centrepiece of the modern HubSpot app framework, compared to legacy CRM Cards (deprecated in 2025 and sunset in October 2026).

At a high level, the key differences are:

Placement is flexible: cards can appear in the main record pages, not just the sidebar.
Rendering is reactive: extensions use React UI components within HubSpot’s native UX.
Data access is easier: apps fetch data through hubspot.fetch(), which handles the data handling process for developers out of the box
More ways to view data: App Objects, Events, and eventually Home Pages provide a path to more deeply integrated experiences.

Account executives and BDRs can rejoice now as information can be more digestible at a glance, rather than a slow, clunky sidebar. Rather than sit, wait, and scramble to review the Legacy apps data 5 minutes into the customer call, sales teams can be right on time with the center page app card, giving them what they need at a glance, between back-to-back calls.

App settings & app home

The new App Settings and App Home experiences allow developers to build configuration UIs directly inside HubSpot. You no longer need an external settings page or a separate admin dashboard. Apps can now:

Store and render their own configuration screens
Allow merchants to manage connections and preferences
Use the same UI Extensions framework as CRM-facing cards

This closes a long-standing pain point for app developers and users where the app existed on an object page side-panel.

There is a large list of beneficial changes for developers, all in the right direction, with more development environment customization, logging, and promised consistency for future HubSpot API changes.

These changes include:

Developers can now configure which combination of hub and tier their test accounts are, whereas before it was always enterprise
Developers can configure & deploy single projects across multiple environments, as well as define and set reference environment variables
Easily integrate Sentry and Honeycomb for logging and debugging
Regularly cadenced releases for API updates in March and September, as well as selectable versioning.

A notable feature in the HubSpot CLI is the hs get-started command, which scaffolds a working starter app, authenticates the CLI, and walks developers through deployment and installation. During this process, templated app cards, AGENTS.md, and CLAUDE.md are generated so your app is AI-ready as well.

HubSpot has also promoted several upcoming Breeze AI features designed to help developers build faster by searching documentation, educating, exploring, debugging, and scaffolding. Breeze is also exposed through an MCP server, enabling the same AI capabilities to be used in any MCP-compatible environment, such as IDEs or chat tools.

Of the mentioned AI features, the only ones currently available are the “Fast and Intelligent” documentation search, and debugging. The accompanying material with these statements is just the AI chat found in the developer documentation page, and not embedded in the app logs page.

So far, anecdotal experience with these features feels like another AI assistant straight from Anthropic, lightly wrapped in whatever content it’s claimed to be an “expert” on. Key highlights from my experience of using Breeze AI are:

This was a miss for me as a result of the expectations. I found it quite slow, strangely clunky with page navigation, and the Assistant did not seem properly educated or integrated on the HubSpot docs knowledge base for about half of my questions.
There were instances where I could tell it was not searching the HubSpot docs for questions I had and used external information that did not pertain to HubSpot's components.
Heavily gravitates to assuming all questions pertain to Legacy apps
There was a specific instance where I got lost in the HubSpot menus (as we all do) and asked the Breeze AI “Where can I find my App’s logs”. The response was that “Legacy Apps do not have logs”, and when I clarified more that this is a “Non-legacy app” it told me HubSpot does not have logging capabilities, and I will need to use an external platform. I knew it existed as I do use the logs in HubSpot, and eventually found it myself in /Development/Monitoring/Logs. Then selected my app from the dropdown menu at the top of the screen.

Authentication

With the expansion of the HubSpot app store comes a push for a standard web application experience, meaning OAuth for multi-tenant apps. You will still have the option of static auth for private app distributions.

If you are looking to have your app be publicly listed on the HubSpot app marketplace, you will need to use OAuth.

If you are building a private app for a single client, an internal tool, or just want to start building without worrying about OAuth, Hubspot's static authentication is a fast way to get started.

The primary difference between OAuth and static is how your application backend will obtain its access token. With OAuth, your backend must perform the full authorization flow. This includes generating an authorization URL using your HubSpot app’s Client ID, Client Secret, redirect URI, and required scopes.

Users are redirected to HubSpot to grant access, and HubSpot sends your backend a temporary authorization code at the redirect URI. Your backend must exchange this code for an access token and a refresh token using HubSpot’s token endpoint, then store and refresh these tokens as needed. In contrast, static auth allows you to manually supply the Client ID, Client Secret, and permanent access token without performing redirects or token exchanges.

For more information on working with OAuth you can check out HubSpot’s developer docs, OR stay tuned to our Gadget blog for our upcoming Gadget app template for HubSpot Oauth, which will have a working implementation for HubSpot Oauth.

Start building Hubspot apps on Gadget

HubSpot’s 2025 platform is a great step forward for a new era of extensibility in the HubSpot ecosystem. With a fully modern app framework, richer UI options, more predictable APIs, and a growing set of developer tools, builders can finally create polished, reliable, highly integrated experiences inside HubSpot.

As the platform evolves through 2025 and beyond, we look forward to seeing the support HubSpot is putting forward in developers to nurture its platform and add highly requested and bespoke capabilities for a wide range of businesses.

Want to start building private Hubspot apps for single clients? Try out the Gadget Hubspot template. It includes static auth, user and session token management, and gives you a hosted and scaled Postgres db, serverless Node backend, and Vite frontend for your app admin.

Getting started with Shop Minis (and other mini apps!)

Gadget — Thu, 04 Dec 2025 21:54:12 +0000

Learn about the Shopify Shop Mini ecosystem and how to get started building Shop Minis with custom backends.

TLDR: Shop Minis are custom, cross-merchant apps that enhance the buyer experience in Shopify’s Shop app. Gadget now has a template that handles authentication, session management, and data multitenancy for Shop Mini apps.

Shopify recently announced Shop Mini apps, providing developers a way to provide shoppers custom experiences in Shopify’s Shop mobile app. I’m going to talk a bit about what mini apps are, what is unique about Shop Mini apps (compared to “traditional” admin-embedded Shopify apps), and how you can start building and submitting your Shop Minis.

If you need a custom backend or database for your Shop Mini, check out the Gadget template and follow the README to start making authenticated requests from your mini to Gadget.

Prefer a video?

What are mini apps?

Mini apps aren’t unique to the Shop app. In fact, on November 13, Apple announced their own Mini Apps Partner Program, accompanied by mini app billing APIs (which are notably absent for Shop Mini apps!).

Mini apps are small applications built with web technologies like HTML, JavaScript, and CSS, that run inside a host application rather than inside a web browser. A host app provides some combination of an outer shell, navigation, identity, APIs, and native UI elements, and the mini app delivers focused functionality inside that wrapper.

It’s like if you were eating a sandwich, and inside that sandwich was another, smaller sandwich. The outer sandwich provides structure and a foundation, something you can hold. The inner sandwich: a delightful twist of new flavors. There is probably a food truck in Portland that sells these already.

A better example: building games for the Discord mobile app:

Mini apps can be built inside the Discord mobile app!

You can think of it like embedding a web-powered widget inside a native container. The host controls high-level concerns; the mini concentrates on a specific user interaction. With mini apps for mobile, you can bypass building, deploying, or managing a full mobile app and instead deliver reach through the existing host app’s user base.

The recently announced ChatGPT App SDK is another example of a mini app. The Apps SDK enables devs to build custom functionality inside ChatGPT (for the 800 million monthly users) and provides an API and design system you can use to extend ChatGPT’s base functionality.

What are Shop Minis?

Shop Minis are just mini apps for Shopify’s Shop mobile app and its user base. (The Shop app is a central hub for all merchants selling on Shopify. Instead of a shopper having to find and visit individual shops, they can discover ALL Shopify products in a single place.)

Instead of building tools for merchants or storefronts like you would when building traditional embedded Shopify apps, a Shop Mini delivers enhancements to the buyer experience across any merchant using Shopify.

Use cases for Shop Minis include things like: custom style pickers, color or complement-color finders, enhanced product discovery and recommendations, or other buyer-facing UI features. In some ways, you can think of a Shop mini as analogous to a theme extension, but instead of modifying a storefront, you’re extending the Shop app itself for shoppers.

Shop Mini app examples:

This is powerful because it gives you reach across all Shopify merchants, without requiring each merchant to install or configure the mini individually. Once your mini is approved, any buyer using Shop can use your mini to find product recommendations.

How to build Shop Minis

At the moment, the Shop Mini functionality is part of a pilot program, not yet broadly available. However, Shopify has established a framework for early partners to develop, submit, and ship minis.

If you are already familiar with traditional web tools and React, building a functioning Mini won’t be difficult (once you download XCode and/or Android Studio.) Shopify provides a well documented API for fetching cross-merchant products and, for apps with custom backends, has provided an auth example using Supabase Edge Functions.

A sample Shop Mini app - tutorial coming soon:

Here is what you need to know if you decide to build a Shop Mini app:

Minis are built in React using a project generated by a command-line interface, via a @shopify/shop-minis CLI.
Mobile-first: Even though you’re building in React, you need to build and test your mini using Android Studio or XCode. If you try to build on a web browser you will only ever get mock data. This is a trap! Just use the mobile simulators from the start!
Styling & UI ecosystem: The mini runs with a provided component library + styling support (Tailwind CSS, a set of SDK components, icons from Lucide), to ensure a consistent look and feel inside the Shop app. Using emojis instead of Lucide icons? Instant rejection.
Limited dependencies: Shopify enforces strict dependency constraints. Using an npm package not on the list? Instant rejection.
Data fetching & hooks: Shopify provides hooks to fetch relevant data like user info, product data, and other context. These hooks are the intended way to access Shopify data, especially merchant and product data. Reading product data from a custom endpoint? Instant rejection.
Backend + auth architecture:
- You can build a custom backend to support your mini, which requires you to set up JWT authentication on your server.
- Before signing a JWT, you need to call the Mini Admin API with the provided Mini API key to verify that the auth request is legitimate.
- Session and user management, and data multi-tenancy must be handled manually.
- The mini must request the openid scope and trusted domains need to be registered in manifest.json.

The auth flow for custom Shop Mini backends:

Analytics & metrics: The mini framework includes analytics support so you can monitor how often your mini is used and measure conversions, such as how often buyers use your mini to go from browsing to purchase. This helps you understand impact and performance.

The Shop Mini docs are great and will help you get started. There are strict guidelines that you need to follow when building Shop Minis, including a hefty list of prohibited practices. Familiarize yourself with these items before you start building!

Publishing your Shop Mini

The Shop Mini CLI has a submit command you can use to send your mini to Shopify for review.

As part of the submission, you must supply your source code and dependencies, which will be reviewed by the Shopify team. You also need to record a video demonstrating the full end-to-end flow: what happens from the buyer opening the Shop app, to launching/using the mini, to the end result (and benefit!) for the buyer.

I expect these reviews to be incredibly thorough. Mini apps reflect on Shopify and their Shop app, and poor-quality minis will discourage buyers from using Shop in the first place. The review will check for compliance: security, performance, bundle size (Shopify is targeting <3 seconds for load and <5MB bundle size), correct behavior, and user experience, and the team will be making sure you don’t violate any of the Shop Mini guidelines.

There’s a financial incentive for early builders: Shopify is offering a bounty of $5,000–$10,000 if the mini is submitted, approved, and launched by December 20. And if your mini makes use of AI, there is also reimbursement available for AI usage up to $500 per partner per month.

Because the Shop Mini ecosystem is still relatively new, documentation and tooling are evolving. Treat this as an opportunity to influence the ecosystem. If you build now, you’ll learn early and be able to provide feedback to Shopify that shapes how Shop Minis work going forward.

Summary

Shop Minis are a new mechanism for embedding buyer-facing functionality inside the Shop mobile app. Built in React and bound by strict constraints (styling, dependencies, performance, security), they allow developers to ship cross-merchant experiences at scale. Devs get access to the massive user base already using the Shop app. And with a custom backend and database, you have flexibility to deliver custom features, data, and behaviors to these users.

If you want to build features that serve buyers directly without asking merchants to install or configure anything, minis are worth exploring.

Start building Shop Minis today, with the Gadget template. Setup instructions are in the README.

Building scalable backends for Swift mobile apps

Gadget — Wed, 03 Dec 2025 20:07:00 +0000

Learn how you can use Gadget as an auto-scaling backend and database for mobile apps built in Swift.

In the past, only web developers used Gadget's infra and benefited from the smooth developer experience. Swift developers are getting wise to the productivity gains. The Swifties are beginning to join the revolution and do double the work in half the time with the Gadget platform.

In this little walk-through, we'll use Gadget to spin up a database and API in minutes. Then we'll get a Swift app to talk to the Gadget backend using auto-generated code from the Apollo iOS package.

The Swift app we'll be building is a pushup tracking app. Users can log pushups, and see a graph of how many pushups they've done in a week.

Spin up the DB and API

Gadget has a web-based editor like Replit, but you can also use the framework in your local dev environment. Either way, you need to sign up for a Gadget account, then create a new app via the browser.

When prompted, choose Web app and enable auth.

Name your app, then let Gadget do the heavy lifting spinning up the database and API.

The pushup table

Once the Gadget app is set upsetup, we need to add the table that will store the user's pushups. In the left navbar, go to the api/models folder. Notice Gadget already created a user table that securely stores each user's account info.

Press the "+" icon beside the models folder to create a new table in your app. Let's name our new table pushup. This will create the schema, database and API endpoints to CRUD the database. That's about an hour of work saved right there. Huzzah!

Now let's add two columns to the database. The first records the number of pushups the user logged. The second is the foreign key to the user table. The foreign key says which pushups belong to which users.

Number of pushups field

Select schema, then press the "+" to add a new column to the database.

Name the field numberOfPushups
Choose Number as the field type
In the validation section, make the name field required

User foreign key

Click the + button to add another field
Choose Belongs to as the field type
Set the API identifier to user
In the Related model dropdown, select user
This creates a many-to-one relationship (many pushups can belong to one user)

Auth
Now let's update permissions so that users can only read the pushup records associated with their account.

Navigate to accessControl/filters/pushup. This is where your Gelly filters should live for the pushup model. Press the + icon to add a new filter.

Name the filter something like tenancy.gelly. We want the filter to make sure the user ID associated with the request equals the user ID associated with the pushup. Here’s the gelly code that does that:

accessControl/filters/pushup/tenancy.gelly

filter ($user: User) on PushupLog [
  where userId == $user.id
]

Copy & paste that into your new gelly filter.

Now we need to add this filter to the read action. Gadget has a handy GUI for that. You can find it by navigating to accessControl/permissions.

Hover on the pushup/read row, and add a filter:

Select the name of the filter you just created.

Now the filter is associated with the read action, users can only view pushup records they created. We have thwarted the throng of nosy hackers once again — what a thrill.

Create the Swift app

Believe it or not, we're done with the backend! Now let's create a simple Swift app that allows users to sign in, then manage their pushups.

The Swift code is available on GitHub. Let's set up and run the app:

Open Xcode, and select Clone Git Repository:

Paste https://github.com/gabeb03/repcount into the search box and press Clone.

In the Menu Bar, select Product > Scheme > Edit Scheme. Select the run section, then add this environment variable:

Product > Scheme > Edit Scheme

PUSHUP_GRAPHQL_ENDPOINT = https://<your app name>--<your environment>.gadget.app/api/graphql

Now you can press the run button, and play around with the app. When you create new pushups, you should see them come up in the Gadget database. Go to api/models/pushup/data to see the data that has been added to the pushup table.

Shazam!! You have a beautiful app that saves pushups to a scalable, secure backend.

Swift codebase deep dive

This section is for the folks who want to know exactly how I got our pushup app to talk to the Gadget API.

Let's dive into the key parts of the codebase. By the end of this section, you should be able to drop Gadget into any native Swift app. Buckle up: we're going to cover a lot here.

The auto-generated GraphQL API

Our goal in life is to write Swift code that will make API requests to Gadget. We want to use the API to create and read pushup entries from the database.

Usually, we'd have to write all the code to do that by hand. Fortunately, Gadget knows how lazy we are, and has written all that code for us.

Gadget automatically spins up a GraphQL API that allows us to read/write to the database.

Now all we have to do is write the Swift code to make calls to the GraphQL API.

There are two ways to make calls to the Gadget API: write all the GraphQL API queries by hand, or generate those queries based on the Gadget's GraphQL schema. The second option is way easier. Let's go with that one.

Install Apollo

The Apollo library makes it super easy to generate the Swift code to hit the Gadget API. Go to File > Add Package Dependencies, then paste https://github.com/apollographql/apollo-ios.git into the search box.

Add the package, then add Apollo and ApolloAPI to the target

Finally, we need to install the Apollo CLI. Right click on the project name, then select "Install CLI"

Get schema

Apollo needs the GraphQL API schema to be able to generate code. We can fetch it using npx:

Terminal

npx -p @apollo/rover rover graph introspect https://repcount--development.gadget.app/api/graphql

Copy the schema into your project. I put my schema in ./graphql/schema/graphqls

Set up codegen config

Next, we need to tell Apollo how to generate the Swift files. All the settings are specified in a file called apollo-codegen-config.json. There's the JSON file that worked for me. You'll need to tweak it for your project.

apollo-codegen-config.json

{
   "schemaNamespace": "RepcountAPI",
   "input": {
     "operationSearchPaths": [
       "GraphQL/**/*.graphql"
     ],
     "schemaSearchPaths": [
       "./graphql/schema.graphqls" // <- put the path to your schema here
     ]
   },
   "output": {
     "testMocks": { "none": {} },
     "schemaTypes": {
       "path": "./RepcountAPI",
       "moduleType": {
         "embeddedInTarget": {
           "name": "Repcount"
         }
       }
     },
     "operations": { "inSchemaModule": {} }
   }
}

Here comes the annoying part: you need to write the GraphQL mutations you want to convert to Swift by hand. Make a folder with all the GraphQL mutations. My mutations are in /graphql. It doesn't matter where you put the queries. Apollo will look everywhere in your project and turn <any file name>.graphql into Swift code.

All the GraphQL mutations I wrote for the pushup app are here. Take a peek at Gadget's GraphQL docs if you're unfamiliar with Gadget's auto-generated GraphQL API

Generate Swift code

Now all your GraphQL queries are written out, you can use Apollo to turn those queries into Swift code.

Go to the terminal, and run the following from the root folder of your Swift project:

Terminal

../apollo-ios-cli generate

The Swift files should magically appear in the folder you specified in apollo-codegen-config.json.

Deal with Xcode being dumb

You are probably going to see a bunch of errors in the generated code that contain "cannot satisfy conformance requirement for a 'Sendable'"

You can fix that by double-clicking on the project name:

Go to Build Settings, then Swift Compiler - Concurrency. Set Default Actor Isolation to nonisolated. You should be able to build your project, and call the Gadget API from any Swift file!

As far as I can tell, Swift Concurrency is to blame for this quirk. Older Swift code was written assuming that it would all run on the main thread. In this brave, concurrent world, that may not be the case. Old, non-current Swift code was breaking, and developers were angry. Apple patched this problem by treating non-annotated code as if it were intentionally main-thread-bound. You make code main-thread-bound by adding the @MainActor annotation. The “Default Actor Isolation = MainActor” means “treat every unannotated file as if it has the @MainActor annotation”. The data models Apollo generates are meant to be passed between threads, so when they are given the @MainActor annotation, the compiler gets very angry.

Setting “Default Actor Isolation = nonisolated” doesn’t add the MainActor annotation to every file, and the compiler gets happy again.

Session token authentication

Thanks to Apollo, we can talk to the Gadget API, but all requests we make from the Swift app will be unauthenticated. Unauthenticated users can't even read pushup records, so we need to set up session authentication so the Gadget API knows the user making these API requests has signed in. Here’s a little diagram showing how we’ll set up auth:

When our beautiful app wants to make an authenticated request, it includes the session ID that was stored locally in the Authentication header of the request:

All the code I’m going to show you is stolen from the Gadget auth docs. Check 'em out if you get stuck.

When the user signs in, we need to store the session token in the Keychain. The session token is what authenticates requests, so it needs to be kept in a secure spot. The Keychain is the perfect place.

Here's a quick tour of the services you need to get session token authentication working:

APINetwork.swift. The APINetwork spins up a GraphQL client that can make authenticated calls.
ApolloClient+Async.swift. This extends the Apollo client in APINetwork.swift so that it handles responses asynchronously.
AuthService.swift. This file exposes the sign in, sign out methods. The UI uses these methods to allow the user to authenticate.
AuthSessionManager.swift. AuthService.swift uses the methods in this file to store the session token in the Keychain.
AuthInterceptor.swift. I'm too lazy to fetch the session token from the Keychain every time and include it in every request I send to Gadget. I wrote this interceptor to add the session token to the Authentication header for every request.

I wish there was a cleaner way to do authentication, but this verbose solution is what we are stuck with at the moment. Thankfully all the files above are general enough to work in any Swift project, not just my pushup app. Feel free to copy and paste.

Call the API from the Swift app

FINALLY, we can start reading and writing to the database. Here's how I did it in my pushup app:

Call Gadget API in Swift

import Apollo

final class PushupRepository: PushupRepositoryProtocol {
    private let sessionManager: AuthSessionManager

    init(sessionManager: AuthSessionManager = .shared) {
        self.sessionManager = sessionManager
    }

    private func client() -> ApolloClient {
        return APINetwork.shared.client(sessionToken: sessionManager.session?.token)
    }

    func fetchEntries(for userId: String) async throws -> [PushupEntry] {
        // Instead of passing in userId, you can get it from sessionManager.session?.userId
        let query = RepcountAPI.GetUserPushupsQuery(userId: userId)
        let result = try await client().fetchAsync(query: query)
        let entries = result.pushups.edges.map { $0.node.toEntry() }
        return entries.sorted { $0.displayDate > $1.displayDate }
    }
}

Party time

That's pretty much it! Once you have the GraphQL and authentication setup, you can start working on making the app beautiful and functional.

I'll leave all that fun stuff to you. Bon voyage!

Gadget’s BFCM 2025 (in numbers)

Gadget — Tue, 02 Dec 2025 21:17:21 +0000

Another year, another successful BFCM for merchants and Gadget developers! Let's dive into the numbers.

Black Friday Cyber Monday (BFCM) remains the annual stress test for Shopify and BigCommerce apps, and this year pushed ecommerce traffic higher than anything we (or Shopify) have seen before!

Below is a recap of how Gadget apps performed, how traffic compared to a normal weekend, and how total load stacked up against BFCM 2024.

Total webhooks processed

Gadget processed 173,078,683 webhooks over the BFCM 2025 weekend, which works out to an average rate of 30,048.382 webhooks/minute!

Total webhooks over BFCM 2025:

Webhooks/minute during BFCM 2025:

For context:

Last weekend (Nov 21-24), we processed 83,557,668 webhooks, or 19,342.053 webhooks/minute.

Total webhooks the weekend before BFCM 2025:

Webhooks/minute the weekend before BFCM 2025:

Picking a random weekend earlier in the year, July 18-21, we processed 46,525,567 webhooks, or 10,769.807 webhooks/minute.

Total webhooks July 18-21, 2025:

Webhooks/minute July 18-21, 2025:

During BFCM 2024, we processed a total of 89,406,843 webhooks, equivalent to ~15,524 webhooks/minute. See last year’s post for more info on these numbers.

We almost surpassed last year’s BFCM traffic on the weekend before BFCM 2025!

This means that Gadget’s total webhook volume almost doubled from last year’s BFCM, growing ~94%.

The growth year over year reflects both the increasing scale of the apps built on Gadget and the expanding footprint of event-driven features across the Shopify ecosystem.

Orders, orders, orders

Shopify’s orders/create webhook gives us a rough idea of how many new orders were modified or customized using Gadget apps.

Over BFCM, the average rate of orders/create webhooks processed by Gadget per minute was 970.358!

Shopify orders/create webhooks/minute BFCM 2025:

That’s compared to:

~530 orders/create webhooks/minute the previous weekend
~345 orders/create webhooks/minute during BFCM 2024
~150 orders/create webhooks/minute the weekend prior to BFCM 2024

That’s almost a 3x increase (actual number: ~2.8x) in orders/create webhooks processed compared to BFCM 2024!

Peak webhook rate

This year’s highest sustained traffic reached 52,659.547 webhooks/minute around 15:00 UTC (or 10:00 am ET) on Cyber Monday. The load curve showed a clean ramp, a stable peak throughout the day, and a slow taper as Cyber Monday deals wound down.

Peak webhooks/minute during BFCM 2025:

Weekend spike compared to pre-BFCM traffic

To get an idea of how much of an increase in webhook traffic we see over BFCM, we can take a look at the biggest difference in webhooks/minute rates across BFCM and the weekend prior.

The largest rate difference was 31,619.900 additional webhooks/minute compared to the same minute the prior weekend (50,106.888 webhooks/minute during BFCM vs 18,486.988 webhooks/minute the weekend before BFCM), which is a spot increase of 171%!

Biggest diff in webhook/minute rate vs weekend before BFCM:

Congratulations again to all ecommerce developers for surviving yet another BFCM weekend!

A special shoutout to the Gadget infrastructure team, who spend weeks (and months) prior to BFCM scaling up resources and redefining architecture to handle the increase in traffic over this important retail weekend!

We look forward to scaling up again next year!

Use Gadget's Preact hooks to build Shopify UI extensions

Gadget — Wed, 12 Nov 2025 23:16:04 +0000

@gadgetinc/preact contains hooks and a Provider to manage your 2025-10 UI extension sessions and make custom network requests.

TLDR: Gadget has released Preact hooks to help you build Shopify extensions on API version 2025-10 (and later).

Shopify’s API 2025-10 release marks a major shift for Shopify app developers. Extensions have officially moved to Preact and Polaris web components are now stable. These changes also enable Shopify to enforce a new 64 KB bundle size limit for extensions.

These updates make extensions faster, smaller, and more consistent across Shopify surfaces. They also mean developers may have to replace existing tools and packages with Preact equivalents and (eventually) migrate existing extensions to Preact and web components.

To support Preact extensions, we’re releasing Preact hooks designed to make it easy to work with your Gadget app backend while staying under Shopify’s new bundle size constraints.

The new UI extension stack: Preact and Polaris web components

For years, Shopify extensions and apps have been built with React and Polaris React, or vanilla JS. With 2025-10, Shopify is taking a decisive step forward:

Preact replaces React or vanilla JS in all new extensions.
Polaris web components are used to build extensions (instead of Polaris React) and are loaded directly from Shopify’s CDN.
Extensions must stay under 64kb. This limit enforces fewer dependencies, smaller runtimes, and faster load times for merchants and buyers.

What this means for developers

Preact’s syntax is nearly identical to React. You’ll still use familiar hooks like useState and useEffect, and you will build with JSX. You may need to adapt your tooling and build pipeline. Gadget built a separate package for Preact hooks. Other packages you use in extensions may also need to be migrated.

You’ll also need to switch from Polaris React to Polaris web components. Shopify’s migration guide has a useful mapping of “Legacy” Polaris components to web components.

An important note: Polaris React is officially deprecated. However, as of writing, Shopify has not officially announced a migration deadline for existing extensions. A minimum of 1 year of support is guaranteed for the last React-focused API version: 2025-07.

Using Gadget’s Preact hooks

Gadget’s existing React tooling, the hooks and Provider from @gadgetinc/react and @gadgetinc/shopify-extensions, don’t work with Preact.

That’s why we built @gadgetinc/preact: a lightweight set of utilities that make it easy to call your Gadget backend directly from your Preact-based extension. They handle session token registration, authenticated requests, and data fetching, allowing you to make custom network requests in a “Preact-ful” way.

The hooks included in @gadgetinc/preact match the hooks from @gadgetinc/react, so you can build extensions with familiar APIs. There is one exception: @gadgetinc/preact does not include support for the useActionForm() hook.

Here’s an example of how you might use them in a customer account UI extension to read data and render UI:

extensions/note-goat/src/MenuActionItemButtonExtension.jsx

import "@shopify/ui-extensions/preact";
import { render } from "preact";
import { Provider, useGadget } from "@gadgetinc/shopify-extensions/preact";
import { useMaybeFindFirst } from "@gadgetinc/preact";

// 1. Import (or init) your app's API client
import { apiClient } from "./api";

// 2. Export the extension
export default async () => {
 render(<GadgetUIExtension />, document.body);
};

function GadgetUIExtension() {
 const { sessionToken } = shopify;

 // 3. Use Gadget Provider to init session management
 return (
   <Provider api={apiClient} sessionToken={sessionToken}>
     <MenuActionItemButtonExtension />
   </Provider>
 );
}

function MenuActionItemButtonExtension() {
 // 4. Use 'ready' to ensure session is initialized before making API calls
 /** @type {{ ready: boolean, api: typeof apiClient }} */
 const { api, ready } = useGadget();

 // 5. Use hooks to call your Gadget API
 const [{ data, fetching, error }] = useMaybeFindFirst(api.message, {
   pause: !ready,
 });

 return !fetching && data && <s-button>{data.body}</s-button>;
}

And this pattern can be used for any UI extension built with Preact. (The least favourite child of the UI extension ecosystem, post-purchase UI extensions, still use React.)

Preact hooks are only available for Gadget apps on framework version 1.5 or later. Read more about upgrading your app’s framework version.

Getting started

To start building with Gadget’s Preact hooks:

Set up your new extension.
1. Pull down your Gadget app locally using the Gadget CLI’s ggt dev.
2. Add workspaces: [“extensions/*”] to your Gadget app’s package.json.
3. Generate your new UI extension using the Shopify CLI.
Set network_access = true in shopify.extension.toml.
Install the @gadgetinc/preact and @gadgetinc/shopify-extensions packages.
Init your app’s API client and set up the Provider in your extension.
Start building!

Keep an eye on your bundle size when building! If you exceed the 64kb limit, you will be notified when you run shopify app deploy to deploy your extension.

You can find full documentation and setup steps in the Gadget docs. If you want to walk through a short app build, you can follow our Shopify UI extension tutorial.

Wrapping up

The Shopify ecosystem is evolving fast. With Preact, Polaris web components, and Gadget’s Preact hooks, you can keep your extensions modern and performant without giving up the productivity of React-style development.

If you have feedback or questions, chat with us on Discord. We’d love to hear what you’re building!