Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 55 ยท App Extensions

App Extensions Overview

Learn what Shopify app extensions are, how to generate one, how shopify.extension.toml declares targets, and how app versions and deploys ship extensions to merchants.

So far your app has been a backend plus an embedded page. That covers a lot, but merchants and buyers spend most of their time elsewhere: on the product page in the admin, in the theme, at checkout, in their customer account, at the point of sale. App extensions are how your app puts code into those places without hosting a whole page there.

An extension is a small, self-contained piece of your app that Shopify loads for you, in the right place, with the right data. You do not run a server for it, and you do not control the page around it. You write the piece, declare where it plugs in, and Shopify does the rest. This lesson is the map; the next lessons go deep on each surface. All examples target Admin API version 2026-07; use whatever version the generator writes into your project.

The extension families

Extensions fall into a few families. The names below are the ones you will see in the CLI and the docs.

Family Where it appears Runs where
Theme app extension Online Store theme (blocks and embeds) Rendered by Shopify as Liquid, with your CSS and JS
Admin UI extension Product, order and customer pages in the admin Sandboxed worker on Shopify's side
Checkout UI extension Checkout and thank-you pages Sandboxed worker on Shopify's side
Customer account and POS UI extensions The customer's account pages, the POS app Sandboxed worker on Shopify's side
Shopify Function Discounts, delivery, payments, validation WebAssembly module on Shopify's servers
Web pixel and similar Storefront and checkout events Sandbox on the storefront

The important idea: extension code does not run on your server. It is uploaded when you deploy and executed by Shopify. That is why extensions are fast for buyers, why they cannot touch arbitrary page elements, and why they have a limited set of APIs.

flowchart LR
  subgraph You["Your project"]
    TOML["shopify.extension.toml"]
    SRC["Extension source"]
  end
  CLI["shopify app deploy"]
  V["App version (immutable snapshot)"]
  subgraph Shopify["Shopify platform"]
    ADM["Admin"]
    CO["Checkout"]
    TH["Theme"]
  end
  TOML --> CLI
  SRC --> CLI
  CLI --> V
  V --> ADM
  V --> CO
  V --> TH

Your extension files are bundled by the CLI into an app version; Shopify serves that version in each surface.

Generating an extension

Extensions live in an extensions/ folder next to your app code. The CLI scaffolds them (read-only commands, not runnable on this site):

Terminal
# from the app's root folder
shopify app generate extension

The command asks for a template (for example "Admin action" or "Theme app extension"), a name, and a language where relevant. It creates a folder such as extensions/product-notes/ containing source files and a shopify.extension.toml. While you work, shopify app dev serves a preview and hot-reloads the extension on your development store.

The extension TOML

Every extension folder has a shopify.extension.toml. It answers four questions: which API version, what kind of extension, where it plugs in, and what it is allowed to do.

TOML
# extensions/product-notes/shopify.extension.toml
api_version = "2026-07"

[[extensions]]
name = "Product notes"
handle = "product-notes"
type = "ui_extension"

  [[extensions.targeting]]
  target = "admin.product-details.block.render"
  module = "./src/BlockExtension.jsx"
  • api_version pins the version of the extension APIs. Like the Admin API, it is quarterly (see API Versioning and Deprecations).
  • handle is the extension's stable identifier within the app. Keep it lowercase with dashes, and never rename it casually: the handle is how Shopify knows a later deploy is the same extension and not a brand new one.
  • type is the family: ui_extension for admin, checkout, customer account and POS UI, theme for theme app extensions, function for Functions.
  • [[extensions.targeting]] (a TOML array of tables, hence the double brackets) lists each target: the named slot where the extension renders, plus the module file that implements it. One extension can have several targets.

Extensions that need more than the default can ask for capabilities, for example network access from a checkout extension (covered in Checkout UI Extensions). Merchants see that some capabilities need approval, so request only what you use.

Targets are named slots

A target name reads like a path: surface, page, kind of slot, and a final verb.

  • admin.product-details.block.render: a block shown on the product details page in the admin.
  • admin.product-details.action.render: an action reachable from the "More actions" menu there.
  • purchase.checkout.block.render: a block merchants can place anywhere in checkout through the checkout editor.
  • purchase.checkout.cart-line-item.render-after: content shown after each line item.
  • customer-account.order-status.block.render: a block on the order status page.

The target decides which components and APIs you get. An admin target cannot use checkout hooks, and a checkout target cannot call the Admin API. Always check the target's documentation, because names evolve with API versions.

A runnable manifest checker

The CLI validates your TOML for you. To see what such a check involves, this stand-in validates manifests written as JavaScript objects. It is not Shopify's validator: it knows only a few rules, and the target list is a small sample.

Node.js Validate extension manifests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first two manifests pass, the second one showing that a single extension can appear on two surfaces. The last three each break a rule, which is the kind of feedback the CLI gives you before anything reaches a merchant.

Versions and deploys

You never upload an extension on its own. shopify app deploy bundles the app's configuration and all extensions into one app version. A version is an immutable snapshot with a name. Releasing a version makes it the active one: merchants who have installed your app get exactly that set of extensions and configuration.

Terminal
# bundle, create a version and release it
shopify app deploy

# create the version but do not release it yet
shopify app deploy --no-release --version "2026-07-notes-v2"

# release a version that already exists (also how you roll back)
shopify app release --version "2026-07-notes-v1"

Because versions are snapshots, rollback is simply releasing an older one. The same mechanism carries your TOML configuration from App Configuration with shopify.app.toml, so scopes and extensions travel together. Note the difference from shopify app dev: dev mode previews on a development store and does not touch what merchants of a released app see.

Node.js Simulate app versions and rollback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The stand-in captures the three rules that matter: a deploy always makes a new named snapshot, --no-release creates one without activating it, and releasing an old name is your rollback.

Practical habits

  • One concern per extension. A checkout upsell and a gift-message field are two extensions; they deploy together but evolve separately.
  • Keep extensions small. Bundles have size limits and they load on the buyer's critical path, so avoid heavy libraries.
  • Test on a development store, and remember some surfaces (parts of checkout, for instance) depend on the store's plan; check the docs for the target you use.
  • Treat the handle and target names as API. Renaming a handle creates a different extension from Shopify's point of view.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does the code of a checkout UI extension execute?

    Extensions are uploaded at deploy time and executed by Shopify in a sandbox. They get a limited API, not the page DOM, and need no server of yours.
  2. 2. What does the double-bracket [[extensions.targeting]] in the TOML express?

    In TOML, double brackets define an element of an array of tables. Each element names one target and the module implementing it.
  3. 3. What is an app version?

    shopify app deploy creates a named, immutable snapshot. Releasing it makes it the active version for merchants, and releasing an older one rolls back.
  4. 4. Why is it risky to rename an extension's handle casually?

    The handle is the stable identity of the extension. Changing it makes the next deploy look like a removal plus a new extension.

Summary

  • Extensions put your code into the admin, theme, checkout, customer accounts and POS; Shopify runs it, not your server.
  • shopify app generate extension scaffolds one under extensions/; shopify app dev previews it.
  • shopify.extension.toml sets api_version, type, handle and one or more [[extensions.targeting]] entries with a target and module.
  • Targets are named slots that decide which components and APIs you can use.
  • shopify app deploy bundles everything into an immutable app version; releasing a version, including an old one, controls what merchants get.

Next: Theme App Extensions