Fix custom-oclif-loader.ts hydrogen loader strategy for hydrogen-cli local development by andguy95 · Pull Request #6827 · Shopify/cli

andguy95 · 2026-02-05T20:59:14Z

WHY are these changes introduced?

During local development of the @shopify/cli in the Shopify/hydrogen you are no longer able to see your changes when running the npx shopify hydrogen commands because the custom-ocliff-loader.ts no longer loads the local Shopify/hydrgen cli in the Shopify/hydrogen monorepo.

These versions below are good:

3.80.6 ✅
3.80.7 ✅
3.81.0 ✅
3.81.1 ✅
3.81.2 ✅
3.82.0 ✅
3.82.1 ✅
3.83.0 ❌ - Looks like the hydrogen mono repo awareness stopped working here (looks like major bump of OCLIF)

In OCLIF v4, determinePriority is a standalone utility function (not an instance method), so we can't override it to customize command priority in custom-ocliff-loader.ts.

WHAT is this pull request doing?

Change the custom-ocliff-loader.ts to manually replace bundled hydrogen commands with external ones after loading completes if in dev mode.

How to test your changes?

Go to dev.ts in hydrogen/packages/cli/src/commands/hydrogen/dev.ts
Make arbitrary update to the run()
In the cli project run npm run build
In the template/skeleton project run npx shopify hydrogen dev
- To test locally i created an alias shopify-dev pointing to a locally built version of the Shopiy/cli

# Create the following file in ~/bin/shopify:

#!/usr/bin/env node

process.env.SHOPIFY_RUBY_BINDIR = "/opt/rubies/3.1.2/bin"
process.env.SHOPIFY_HOMEBREW_FORMULA = "shopify-cli"

import("/Users/<your-user>/src/github.com/Shopify/cli/packages/cli/bin/run.js")

alias shopify-dev='/Users/$USER/bin/shopify'

Measuring impact

How do we know this change was effective? Please choose one:

n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix

Checklist

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

…l dev

github-actions · 2026-02-05T21:05:56Z

Coverage report

St.^❔	Category	Percentage	Covered / Total
🟡	Statements	78.92%	14522/18402
🟡	Branches	73.45%	7229/9842
🟡	Functions	79.05%	3690/4668
🟡	Lines	79.26%	13727/17319

Test suite run success

3792 tests passing in 1453 suites.

Report generated by 🧪jest coverage report action from 317cf86

EvilGenius13 · 2026-02-05T21:46:37Z

Changes make sense, thank you for the pairing @andguy95. We'll want to make sure @Shopify/app-inner-loop takes a peek as they have historically made the changes to the file.

packages/cli-kit/src/public/node/custom-oclif-loader.ts

packages/cli-kit/src/public/node/custom-oclif-loader.test.ts

kdaviduik

Needs a changeset but other than that LGTM :)

note about this, it seems to be a false alarm as apparently:

customPriority had zero callers anywhere in the codebase
customPriority was already non-functional since oclif v3.83.0
The sole consumer (cli-launcher.ts) already calls config.load() — no caller changes needed

binks-code-reviewer · 2026-02-26T22:28:29Z

🤖 Code Review · #projects-dev-ai for questions
React with 👍/👎 or reply — all feedback helps improve the agent.

✅ Complete - No issues

📋 History

✅ No issues

binks-code-reviewer · 2026-02-26T22:28:29Z

🤖 Code Review · #projects-dev-ai for questions
React with 👍/👎 or reply — all feedback helps improve the agent.

✅ Complete - No issues

📋 History

✅ No issues

packages/cli-kit/src/public/node/custom-oclif-loader.ts

kdaviduik · 2026-02-27T04:58:48Z

.changeset/pretty-swans-smell.md

+'@shopify/cli-kit': patch
+---
+
+Fix hydrogen local dev plugin loader to correctly replace bundled hydrogen commands with external plugin commands by switching to a post-load strategy


blocking: @shopify/cli-kit exports custom-oclif-loader.js as a public entry point. The type diff shows customPriority was removed from the public declaration and load() was added. While customPriority was effectively dead code in oclif v4 (the framework no longer called it), it was part of the public type declaration.

The changeset is marked as patch, which I think is appropriate if there are no external consumers, but I think the changeset body should also mention the customPriority removal for transparency, even if it's dead code - consumers upgrading @shopify/cli-kit should be aware.

packages/cli-kit/src/public/node/custom-oclif-loader.ts

isaacroldan · 2026-02-27T12:46:19Z

packages/cli-kit/src/public/node/custom-oclif-loader.ts

        }
+        // Force OCLIF to ignore manifests so commands are loaded dynamically
+        // to be replaced later
+        options.ignoreManifest = true


This is dangerous change, ignoring the manifest will make the CLI slower at startup on every command, because it needs to discover every command again on each run. Please do a comparison to check how speed is affected with and without this 🙏.

When is this line code executed? will it affect most users or just internal hydrogen development?

@isaacroldan Thank you, this is a good callout. I will test. This ideally should be executed in development mode but only when in the Hydrogen Monorepo.

In this instance we could probably move the hydrogen monorepo check where the isDevelopment check is to ensure this ignoreManifest only runs in the expected context.

Hey @isaacroldan. Here's what I found:

Who is affected?

ignoreManifest only fires inside isDevelopment(), which requires SHOPIFY_CLI_ENV=development. The majority of public facing end users shouldn't be affected. The only people who hit this path are CLI developers
running from source with the SHOPIFY_CLI_ENV set.

The gate fix

Even so, the original code was broader than needed, as it would set ignoreManifest = true for any dev running from source in any directory with a package.json and SHOPIFY_CLI_ENV=development.

I've tightened it so that ignoreManifest is now gated behind useHydrogenMonorepo (the same
/(shopify|hydrogen)\/hydrogen/i path check already used for the npm prefix call). It only fires when you're actually inside the Hydrogen monorepo.

Tests

Either way with and without the gate, there wasn't any noticible perf hit running outside or inside the Hydrogen Monorepo. I used hyperfine to run these tests:

isaacroldan · 2026-02-27T12:50:23Z

Is bringing hydrogen-cli back to this repo a possible alternative to this change? We are doing hacks to support a weird repo structure :/

isaacroldan · 2026-02-27T12:50:53Z

/snapit

github-actions · 2026-02-27T12:53:46Z

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

Test the snapshot by installing your package globally:

npm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20260227125139

Caution

After installing, validate the version by running shopify version 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.

andguy95 · 2026-03-03T21:12:41Z

Is bringing hydrogen-cli back to this repo a possible alternative to this change? We are doing hacks to support a weird repo structure :/

@isaacroldan, there have been some discussions on how we can better manage this strange repo dependencies. We are going to explore patch packages as well as seeing if we can possible change the dependencies of the cli-hydrogen to avoid this hack if possible 🤞

github-actions · 2026-03-03T21:29:16Z

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/custom-oclif-loader.d.ts

@@ -1,6 +1,6 @@
-import { Command, Config } from '@oclif/core';
+import { Config } from '@oclif/core';
 import { Options } from '@oclif/core/interfaces';
 export declare class ShopifyConfig extends Config {
     constructor(options: Options);
-    customPriority(commands: Command.Loadable[]): Command.Loadable | undefined;
+    load(): Promise<void>;
 }
\ No newline at end of file

andguy95 · 2026-03-04T19:04:40Z

/snapit

github-actions · 2026-03-04T19:07:46Z

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

Test the snapshot by installing your package globally:

npm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20260304190535

Caution

After installing, validate the version by running shopify version 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.

itsjustriley

Looks good, all comments seem to be addressed. I know we're looking at better solutions for strange repo dependencies in the future, but I think this is an appropriate solution for now given that this is blocking us.

andguy95 · 2026-03-05T06:11:33Z

@isaacroldan I put up a draft PR in the hydrogen monorepo (Shopify/hydrogen#3531) for a strategy to offload the logic for local hydrogen monorepo development.

This custom oclif loader I believe would become simplified to still maintain that logic for hydrogen backwards compatibility as noted in the comment. (But honestly I would love your opinion to see if we could kill this off all together)

isaacroldan · 2026-03-05T10:48:20Z

Love it, I think it makes the most sense for you to own this and be part of the hydrogen repo itself.

About the backwards compatibility, I think the global CLI has been out for 2 years or more, IMHO it's time to remove that part too and basically stop having a custom oclif loader :)

fix: updates to new oclif v4 plugin loader strategy for hydrogen loca…

9679c32

…l dev

andguy95 requested a review from a team as a code owner February 5, 2026 20:59

This comment has been minimized.

Sign in to view

EvilGenius13 approved these changes Feb 5, 2026

View reviewed changes

fix: variable length lint error

2b31382

kdaviduik reviewed Feb 10, 2026

View reviewed changes

fredericoo mentioned this pull request Feb 10, 2026

feat(ci): add scaffolding tests for npm, pnpm, bun, and yarn Shopify/hydrogen#3458

Merged

4 tasks

andguy95 added 3 commits February 19, 2026 17:13

chore: address comments and adds tests

511a2de

fix: lint errors

5a5fc4b

fix: eslint type error

122dca8

andguy95 commented Feb 19, 2026

View reviewed changes

packages/cli-kit/src/public/node/custom-oclif-loader.ts Outdated Show resolved Hide resolved

andguy95 commented Feb 19, 2026

View reviewed changes

packages/cli-kit/src/public/node/custom-oclif-loader.test.ts Show resolved Hide resolved

andguy95 commented Feb 19, 2026

View reviewed changes

packages/cli-kit/src/public/node/custom-oclif-loader.test.ts Show resolved Hide resolved

andguy95 commented Feb 19, 2026

View reviewed changes

packages/cli-kit/src/public/node/custom-oclif-loader.test.ts Show resolved Hide resolved

andguy95 requested review from EvilGenius13, amcaplan, craigmichaelmartin, fredericoo, gonzaloriestra, itsjustriley and kdaviduik February 19, 2026 23:03

fredericoo changed the title ~~Fix custom-ocliff-loader.ts hydrogen loader strategy for hydrogen-cli local development~~ Fix custom-oclif\-loader.ts hydrogen loader strategy for hydrogen-cli local development Feb 23, 2026

fredericoo changed the title ~~Fix custom-oclif\-loader.ts hydrogen loader strategy for hydrogen-cli local development~~ Fix custom-oclif-loader.ts hydrogen loader strategy for hydrogen-cli local development Feb 23, 2026

kdaviduik reviewed Feb 23, 2026

View reviewed changes

chore: adds a patch changeset for cli-kit

d47821b

andguy95 requested a review from a team as a code owner February 24, 2026 17:11

Merge branch 'main' into an-fix-hydrogen-cli-custom-loader

72d3411

andguy95 requested a review from a team as a code owner February 24, 2026 17:11

Merge branch 'main' into an-fix-hydrogen-cli-custom-loader

72d3411

kdaviduik reviewed Feb 27, 2026

View reviewed changes

isaacroldan reviewed Feb 27, 2026

View reviewed changes

feat: updates change log message and small tweaks to the oclif loader

df2176c

andguy95 requested review from isaacroldan and kdaviduik March 3, 2026 21:10

chore: regenerate graphql types

317cf86

itsjustriley approved these changes Mar 4, 2026

View reviewed changes

andguy95 mentioned this pull request Mar 5, 2026

An feat local cli hydrogen patch Shopify/hydrogen#3531

Draft

5 tasks

Conversation

andguy95 commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

WHAT is this pull request doing?

How to test your changes?

Measuring impact

Checklist

Uh oh!

This comment has been minimized.

github-actions bot commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

Test suite run success

Uh oh!

EvilGenius13 commented Feb 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kdaviduik left a comment

Choose a reason for hiding this comment

Uh oh!

binks-code-reviewer bot commented Feb 26, 2026

Uh oh!

binks-code-reviewer bot commented Feb 26, 2026

Uh oh!

Uh oh!

kdaviduik Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

isaacroldan Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

andguy95 Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

andguy95 Mar 3, 2026

Choose a reason for hiding this comment

Who is affected?

The gate fix

Tests

Uh oh!

isaacroldan commented Feb 27, 2026

Uh oh!

isaacroldan commented Feb 27, 2026

Uh oh!

github-actions bot commented Feb 27, 2026

Uh oh!

andguy95 commented Mar 3, 2026

Uh oh!

github-actions bot commented Mar 3, 2026

Differences in type declarations

New type declarations

Existing type declarations

Uh oh!

andguy95 commented Mar 4, 2026

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

itsjustriley left a comment

Choose a reason for hiding this comment

Uh oh!

andguy95 commented Mar 5, 2026

Uh oh!

isaacroldan commented Mar 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

andguy95 commented Feb 5, 2026 •

edited

Loading

github-actions bot commented Feb 5, 2026 •

edited

Loading