Add default environment functionality to theme commands #5931

graygilmore · 2025-06-02T18:40:35Z

WHY are these changes introduced?

Closes [Feature]: Theme command to load the default environment #4692

Allows developers to set a default environment in their environments config file:

[environments.default]
store = "abc.myshopify.com"

This environment will automatically be used for CLI commands even if the developer does not specify the environment with the --environment flag. This gives developers a bit of a safety net when running commands and switching between different storefronts because this default environment will take precedence over any storefront saved to local storage.

How to test your changes?

Install the snapped version:

npm i -g @shopify/[email protected] --@shopify:registry=https://registry.npmjs.org

Navigate to a theme folder
Create a shopify.theme.toml file if one doesn't already exist and populate it with at least a [environments.default] entry that has a store entry
Run a theme command like shopify theme dev
Ensure that it is using the default environment's store
Run the command again but specify a store shopify theme dev --store different-store.myshopify.com
Ensure that it's using the flag you passed in instead of the default store
Add a separate entry to the shopify.theme.toml file
Run the command again but specify your other environment shopify theme dev -e new
Ensure that it's using the new environment's store instead of the default

Post-release steps

Once this is approved and merged we'll want to update the docs: https://shopify.dev/docs/storefronts/themes/tools/cli/environments#configure-environments

Checklist

I've considered possible cross-platform impacts (Mac, Linux, Windows)
I've considered possible documentation changes

github-actions · 2025-06-02T18:45:57Z

Coverage report

St.^❔	Category	Percentage	Covered / Total
🟡	Statements	78.17% (+0.02% 🔼)	12481/15967
🟡	Branches	72.37% (+0.08% 🔼)	6072/8390
🟡	Functions	78.38% (+0.01% 🔼)	3263/4163
🟡	Lines	78.6% (+0.03% 🔼)	11810/15026

Test suite run success

2878 tests passing in 1253 suites.

Report generated by 🧪jest coverage report action from 4139e95

graygilmore · 2025-06-02T20:22:24Z

/snapit

github-actions · 2025-06-02T20:25:36Z

🫰✨ Thanks @graygilmore! Your snapshot has been published to npm.

Test the snapshot by installing your package globally:

pnpm i -g @shopify/[email protected]

Tip

If you get an ETARGET error, install it with NPM and the flag --@shopify:registry=https://registry.npmjs.org

Caution

After installing, validate the version by running just shopify in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

graygilmore · 2025-06-03T00:01:46Z

/snapit

github-actions · 2025-06-03T00:04:31Z

🫰✨ Thanks @graygilmore! Your snapshot has been published to npm.

Test the snapshot by installing your package globally:

pnpm i -g @shopify/[email protected]

Tip

If you get an ETARGET error, install it with NPM and the flag --@shopify:registry=https://registry.npmjs.org

Caution

After installing, validate the version by running just shopify in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

graygilmore · 2025-06-03T16:50:45Z

/snapit

github-actions · 2025-06-03T16:53:30Z

🫰✨ Thanks @graygilmore! Your snapshot has been published to npm.

Test the snapshot by installing your package globally:

pnpm i -g @shopify/[email protected]

Tip

If you get an ETARGET error, install it with NPM and the flag --@shopify:registry=https://registry.npmjs.org

Caution

After installing, validate the version by running just shopify in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

graygilmore · 2025-06-03T17:22:12Z

packages/cli-kit/src/public/node/base-command.ts

The conditionals got a little out of hand in this file but it's a bit of a complicated thing to check for. Let me know if any of this is too complicated to read through and I can think about rearranging things.

Pushed up a commit to help with this fbdb994

jamesmengo

I do think the code in base-command would benefit from another pass for readability, but my tophat went well!

Aside from that, I wanted to raise the edge case where a user may have created an environment called 'default', which is no longer actually used in their workflow or should only be used when specified.

Not too worried about functional impact, since we output information to the user about the environment being used.

I wonder if that's worth making this a minor change though 🤔

EvilGenius13 · 2025-06-04T14:18:46Z

I do think the code in base-command would benefit from another pass for readability, but my tophat went well!

Aside from that, I wanted to raise the edge case where a user may have created an environment called 'default', which is no longer actually used in their workflow or should only be used when specified.

Not too worried about functional impact, since we output information to the user about the environment being used.

I wonder if that's worth making this a minor change though 🤔

🎩 went great here too. Chiming in that I agree making it a minor change would be nice.

graygilmore · 2025-06-04T22:14:23Z

Force Push Patch Notes

Rebased with main

jamesmengo · 2025-06-05T02:35:53Z

packages/cli-kit/src/public/node/base-command.ts

+    if (!environmentFileExists && !environmentSpecified) return originalResult
+
+    // Noop if multiple environments were specified (let commands handle this)
+    if (environmentSpecified && environments.length > 1) return originalResult


Could we skip the check for environmentSpecified?

jamesmengo

Ty for the changes! If the platform team is ok with the implications of this change I'm 100% on board!

Bikeshed warning: I wonder if we can also provide a way to specify a custom 'default' name but that would likely be out of the scope of this

graygilmore · 2025-06-06T20:43:00Z

Force Push Patch Notes

Rebased with main

gonzaloriestra

Code LGTM. Is the documentation ready?

.changeset/bright-vans-rule.md

graygilmore · 2025-06-09T17:43:25Z

Is the documentation ready?

Was waiting on approval on approach here first. I'll fire that up now and address the feedback on this PR, too.

You may now optionally define a default environment in your environment config file (e.g. `shopify.theme.toml`) that will be automatically injected into the running command without needing to specify it.

github-actions · 2025-06-09T17:58:52Z

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

Some seemingly private modules might be re-exported through public modules.
If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/public/node/base-command.d.ts

@@ -20,6 +20,11 @@ declare abstract class BaseCommand extends Command {
     protected environmentsFilename(): string | undefined;
     protected failMissingNonTTYFlags(flags: FlagOutput, requiredFlags: string[]): void;
     private resultWithEnvironment;
+    /**
+     * Tries to load an environment to forward to the command. If no environment
+     * is specified it will try to load a default environment.
+     */
+    private loadEnvironmentForCommand;
 }
 export declare function addFromParsedFlags(flags: {
     path?: string;

packages/cli-kit/dist/public/node/environments.d.ts

@@ -11,4 +11,5 @@ interface LoadEnvironmentOptions {
  * @returns The loaded environments.
  */
 export declare function loadEnvironment(environmentName: string, fileName: string, options?: LoadEnvironmentOptions): Promise<JsonMap | undefined>;
+export declare function environmentFilePath(fileName: string, options?: LoadEnvironmentOptions): Promise<string | undefined>;
 export {};
\ No newline at end of file

graygilmore force-pushed the gg-default-environment branch 2 times, most recently from 6951290 to 879bacc Compare June 2, 2025 19:01

graygilmore force-pushed the gg-default-environment branch from 879bacc to 782dbc6 Compare June 2, 2025 23:48

graygilmore force-pushed the gg-default-environment branch from e771005 to 782dbc6 Compare June 3, 2025 16:43

graygilmore commented Jun 3, 2025

View reviewed changes

graygilmore marked this pull request as ready for review June 3, 2025 17:22

graygilmore requested review from a team as code owners June 3, 2025 17:22

jamesmengo approved these changes Jun 3, 2025

View reviewed changes

EvilGenius13 approved these changes Jun 4, 2025

View reviewed changes

graygilmore force-pushed the gg-default-environment branch from 782dbc6 to 60c1b9d Compare June 4, 2025 22:14

graygilmore requested review from EvilGenius13 and jamesmengo June 4, 2025 23:02

jamesmengo reviewed Jun 5, 2025

View reviewed changes

jamesmengo approved these changes Jun 5, 2025

View reviewed changes

graygilmore force-pushed the gg-default-environment branch from fbdb994 to 9b889ac Compare June 6, 2025 20:42

EvilGenius13 approved these changes Jun 9, 2025

View reviewed changes

gonzaloriestra approved these changes Jun 9, 2025

View reviewed changes

.changeset/bright-vans-rule.md Outdated Show resolved Hide resolved

.changeset/bright-vans-rule.md Outdated Show resolved Hide resolved

gonzaloriestra force-pushed the gg-default-environment branch from 9b889ac to 18f9aa2 Compare June 9, 2025 17:42

graygilmore added 3 commits June 9, 2025 10:57

Add default environment functionality

c39ba5e

You may now optionally define a default environment in your environment config file (e.g. `shopify.theme.toml`) that will be automatically injected into the running command without needing to specify it.

Fix missing path flag in loadEnvironment calls

f194fd1

Improve readability of default environment logic

4139e95

graygilmore force-pushed the gg-default-environment branch from 18f9aa2 to 4139e95 Compare June 9, 2025 17:57

graygilmore enabled auto-merge June 9, 2025 18:06

gonzaloriestra disabled auto-merge June 10, 2025 07:23

gonzaloriestra merged commit 190e2b9 into main Jun 10, 2025
30 checks passed

gonzaloriestra deleted the gg-default-environment branch June 10, 2025 07:23

Add default environment functionality to theme commands #5931

Add default environment functionality to theme commands #5931

Conversation

graygilmore commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

How to test your changes?

Post-release steps

Checklist

Uh oh!

github-actions bot commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

Test suite run success

Uh oh!

graygilmore commented Jun 2, 2025

Uh oh!

github-actions bot commented Jun 2, 2025

Uh oh!

graygilmore commented Jun 3, 2025

Uh oh!

github-actions bot commented Jun 3, 2025

Uh oh!

graygilmore commented Jun 3, 2025

Uh oh!

github-actions bot commented Jun 3, 2025

Uh oh!

graygilmore Jun 3, 2025

Choose a reason for hiding this comment

Uh oh!

graygilmore Jun 4, 2025

Choose a reason for hiding this comment

Uh oh!

jamesmengo left a comment

Choose a reason for hiding this comment

Uh oh!

EvilGenius13 commented Jun 4, 2025

Uh oh!

graygilmore commented Jun 4, 2025

Force Push Patch Notes

Uh oh!

jamesmengo Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

jamesmengo left a comment

Choose a reason for hiding this comment

Uh oh!

graygilmore commented Jun 6, 2025

Force Push Patch Notes

Uh oh!

gonzaloriestra left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

graygilmore commented Jun 9, 2025

Uh oh!

github-actions bot commented Jun 9, 2025

Differences in type declarations

New type declarations

Existing type declarations

Uh oh!

Uh oh!

Uh oh!

graygilmore commented Jun 2, 2025 •

edited

Loading

github-actions bot commented Jun 2, 2025 •

edited

Loading