Getting started

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

• Register the extension with Shopify

• You've created a Partner account.

• You've installed the Shopify CLI.

• You've created a new development store, where you've enabled the checkout extensions developer preview.

• You've populated your store with test products.

• You've created an app for your checkout extension.

• You have basic familiarity with React and vanilla JavaScript (JS).

You'll use Shopify CLI to scaffold a new extension. In a subsequent step, you'll register the extension with your app.

1. Navigate to the directory where you want to create your extension.

2. Authenticate with Shopify CLI:

3. Create the checkout extension:

4. At the prompt, choose the app for the extension.

5. Select Checkout Extension as the type of extension.

6. Select a template for your extension. You can choose from vanilla JavaScript or React, and whether you want to use TypeScript.

7. Provide a name for your extension using either dash case or snake case.

You should now have a new project directory that includes the extension script at src/index.{fix-extension}

Shopify CLI creates the following directory structure for the extension:

• src/index.{file-extension} contains boilerplate checkout extension code in the language that you specified when you created the extension.

• locales contains JSON-formatted translation strings for checkout localization.

• extension.config.yml contains configurations for the checkout extension, including extension points. Checkout::Dynamic::Render is the extension point for rendering dynamic content in the checkout flow.

The following is an example of the files in the directory:

Now you'll use Shopify CLI to run your extension locally. CLI version 2.2.0 and higher creates a test checkout link when there are products in your development store.

1. Navigate to the folder that contains your extension.

2. Start the app extension server and follow the command prompts.

3. If this is the first time testing your extension, then follow the prompt in the CLI output to log in to your development store.

4. Click on the URL printed at the bottom of the CLI output to view your extension.

• --tunnel: Creates an HTTP tunnel (this is the default behavior).

• --no-tunnel: Skips creating an HTTP tunnel.

• --resourceUrl: A partial link with a product variant ID and quantity to be used to create a test checkout. If the flag isn't passed, then Shopify CLI auto-populates this value. To test with a specific product variant ID and quantity, you can provide the flag as shopify extension serve --resourceUrl="/12345:1", where 12345 is the product variant ID and :1 is the quantity.

In this step, you'll register the checkout extension with your app.

After you've registered your extension to an app, you can push your extension code with Shopify. To publish your extension to Shopify, you need to request network access.

1. Add the network_access Boolean key to your extension configuration file:

2. Push your extension code to Shopify:

This section describes how to solve some potential errors when you run shopify extension serve.

If you receive the error ShopifyCLI:AdminAPI requires the property token to be set, then you'll need to use the --resourceUrl flag to direct the CLI to open a checkout session for you.

If you don't receive the test checkout URL when you run shopify extension serve, 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, run shopify login --store=YOUR-STORE-URL.

Otherwise, you can manually create a checkout with the following steps:

1. From your development store's storefront, add some products to your cart.

2. From the cart, click Checkout.

3. From your extension project's root, start the app extension server:

   You should see similar output to the following:

4. On the checkout page for your store, change the URL by appending the ?dev=https://{ngrok_tunnel_id}.ngrok.io/extensions query string and reload the page.

   You should now see a rendered order note that corresponds to the code in your project template.

   

   TODO: This asset should be updated, the boilerplate extension no longer includes a Order note field, just text that says Welcome to the Checkout::Dynamic::Render extension!. It is shown by default in the cart area, underneath the line items.

• Learn how to add custom banners to checkout.