[Bug]: `shopify app deploy` doesn't recognize `web_directories` argument

[vfonic]

Please confirm that you have:

• [x] Searched existing issues to see if your issue is a duplicate. (If you’ve found a duplicate issue, feel free to add additional information in a comment on it.)
• [x] Reproduced the issue in the latest CLI version.

In which of these areas are you experiencing a problem?

App

Expected behavior

I should be able to provide web_directories argument so that I can narrow down which shopify.web.toml files need to be used for deploying a new app version. Or shopify app deploy should NOT read any shopify.web.toml files as they seem to not be relevant to deploying a new app version. (?)

Actual behavior

> shopify app deploy -c shopify.app.local.toml                           
╭─ error ───────────────────────────────────────────────────────────────────────╮
│                                                                               │
│  You can only have one web with the backend role in your app                  │
│                                                                               │
╰───────────────────────────────────────────────────────────────────────────────╯

The above error is caused by having multiple shopify.web.toml files inside of a gitignored directory nested within the project root.

> shopify app deploy -c shopify.app.local.toml --web_directories "frontend"
╭─ error ───────────────────────────────────────────────────────────────────────╮
│                                                                               │
│  Nonexistent flag: --web_directories                                          │
│  See more help with --help                                                    │
│                                                                               │
╰───────────────────────────────────────────────────────────────────────────────

Verbose output

Provided above

Reproduction steps

Provided above

Operating System

macOS

Shopify CLI version (shopify --version)

3.85.4

Shell

oh my zsh

Node version (run node -v if you're not sure)

v22.12.0

What language and version are you using in your application?

ruby 3.4.4 (2025-05-14 revision a38531fd3f) +PRISM [arm64-darwin24]

[vfonic]

Also the documentation here is misleading: https://shopify.dev/docs/apps/build/cli-for-apps/app-structure#web-files

I'm not sure where to report documentation issues so I'm posting it here.

In older versions of Shopify CLI, the web files were created in a directory called /web.

The default location for web files is the web/ subdirectory. Keeping your web files in a subdirectory like web/ helps to keep your project organized. However, Shopify CLI supports having the web file at the root of the project or any subdirectory of your choice. To use a different subdirectory or the project root for your web files, include the shopify.web.toml file in the directory.

Aside from one time being referred to as /web and another time as web/, seems like the updated recommendation is to NOT have shopify.web.toml inside ./web directory. The second Tip probably hasn't been updated, following this new recommendation.

[amcaplan]

Hi @vfonic, this happens because we are running the same validation before running dev (where webs need to be valid) as before running deploy. Which generally makes sense. You're correct that deploying doesn't have to be stopped by invalid webs, but the gains here seem pretty marginal, as in most cases you should have a valid app at all times.

Good note on the documentation, though.

[vfonic]

You're right, it makes sense to have the app state valid.

I guess this is the same issue as [Bug]: Shopify CLI shouldn't read all TOML files in the project and "guess" they are all applicable to current app #6472

Isaac already explained that web_directories is not a CLI argument, but one of the config options in the TOML file.

The issue is that Shopify CLI looks for TOML files in "too many places". I have gitignored directory inside the project root where I add git workspaces (basically duplicates of the current project). Those workspaces have the same TOML files like the main project. This causes Shopify CLI to find several frontend and backend roles within the same project.

Maybe the best solution would be to skip traversing gitignored directories? I'm not sure. Does Shopify CLI skip any directories or it literally traverses all of the directories, including node_modules and any hidden dotfiles/directories? It does sound odd that a random NPM package, having shopify.web.toml with roles = ["frontend", "backend"] could prevent user from running shopify app dev command successfully.

[isaacroldan]

We explicitly ignore anything in node_modules. The logic for searching web.toml files is a bit old and we should probably revisit it, as it does indeed look in every subfolder of your project.

[vfonic]

It must be a difficult challenge, as there can be many, many directories that might slow the command down and might be worth excluding: tmp, logs, cache, build, dist, .git, ...

Maybe it would be worth it to reverse the logic and have one default .web.toml file name (in the root?) and allow passing command line argument similar to --config shopify.app.toml