DEV Community: João Cunha

Building a Shopify Sidekick app extension: what the docs don't tell you

João Cunha — Mon, 13 Jul 2026 16:28:06 +0000

Shopify quietly opened Sidekick app extensions to all developers on June 17, 2026. If you build Shopify apps, this is a new surface worth grabbing early: your app's data becomes queryable from the AI assistant that ships in every admin, and almost nobody has shipped one yet.

I added one to my B2B onboarding app, Tradelane, in an afternoon. The happy path is genuinely small — but I hit four walls the docs don't warn you about. Here's the whole thing, walls included.

What you're building

A Sidekick data extension is three files and a backend route:

shopify.extension.toml — declares a headless UI extension with the special target admin.app.tools.data
tools.json — JSON Schema for the tools Sidekick can call
src/index.js — registers the tools; each one fetches from your app's backend
a backend route that returns the data

When a merchant asks Sidekick something your extension's description matches ("do I have pending wholesale applications?"), Sidekick calls your tool in a sandbox, your code fetches your backend, and the answer lands in the chat — with clickable links into your app.

The extension

extensions/sidekick-tools/shopify.extension.toml:

api_version = "2026-07"

[[extensions]]
name = "Tradelane Wholesale Application Tools"
description = "Search and summarize B2B wholesale applications: pending, approved, and rejected applications, applicant details, EU VAT (VIES) verification status."
handle = "sidekick-tools"
type = "ui_extension"

  [[extensions.targeting]]
  module = "./src/index.js"
  target = "admin.app.tools.data"
  tools = "./tools.json"
  instructions = "./instructions.md"

The description is not decoration — it's how Sidekick decides your extension is relevant. Write it like you're prompting a model, because you are.

src/index.js is tiny. The sandbox gives you a global shopify object and authenticated fetch to your own backend:

export default () => {
  shopify.tools.register(
    "search_wholesale_applications",
    async ({ status, query, first }) => {
      const params = new URLSearchParams();
      if (status) params.set("status", status);
      if (query) params.set("query", query);
      if (first) params.set("first", String(first));
      const response = await fetch(`/api/sidekick/applications?${params}`);
      return response.json();
    },
  );
};

tools.json declares the input schema (name, description, JSON Schema inputSchema). Same rule as the toml: tool descriptions are prompts. "Search extension for your app" gets you nothing; name the domain and the questions it answers.

You also must add a summary to your app's main shopify.app.toml — deploy fails without it:

[sidekick]
extensions_summary = "Search and summarize B2B wholesale account applications and buyer verification status."

The backend route returns results in MCP Resource Links format, so answers are clickable:

return cors(Response.json({
  results: applications.map((app) => ({
    type: "resource_link",
    uri: `gid://tradelane/CompanyApplication/${app.id}`,
    name: app.companyName,
    mimeType: "application/vnd.tradelane.wholesale-application",
    _meta: {
      status: app.status,
      country: app.country,
      vatCheckStatus: app.vatCheckStatus ?? undefined,
    },
  })),
}));

That cors(...) wrapper is wall #2. Let's do the walls.

Wall 1: the docs say you can't have this (you can)

The build guides still show a "Developer preview — we're selecting partners" banner with an application form. That banner is stale. Sidekick app extensions have been GA for every developer since June 17, 2026 — there's a changelog entry that says so. I almost didn't build this because the docs told me I wasn't allowed to. Trust the changelog, not the banner.

Wall 2: CORS, and an error message that tells you nothing

The extension sandbox runs on a Shopify origin. Your backend runs on yours. Every fetch your tool makes is cross-origin, and if your backend doesn't send CORS headers, Sidekick reports a vague "couldn't connect to the app" failure. Nothing in the extension guide mentions this.

If you're on shopify-app-remix / shopify-app-react-router, the fix is one line — the auth helper hands you a cors wrapper:

export const loader = async ({ request }) => {
  const { session, cors } = await authenticate.admin(request);
  // ... query your data ...
  return cors(Response.json(payload));
};

Authentication, by the way, just works: the sandbox attaches a session token to your fetches, so authenticate.admin() resolves the shop like any embedded request.

Wall 3: you have one second

Sidekick expects tool responses within 1 second, and extensions that consistently miss get skipped. If your app scales to zero (Fly.io, Cloud Run, Lambda...), a cold start eats your entire budget before your query runs.

Practical mitigations: keep at least one machine warm, keep the query trivial (indexed lookups, small take), and keep _meta lean — there's also a 4,000-token response cap, and blowing it rejects the whole response.

Wall 4: testing lies to you twice

Two things made me think the extension was broken when it wasn't:

Sidekick remembers the conversation. I submitted new test data and re-asked in the same chat — Sidekick answered from memory: "no new applications since the last time we checked." It never called the tool again. Test every change in a fresh conversation.

The model summarizes. Sometimes it got the data and simply didn't mention the fields I cared about (it offered them as a follow-up instead). That's not a bug in your extension; it's model discretion. Your instructions.md — an optional file the docs undersell — is where you nudge which fields matter and when.

The rules of the road

Before you ship, read requirements 2.2.8 and 2.2.9: tools must match your app's stated functionality, and no promotions, upsells, or review begging inside the extension — content is checked at deploy and at runtime. Keep data tools read-only; anything that changes state belongs in action extensions where the merchant confirms.

Also: 20 tools per app, 5 intents, 512 chars per tool description. You won't hit these in v1.

Was it worth it?

The whole thing — extension, backend route, deploy, debugging all four walls — was one afternoon. In exchange, my app's data answers questions in the surface every merchant already uses, and "Works with Sidekick" goes on the listing while that sentence is still rare.

If you maintain a Shopify app with any queryable data in it, this is the cheapest differentiation you'll ship this year.

Questions welcome — I kept the war wounds fresh.

6 things I learned building an app for Shopify's new native B2B

João Cunha — Wed, 08 Jul 2026 09:05:21 +0000

This spring, Shopify quietly did something big: native B2B — Companies, catalogs, net terms — became available on all plans, not just Plus. Millions of stores can now sell wholesale without a $2k/month subscription or a heavyweight app suite.

I spent the last month building a small app on top of these APIs (Tradelane, it handles the wholesale application/approval flow that Shopify left out). Here's what I wish I'd known on day one.

1. One email = one company contact. Plan for it.

The constraint that bit me hardest: a customer email can only be the main contact of one company. If a buyer applies twice, or a merchant re-approves someone whose email is already attached to another company, companyCreate succeeds but the contact assignment fails silently unless you handle it.

My fix: treat "approved, but contact not assigned" as a first-class state with a clear message to the merchant, instead of pretending the whole operation failed. Partial success with an explanation beats a rollback nobody understands.

2. The app proxy is underrated for public-facing features

If your app needs a public page on the merchant's storefront (forms, portals, status pages), Shopify's app proxy gives you a route at store.com/apps/your-app/... that forwards to your server with an HMAC signature. Same origin as the storefront, no CORS, no theme code.

Two practical notes: authenticate.public.appProxy(request) (in the Remix/React Router template) gives you the shop and an admin API client, and because the page is same-origin you can later embed it in a theme app extension with a plain <iframe> — no postMessage gymnastics.

3. React escapes your `<style>` tags. Yes, really.

I shipped a form whose fonts silently fell back to Times New Roman. The culprit:

<style>{`
  body { font-family: -apple-system, "Segoe UI", sans-serif; }
`}</style>

React escapes text children — including inside <style> — so "Segoe UI" becomes "Segoe UI", which is invalid CSS, which invalidates the whole declaration. Border-radius from the same stylesheet worked fine, so it took me days to notice. Same thing breaks url("data:...") values.

The fix is the escape hatch that exists precisely for this (spaces added between the braces so this renders on dev.to — in real code they'd be together):

<style dangerouslySetInnerHTML={ { __html: `...` } } />

4. Validate EU VAT numbers with VIES — it's free and merchants love it

If your app touches B2B in Europe, the EU's VIES service validates VAT numbers (and returns the registered business name) via a free API. Fake wholesale applications are more common than I expected, and "VAT valid ✓" next to an application turned out to be one of the most-mentioned features in feedback.

Cache the result — VIES is slow and occasionally down, so check once per application and store valid | invalid | unavailable.

5. hCaptcha over Turnstile for multi-tenant storefronts

My form renders on any merchant's domain via the app proxy. Cloudflare Turnstile wants per-hostname configuration; hCaptcha sitekeys work on any hostname by default. For a multi-tenant Shopify app, that's the whole decision. (Also: append ?hl=en to the script URL, or the widget renders in the visitor's browser language while the rest of your form is English.)

6. Fire-and-forget your emails, but never your writes

Every notification email in my submit path is void sendEmail().catch(log) — if the email provider hiccups, the application still saves and the buyer still sees the success page. A missed email is a degraded state; a lost application is a lost customer. Decide explicitly which failures are allowed to break the request and which aren't.

The gap, if you're looking for one: native B2B handles pricing, catalogs and payment terms well, but onboarding is still rough. The free Forms app can take applications, yet it creates the Company before approval (junk piles up in the admin), skips VAT validation, and doesn't assign catalogs. That's the hole I built Tradelane into. If you're building on the Companies API and hit something weird, my DMs are open. Happy to compare notes.

I built an offline invoice generator in a single HTML file

João Cunha — Tue, 19 May 2026 18:12:45 +0000

I recently built a small offline invoice generator using a single HTML file.

The idea was simple: I wanted something that could run directly in the browser without login, without a backend, and without a subscription.

The tool lets you:

Add your business details
Add client details
Add invoice items
Calculate subtotal, tax, and total
Preview the document
Save it as a PDF

Why offline?

Most invoice tools are either online platforms, subscription-based, or require creating an account. For simple use cases, that can feel like too much.

So I wanted to test a different approach:

download once, open in the browser, use whenever needed.

This is not accounting software. It is just a lightweight document generator for simple client documents.

After building the invoice generator, I also packaged it with a quote generator and receipt generator as a small Freelancer PDF Kit.

If you want to check it out, here it is:

Gumroad: https://jctools.gumroad.com/l/freelancer-pdf-kit

Payhip: https://payhip.com/b/M58nJ

I’d appreciate any feedback on the idea, positioning, or what would make this more useful.