Getting started with field validation
You're ready to create a checkout UI extension. You want to set up your development environment so that you can start coding.
In this tutorial, you'll use Shopify CLI to create a checkout UI extension. Shopify CLI generates starter code for building your extension and automates common development tasks.
You'll create a simple extension that renders some text in the checkout flow. You can build up this extension for more complex use cases.

What you'll learn
Anchor link to section titled "What you'll learn"In this tutorial, you'll learn how to do the following tasks:
- Create a new extension
- Run the extension locally and test it on a development store
Requirements
Anchor link to section titled "Requirements"You've created a Partner account.
You've created a new development store, where you've enabled the checkout UI extensions developer preview.
You've created an ngrok account and auth token. The ngrok token is used when previewing your app with Shopify CLI. To learn more about creating an auth token, refer to ngrok’s documentation.
You've created an app that uses Shopify CLI 3.0 or higher, or you've migrated your existing app so that it's compatible with Shopify CLI 3.0 or higher.
Step 1: Generate a new extension
Anchor link to section titled "Step 1: Generate a new extension"You'll use Shopify CLI to generate a new extension.
Navigate to the directory of the app that you want to add your extension to.
Run the following command to start creating the checkout extension:
Select
Checkout UI
as the type of extension.Provide a name for your extension using either dash case or snake case.
Select a template for your extension. You can choose from JavaScript, TypeScript, React, or React TypeScript.
You should now have a new extension directory in your app's directory. The extension directory includes the extension script at src/index.{file-extension}
. The following is an example directory structure:
Step 2: Preview your extension
Anchor link to section titled "Step 2: Preview your extension"After your extension is created, you can work with it by building the app and starting a local development server.
Shopify CLI uses ngrok to create a tunnel that allows your app and extension to be accessed using a unique HTTPS URL.
Navigate to your app directory.
Either start or restart your server to build and preview your app:
When you run thedev
command, the CLI builds and serves your app. It also walks you through multiple configuration steps. If you've already rundev
for this app, then some of these steps are skipped. In some cases, you might be required to manually kill an ngrok tunnel that's already running.To learn about the processes that are executed when you run
dev
, refer to the Shopify CLI command reference.Click the URL that's printed at the bottom of the CLI output to view your extension.
Step 3: Deploy the extension
Anchor link to section titled "Step 3: Deploy the extension"After your extension is created, you can deploy your extension code to Shopify.
Navigate to your app directory.
Run one of the following commands:
When you run the
deploy
command, the CLI deploys the extensions to Shopify as a draft. It also walks you through multiple configuration steps. If you've already rundev
ordeploy
for this app, then some of these steps are skipped.To learn about the processes that are executed when you run
deploy
, refer to the Shopify CLI command reference.After you deploy the extension to Shopify, navigate to your app in the Partner Dashboard.
Troubleshooting
Anchor link to section titled "Troubleshooting"This section describes how to solve some potential errors when you run dev
for an app that contains a checkout extension.
Property token error
Anchor link to section titled "Property token error"If you receive the error ShopifyCLI:AdminAPI requires the property token to be set
, then you'll need to use the --checkout-cart-url
flag to direct the CLI to open a checkout session for you.
Missing checkout link
Anchor link to section titled "Missing checkout link"If you don't receive the test checkout URL when you run dev
, then verify the following:
You have a development store populated with products.
You're logged in to the correct Partners organization and development store. To verify, check your app info using the following command:
Otherwise, you can manually create a checkout with the following steps:
From your development store's storefront, add some products to your cart.
From the cart, click Checkout.
From directory of the app that contains your extension, run
dev
to preview your app:On the checkout page for your store, change the URL by appending the
?dev=https://{tunnel_url}/extensions
query string and reload the page.You should now see a rendered order note that corresponds to the code in your project template.
- Learn how to validate fields at checkout.