How to use environment variables in Checkout UI Extension apps

How to use environment variables in Checkout UI Extension apps

Shopify Partner
6 0 2
Hi there,

I'm trying to find a better way for my team to update the version while deploying my Checkout UI extension app.

I created a small deploy script for this that does a version number prompt. First of all, it turns out that you cannot use numbers with dots (e.g. 1.2.1).

Secondly, I don't really understand where we can use the Environment Variables, as described after each command in this documentation. For the --version flag this should be SHOPIFY_FLAG_VERSION, but as soon as I add it to my .env file it is not used.

I also don't see a command to push my .env or something like that, only to show or pull.

My question now is what exactly are those environment variables used for?

Replies 9 (9)

Shopify Partner
234 9 103

We also have this question, because we need to make network calls from the Checkout UI Extension to our API as part of the checkout customization.

Without the ability to define an environment variable, we're not able to define a different URL for each of these environments (development, staging vs production).

Otherwise we're relying on hardcoded strings to pass the API URL, which is very dangerous and error prone to be checked into version control.

The closest documented option seems to be the Checkout Settings API, but that's configurable by merchants. Env variables are supposed to be used by developers internally, but I'm not seeing a way to define variables for use within the UI Extension itself.

Founder of Real ID - Verify your customer's real IDs easily & securely with modern A.I.

Want to see it in action? Check out our demo store.

Shopify Partner
14 1 6

So I ended up using the Shop's Metafield to handle it. I don't like using the Settings as merchant would need to configure it themselves on the Checkout editor. There's a huge chance that it'll be wrongly set.

Here's a blog post I made for this:

Shopify Partner
13 1 1

In case it helps, I landed at a solution that I think I like better than metafields for now. Obviously Shopify supporting this would be ideal / feels like table stakes, but as a workaround I think I like this better than using metafields and writing app code for this.


Where I landed was to use `envsubst` with a template file. The template file gets committed while the runtime file does not as it's generated. I pair this with a script that I can run as needed in CI and whatnot (or before `deploy`) for example. My `dev` script now looks like

"API_URL=http://localhost:4000 npm run env:setup && shopify app dev"



where `env:setup` invokes the script "./scripts/"


which runs

#!/usr/bin/env bash

if [ -z "${API_URL}" ]; then
echo -e "\033[0;31mMust set API_URL environment variable"
exit 1

envsubst < "$template" > extensions/<your-extension>/src/config.ts

echo -e "\033[0;32mWrote $API_URL as API_URL from $template to $config"


Hope this helps others! Bummer it's not supported 😕


Shopify Partner
1 0 2


I was also struggling with this issue, but I realized that we can reference environment variables as shown below.


Execute the following:


YOUR_ENV=abc yarn shopify app dev # or deploy



Then, within the TypeScript file of the extension, you can reference it as follows:


console.log(process.env.YOUR_ENV) // outputs abc



However, for reasons I don't fully understand, it seems that a reference error occurs when doing hot reloading in the development environment.

Therefore, checking with process.env.NODE_ENV === 'development' and only executing it when not in local development might be advisable.


FYI, In the examples of Shopify's GitHub Actions, it is also mentioned that env is available for use.


I hope this will be helpful.

Shopify Partner
2 0 0

Does this work in "production" mode though? I am getting some errors: process is undefiend. When running `npm run dev`, this option works.

Shopify Partner
11 0 4

No this will not work in production as the block does not have access to the apps environment variables. It's run on Shopify infrastructure.

This is a bummer when trying to manage development, staging and production environments!

Shopify Partner
13 1 1

The solution I propose above will work in production as you're writing to a typescript file that you depend on at runtime, not environment variables

Shopify Partner
13 1 1

Apologies, I can't seem to edit my post, but just in case you'd like to see it, I did a little write up

Shopify Partner
1 0 1

Yes, this should work in production. If you are using multiple configurations (e.g. for staging and production, etc), check that you have a respective .env file configured for each (after switching what config you are using the config commands) and that you have added your custom values to it. Once you add them to each, it should work.


For example, if you have a staging config like then your env file name might look like .env.appname-staging after running the env pull command.

shopify app env pull


Hope this helps anyone else who is seeing the process undefined errors in the browser console.