feat: add support for catalogs with dlx by Netail · Pull Request #10434 · pnpm/pnpm

Netail · 2026-01-09T15:37:20Z

Add support for the catalog: protocol when using pnpm dlx or pnpx

Closes # #10249

Netail · 2026-01-09T16:11:13Z

  const resolvedPkgs = await Promise.all(pkgs.map(async (pkg) => {
    const { alias, bareSpecifier } = parseWantedDependency(pkg) || {}
    if (alias == null) return pkg
+    const resolvedBareSpecifier = resolveCatalogProtocol(catalogResolver, alias, bareSpecifier ?? '')


Not sure if we should default this to an empty string; catalogResolver does not support undefined, but parseWantedDependency returns string or undefined

It sounds like we only want to call resolveCatalogProtocol if bareSpecifier != null based on your explanation. Something like this should be more correct and less hacky than passing in an empty string?

Suggested change

const resolvedBareSpecifier = resolveCatalogProtocol(catalogResolver, alias, bareSpecifier ?? '')

const resolvedBareSpecifier = bareSpecifier != null

? resolveCatalogProtocol(catalogResolver, alias, bareSpecifier)

: bareSpecifier

Copilot

Pull request overview

This pull request adds support for the catalog: protocol when using pnpm dlx or pnpx, allowing users to reference catalog-defined versions when executing packages temporarily.

Key changes:

Integration of catalog resolver into the dlx command handler
Addition of retry and timeout configuration to the resolver
New test case validating catalog protocol resolution with dlx

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pnpm-lock.yaml	Adds @pnpm/catalogs.resolver dependency to plugin-commands-script-runners
exec/plugin-commands-script-runners/package.json	Declares @pnpm/catalogs.resolver as a workspace dependency
exec/plugin-commands-script-runners/tsconfig.json	Adds TypeScript project reference to catalogs/resolver
exec/plugin-commands-script-runners/src/dlx.ts	Implements catalog resolution by creating a catalogResolver and resolveCatalogProtocol helper function; also adds retry/timeout options to createResolver
exec/plugin-commands-script-runners/test/dlx.e2e.ts	Adds test case verifying catalog protocol works with dlx command
CONTRIBUTING.md	Minor improvement: adds shell syntax highlighting to code block
.changeset/curly-dryers-jam.md	Documents the new feature in the changeset

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-09T16:15:02Z

+test('dlx with catalog', async () => {
+  prepareEmpty()
+
+  await dlx.handler({
+    ...DEFAULT_OPTS,
+    dir: path.resolve('project'),
+    storeDir: path.resolve('store'),
+    cacheDir: path.resolve('cache'),
+    dlxCacheMaxAge: Infinity,
+    catalogs: {
+      default: {
+        shx: '^0.3.4',
+      },
+    },
+  }, ['shx@catalog:'])
+
+  verifyDlxCache(createCacheKey('shx@0.3.4'))
+})


The test covers the happy path for catalog resolution, but doesn't include tests for error cases such as:

Catalog entry not found (e.g., 'shx@catalog:' when shx is not in the default catalog)

Named catalog not found (e.g., 'shx@catalog:nonexistent')

Invalid catalog configuration (recursive catalog reference, workspace protocol, etc.)

These error conditions are handled in the resolveCatalogProtocol function and should be tested to ensure proper error messages are displayed to users when they misconfigure catalogs with dlx.

gluxon · 2026-01-13T18:10:25Z

I'll take a look at this and review. Thanks!

gluxon · 2026-01-25T20:17:06Z

  const resolvedPkgs = await Promise.all(pkgs.map(async (pkg) => {
    const { alias, bareSpecifier } = parseWantedDependency(pkg) || {}
    if (alias == null) return pkg
+    const resolvedBareSpecifier = resolveCatalogProtocol(catalogResolver, alias, bareSpecifier ?? '')


It sounds like we only want to call resolveCatalogProtocol if bareSpecifier != null based on your explanation. Something like this should be more correct and less hacky than passing in an empty string?

Suggested change

const resolvedBareSpecifier = resolveCatalogProtocol(catalogResolver, alias, bareSpecifier ?? '')

const resolvedBareSpecifier = bareSpecifier != null

? resolveCatalogProtocol(catalogResolver, alias, bareSpecifier)

: bareSpecifier

gluxon

Thanks for the updates!

Co-authored-by: Brandon Cheng <gluxon@users.noreply.github.com>

welcome · 2026-01-26T06:06:38Z

Congrats on merging your first pull request! 🎉🎉🎉

* feat: add support for catalogs with dlx * fix: feedback * Update .changeset/curly-dryers-jam.md Co-authored-by: Brandon Cheng <gluxon@users.noreply.github.com> * Update .changeset/curly-dryers-jam.md Close #10249 Co-authored-by: Brandon Cheng <gluxon@users.noreply.github.com> --------- Co-authored-by: Brandon Cheng <gluxon@users.noreply.github.com>

Netail · 2026-02-11T12:21:29Z

@gluxon @zkochan Mhm okay, I don't think it works as expected yet.

We seem to be getting a ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_SPEC, while pnpm config list does show the dependency listed. Perhaps the catalogs are not fetched from the workspace file when using dlx?
I thought it did, as some other stuff is read from the workspace file

gluxon · 2026-02-12T19:39:29Z

It looks like dlx has a special case when reading pnpm's config. I suspect that behavior is likely for performance.

pnpm/pnpm/src/main.ts

Line 115 in 4110a4e

ignoreNonAuthSettingsFromLocal: isDlxOrCreateCommand,

Here's the instructions for testing locally. When you have a fix up, it should be possible to check whether your fix works by running pd dlx.

https://github.com/pnpm/pnpm/blob/main/CONTRIBUTING.md#setting-up-the-environment

I generally recommend testing locally every PR you open before asking for a review. 🙂

Netail · 2026-02-12T23:41:18Z

It looks like dlx has a special case when reading pnpm's config. I suspect that behavior is likely for performance.

pnpm/pnpm/src/main.ts

Line 115 in 4110a4e

ignoreNonAuthSettingsFromLocal: isDlxOrCreateCommand,

Here's the instructions for testing locally. When you have a fix up, it should be possible to check whether your fix works by running pd dlx.

https://github.com/pnpm/pnpm/blob/main/CONTRIBUTING.md#setting-up-the-environment

I generally recommend testing locally every PR you open before asking for a review. 🙂

I think so, yes. Didn't knew it wouldn't fetch the workspace file. For me the pb command doesn't work, do I need to install something extra?

zkochan · 2026-02-13T00:03:35Z

It is pd, not pb.

Netail · 2026-02-13T12:44:07Z

It is pd, not pb.

Woops, I mean pd.

Seems to be getting a ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_SPEC No catalog entry 'esbuild' was found for catalog 'default'. when running pnpm link --dir ./pnpm/dev -g in the main branch & a zsh: command not found: pd when running pd

Netail commented Jan 9, 2026

View reviewed changes

Netail marked this pull request as ready for review January 9, 2026 16:11

Netail requested a review from zkochan as a code owner January 9, 2026 16:11

Copilot AI review requested due to automatic review settings January 9, 2026 16:11

Copilot started reviewing on behalf of Netail January 9, 2026 16:11 View session

Copilot AI reviewed Jan 9, 2026

View reviewed changes

feat: add support for catalogs with dlx

3f9b600

zkochan requested a review from gluxon January 13, 2026 13:51

gluxon self-assigned this Jan 13, 2026

gluxon reviewed Jan 25, 2026

View reviewed changes

Merge branch 'pnpm:main' into feat/dlx-catalog

90a95d3

This was referenced Jan 25, 2026

docs: add codeblock highlight #10510

Merged

feat: dlx timeout & retry #10512

Merged

fix: feedback

eeacc74

gluxon approved these changes Jan 25, 2026

View reviewed changes

Comment thread .changeset/curly-dryers-jam.md

Comment thread .changeset/curly-dryers-jam.md Outdated

Netail and others added 2 commits January 25, 2026 22:50

Update .changeset/curly-dryers-jam.md

4f80a73

Co-authored-by: Brandon Cheng <gluxon@users.noreply.github.com>

Update .changeset/curly-dryers-jam.md

3a1c722

Co-authored-by: Brandon Cheng <gluxon@users.noreply.github.com>

zkochan approved these changes Jan 26, 2026

View reviewed changes

zkochan merged commit 8eee416 into pnpm:main Jan 26, 2026
11 of 12 checks passed

Netail deleted the feat/dlx-catalog branch January 26, 2026 07:25

Netail mentioned this pull request Feb 11, 2026

ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_SPEC dlx catalog #10594

Closed

4 tasks

-    const resolvedBareSpecifier = resolveCatalogProtocol(catalogResolver, alias, bareSpecifier ?? '')
+    const resolvedBareSpecifier = bareSpecifier != null
+      ? resolveCatalogProtocol(catalogResolver, alias, bareSpecifier)
+      : bareSpecifier

Uh oh!

Conversation

Netail commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Netail Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

gluxon Jan 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

gluxon commented Jan 13, 2026

Uh oh!

gluxon Jan 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gluxon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

welcome Bot commented Jan 26, 2026

Uh oh!

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

Uh oh!

Uh oh!

gluxon commented Feb 12, 2026

Uh oh!

Netail commented Feb 12, 2026

Uh oh!

zkochan commented Feb 13, 2026

Uh oh!

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

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Netail commented Jan 9, 2026 •

edited

Loading

Netail commented Feb 11, 2026 •

edited

Loading

Netail commented Feb 13, 2026 •

edited

Loading