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.

An example UI with a custom input box, as rendered at checkout

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 populated your store with test products.
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.

Tip

Learn how to check your Shopify CLI version.

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.

Tip

JavaScript/TypeScript is suitable for smaller projects that require a more straightforward API. React/React TypeScript is suitable when you want an easy model for mapping state updates to UI updates. With JavaScript/TypeScript, you need to map state updates yourself. This process is similar to writing an application targeting the DOM, versus using react-dom.

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 the dev command, the CLI builds and serves your app. It also walks you through multiple configuration steps. If you've already run dev 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:

Caution

The deploy command deploys all of the extensions that are included in your app.

Any unregistered extensions are registered during deployment. You can only register five checkout UI extensions with an app. After you register an extension, it can't be undone.

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 run dev or deploy 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.

Next steps

Anchor link to section titled "Next steps"

Learn how to validate fields at checkout.