Refactor: rename .env to .demo.env to align with .dev.env

.env.example → .demo.env.example

@@ -1,11 +1,11 @@
 # Checkout Kit sample storefront configuration.
-# Copy this file to .env, fill in local values, then run dev up or:
+# Copy this file to .demo.env, fill in local values, then run dev up or:
 # scripts/setup_storefront_env
 # Direct interactive setup prompts for optional Apple Pay and Customer Account
 # API values by default. dev up uses non-interactive setup, so missing optional
 # values can stay blank.
 #
-# Do not commit real values from .env or generated platform config files.
+# Do not commit real values from .demo.env or generated platform config files.
 
 # Storefront details
 STOREFRONT_DOMAIN=your-store.myshopify.com

.github/CONTRIBUTING.md

@@ -55,7 +55,7 @@ Android, React Native, or Web setup failure is visible without hiding later
 platform results. If a setup step fails, fix it and rerun `dev up`.
 
 Setup creates or syncs sample app storefront configuration from the repo-root
-`.env`. If `.env` is missing, setup prompts for required storefront values and
+`.demo.env`. If `.demo.env` is missing, setup prompts for required storefront values and
 then generates the Android, Swift, and React Native sample config files.
 Optional Apple Pay and Customer Account API values are preserved if already set,
 but `dev up` leaves missing optional values blank instead of prompting.
@@ -66,9 +66,9 @@ React Native sample apps can be run against local in-repo SDK sources with
 `dev rn ios --local` or `dev rn android --local`. The Web sample accepts a
 checkout URL directly and does not use the shared storefront credential files.
 
-Sample app storefront configuration is generated from the repo-root `.env`.
+Sample app storefront configuration is generated from the repo-root `.demo.env`.
 Shopify employees get this through `dev up`. External contributors can copy
-`.env.example` to `.env`, fill in local storefront values, then run
+`.demo.env.example` to `.demo.env`, fill in local storefront values, then run
 `scripts/setup_storefront_env` from the repo root.
 
 ---

.gitignore

@@ -45,6 +45,9 @@ captures/
 local.properties
 .env
 
+# Demo apps' storefront configuration (see .demo.env.example)
+.demo.env
+
 # Local developer tooling preferences (see .dev.env.example)
 .dev.env
 upload-keystore.jks

AGENTS.md

@@ -95,7 +95,7 @@ USE_LOCAL_SDK=1 ./gradlew :shopify_checkout-kit-react-native:testDebugUnitTest
 ## Sensitive configuration
 
 Treat storefront environment and generated sample app configuration values as
-sensitive. Never print, commit, paste, or document real values from `.env`,
+sensitive. Never print, commit, paste, or document real values from `.demo.env`,
 generated platform config, access tokens, merchant identifiers, shop IDs,
 account IDs. Use synthetic placeholders for docs and
 verification.

dev.yml

@@ -23,6 +23,13 @@ up:
         - protocol
         - platforms/react-native
         - platforms/web
+  # TODO(remove after 2026-06-19): one-off migration of the repo-root storefront
+  # config from .env to .demo.env. Delete this step and scripts/migrate_demo_env
+  # once developers have run `dev up` at least once.
+  - custom:
+      name: Migrate .env to .demo.env
+      met?: ./scripts/migrate_demo_env --check
+      meet: ./scripts/migrate_demo_env
   - custom:
       name: Run Checkout Kit workspace setup
       met?: ./scripts/setup_dev_workspace --check --skip-optional-prompts

platforms/android/samples/CheckoutKitAndroidDemo/README.md

@@ -73,7 +73,7 @@ Do not edit files in `app/build/generated/source/apollo/` by hand. Update `.grap
    dev up
    ```
 
-   If you are not using `dev`, copy the repo-root `.env.example` to `.env`,
+   If you are not using `dev`, copy the repo-root `.demo.env.example` to `.demo.env`,
    fill in local values, then run:
 
    ```bash
@@ -96,7 +96,7 @@ Open the project in Android Studio, sync Gradle, then build and run.
 
 ## Updating the Storefront API version
 
-1. Update `API_VERSION` in the repo-root `.env`.
+1. Update `API_VERSION` in the repo-root `.demo.env`.
 2. Sync the generated platform config:
 
    ```sh
@@ -139,7 +139,7 @@ Open the project in Android Studio, sync Gradle, then build and run.
 
 | File | Purpose |
 | --- | --- |
-| `.env` | Generated sample config from the repo-root `.env` (not checked into git). |
+| `.env` | Generated sample config from the repo-root `.demo.env` (not checked into git). |
 | `app/build.gradle` | Apollo plugin configuration and `BuildConfig` values from `.env`. |
 | `app/src/main/graphql/schema.graphqls` | Storefront API schema. |
 | `common/client/StorefrontApiClient.kt` | Apollo client setup and Storefront API auth header. |

platforms/android/samples/README.md

@@ -2,7 +2,7 @@
 
 This directory contains Android sample apps for Checkout Kit.
 
-Sample app storefront configuration is generated from the repo-root `.env`.
+Sample app storefront configuration is generated from the repo-root `.demo.env`.
 Run `dev up` from the repo root or any platform directory to provision the repo
 and create or sync the generated sample config files.
 
@@ -18,7 +18,7 @@ From the repo root or this platform directory:
 dev up
 ```
 
-If you are not using `dev`, copy the repo-root `.env.example` to `.env`, fill
+If you are not using `dev`, copy the repo-root `.demo.env.example` to `.demo.env`, fill
 in local values, then run:
 
 ```sh

platforms/react-native/CONTRIBUTING.md

@@ -193,9 +193,9 @@ pnpm module build
 ### Update sample configuration
 
 From the repo root or this platform directory, run `dev up` to create or sync
-the sample app dotenv file from the root `.env`.
+the sample app dotenv file from the root `.demo.env`.
 
-If you are not using `dev`, copy `.env.example` from the repo root to `.env`,
+If you are not using `dev`, copy `.demo.env.example` from the repo root to `.demo.env`,
 fill in local values, then run `scripts/setup_storefront_env`.
 
 ```

platforms/react-native/scripts/publish_checks/support/package_manager.rb

@@ -41,9 +41,7 @@ def version
     end
 
     def resolved_binary
-      Shell.capture('command', '-v', binary).strip
-    rescue StandardError
-      binary
+      Shell.which(binary) || binary
     end
 
     def write_config(app_dir)

platforms/swift/Samples/CheckoutKitSwiftDemo/README.md

@@ -70,7 +70,7 @@ Do not edit files in `Generated/` by hand. Update `.graphql` files and regenerat
    dev up
    ```
 
-   If you are not using `dev`, copy the repo-root `.env.example` to `.env`,
+   If you are not using `dev`, copy the repo-root `.demo.env.example` to `.demo.env`,
    fill in local values, then run:
 
    ```bash
@@ -92,7 +92,7 @@ Open the project in Xcode, let Swift Package Manager resolve dependencies, then
 
 ## Updating the Storefront API version
 
-1. Update `API_VERSION` in the repo-root `.env`.
+1. Update `API_VERSION` in the repo-root `.demo.env`.
 2. Sync the generated platform config:
 
    ```sh
@@ -144,7 +144,7 @@ All commands are run from the **repo root** (`checkout-kit/`):
 
 | File | Purpose |
 | --- | --- |
-| `Storefront.xcconfig` | Generated sample config from the repo-root `.env` (not checked into git). |
+| `Storefront.xcconfig` | Generated sample config from the repo-root `.demo.env` (not checked into git). |
 | `schema.<version>.graphqls` | Storefront API schema downloaded with the Apollo iOS CLI. |
 | `apollo-codegen-config.json` | Apollo code generation configuration. |
 | `CheckoutKitSwiftDemo/Sources/Api/Network.swift` | Apollo client setup and authentication interceptor. |

platforms/swift/Samples/README.md

@@ -29,7 +29,7 @@ them from the shared `.env`.
    dev up
    ```
 
-2. If you are not using `dev`, copy the repo-root `.env.example` to `.env`,
+2. If you are not using `dev`, copy the repo-root `.demo.env.example` to `.demo.env`,
 fill in local values, then run `scripts/setup_storefront_env`.
 
 The setup script generates `platforms/swift/Samples/CheckoutKitSwiftDemo/Storefront.xcconfig`.
@@ -52,7 +52,7 @@ To get started:
    dev up
    ```
 
-2. If you are not using `dev`, copy the repo-root `.env.example` to `.env`,
+2. If you are not using `dev`, copy the repo-root `.demo.env.example` to `.demo.env`,
 fill in local values, then run `scripts/setup_storefront_env`.
 
 The setup script generates `platforms/swift/Samples/ShopifyAcceleratedCheckoutsApp/Storefront.xcconfig`.
@@ -69,5 +69,5 @@ Open the build log and check the script output.
 | Build log output | Cause | Fix |
 | --- | --- | --- |
 | `grep: Storefront.xcconfig: No such file or directory` | `Storefront.xcconfig` file is missing. | Run `dev up` from the repo root or any platform directory. |
-| `Error: STOREFRONT_DOMAIN is not set in Storefront.xcconfig` | `Storefront.xcconfig` exists but `STOREFRONT_DOMAIN` is blank. | Update root `.env`, then run `dev up`. |
-| Associated domains not working at runtime | Domain value is incorrect. | Update root `.env`, then run `dev up`. |
+| `Error: STOREFRONT_DOMAIN is not set in Storefront.xcconfig` | `Storefront.xcconfig` exists but `STOREFRONT_DOMAIN` is blank. | Update root `.demo.env`, then run `dev up`. |
+| Associated domains not working at runtime | Domain value is incorrect. | Update root `.demo.env`, then run `dev up`. |

scripts/lib/checkout_kit/cli/shell.rb

@@ -89,7 +89,25 @@ def capture(*command, chdir: nil, env: {})
       end
 
       def command?(binary)
-        system('command', '-v', binary.to_s, out: File::NULL, err: File::NULL)
+        !which(binary).nil?
+      end
+
+      def which(binary)
+        binary = binary.to_s
+        return nil if binary.empty?
+
+        if binary.include?(File::SEPARATOR) || (File::ALT_SEPARATOR && binary.include?(File::ALT_SEPARATOR))
+          return File.expand_path(binary) if File.file?(binary) && File.executable?(binary)
+
+          return nil
+        end
+
+        ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |dir|
+          candidate = File.join(dir.empty? ? '.' : dir, binary)
+          return candidate if File.file?(candidate) && File.executable?(candidate)
+        end
+
+        nil
       end
 
       def require_command!(binary, message = nil)

scripts/migrate_demo_env

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# TODO(remove after 2026-06-19): temporary one-off migration.
+#
+# The repo-root storefront configuration moved from `.env` to `.demo.env`.
+# This copies an existing `.env` to `.demo.env` once, so developers with a
+# pre-existing local `.env` keep working without re-running setup.
+#
+# It is idempotent: it does nothing once `.demo.env` exists (or if there is no
+# `.env` to migrate). Once everyone has run `dev up` at least once, delete this
+# script and its `up:` step in dev.yml.
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OLD_ENV="$ROOT_DIR/.env"
+NEW_ENV="$ROOT_DIR/.demo.env"
+
+needs_migration() {
+  [[ -f "$OLD_ENV" && ! -f "$NEW_ENV" ]]
+}
+
+# `--check` is the dev `met?` probe: succeed (exit 0) when no work is needed.
+if [[ "${1:-}" == "--check" ]]; then
+  if needs_migration; then
+    exit 1
+  fi
+  exit 0
+fi
+
+if needs_migration; then
+  cp "$OLD_ENV" "$NEW_ENV"
+  echo "Migrated repo-root .env -> .demo.env (your existing .env was left untouched)."
+fi
+
+exit 0

scripts/setup_storefront_env

@@ -4,7 +4,7 @@ set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
-ROOT_ENV="${ROOT_DIR}/.env"
+ROOT_ENV="${ROOT_DIR}/.demo.env"
 ANDROID_ENV="${ROOT_DIR}/platforms/android/samples/CheckoutKitAndroidDemo/.env"
 SWIFT_DEMO_XCCONFIG="${ROOT_DIR}/platforms/swift/Samples/CheckoutKitSwiftDemo/Storefront.xcconfig"
 SWIFT_ACCELERATED_XCCONFIG="${ROOT_DIR}/platforms/swift/Samples/ShopifyAcceleratedCheckoutsApp/Storefront.xcconfig"
@@ -17,7 +17,7 @@ usage() {
   cat <<EOF
 Usage: scripts/setup_storefront_env [--check] [--skip-optional-prompts|--prompt-optional]
 
-Creates or checks sample app storefront configuration from the repo-root .env.
+Creates or checks sample app storefront configuration from the repo-root .demo.env.
 This command prints file paths and status only; it never prints configured values.
 
 By default, interactive setup prompts for missing optional Apple Pay and Customer
@@ -528,16 +528,16 @@ EOF
 
 generate_platform_env_header() {
   cat <<EOF
-# Generated from repo-root .env by scripts/setup_storefront_env.
-# Do not edit directly; update .env and rerun scripts/setup_storefront_env.
+# Generated from repo-root .demo.env by scripts/setup_storefront_env.
+# Do not edit directly; update .demo.env and rerun scripts/setup_storefront_env.
 
 EOF
 }
 
 generate_xcconfig_header() {
   cat <<EOF
-// Generated from repo-root .env by scripts/setup_storefront_env.
-// Do not edit directly; update .env and rerun scripts/setup_storefront_env.
+// Generated from repo-root .demo.env by scripts/setup_storefront_env.
+// Do not edit directly; update .demo.env and rerun scripts/setup_storefront_env.
 
 EOF
 }
@@ -644,23 +644,23 @@ ensure_root_env() {
 
   if [[ "$mode" == "check" ]]; then
     if [[ ! -f "$ROOT_ENV" ]]; then
-      echo "Missing storefront configuration: .env" >&2
+      echo "Missing storefront configuration: .demo.env" >&2
       exit 1
     fi
 
     if is_missing_required_value "$(read_env_value STOREFRONT_DOMAIN "$ROOT_ENV")" ||
       is_missing_required_value "$(read_env_value STOREFRONT_ACCESS_TOKEN "$ROOT_ENV")"; then
-      echo "Root .env is missing required storefront configuration." >&2
+      echo "Root .demo.env is missing required storefront configuration." >&2
       exit 1
     fi
 
     if ! root_has_canonical_keys; then
-      echo "Root .env is missing canonical storefront configuration keys." >&2
+      echo "Root .demo.env is missing canonical storefront configuration keys." >&2
       exit 1
     fi
 
     if customer_account_api_version_needs_default; then
-      echo "Root .env has a blank Customer Account API version." >&2
+      echo "Root .demo.env has a blank Customer Account API version." >&2
       exit 1
     fi
 
@@ -670,27 +670,27 @@ ensure_root_env() {
   local root_needs_write="false"
   if [[ ! -f "$ROOT_ENV" ]]; then
     root_needs_write="true"
-    echo "Creating root storefront configuration at .env."
+    echo "Creating root storefront configuration at .demo.env."
   elif is_missing_required_value "$(read_env_value STOREFRONT_DOMAIN "$ROOT_ENV")" ||
     is_missing_required_value "$(read_env_value STOREFRONT_ACCESS_TOKEN "$ROOT_ENV")"; then
     root_needs_write="true"
-    echo "Updating root storefront configuration at .env."
+    echo "Updating root storefront configuration at .demo.env."
   elif ! root_has_canonical_keys; then
     root_needs_write="true"
-    echo "Normalizing root storefront configuration at .env."
+    echo "Normalizing root storefront configuration at .demo.env."
   elif customer_account_api_version_needs_default; then
     root_needs_write="true"
-    echo "Normalizing root storefront configuration at .env."
+    echo "Normalizing root storefront configuration at .demo.env."
   fi
 
   if [[ "$root_needs_write" == "true" ]]; then
     collect_missing_values
     generate_root_env >"$ROOT_ENV"
   elif fill_optional_values_from_environment; then
-    echo "Updating optional storefront configuration at .env."
+    echo "Updating optional storefront configuration at .demo.env."
     generate_root_env >"$ROOT_ENV"
   elif optional_values_need_prompt; then
-    echo "Updating optional storefront configuration at .env."
+    echo "Updating optional storefront configuration at .demo.env."
     collect_missing_values
     generate_root_env >"$ROOT_ENV"
   fi