Add a new --live-reload parameter to the theme serve command

[karreiro]

WHY are these changes introduced?

Some users prefer to fully the reload page (I) when a file is modified, instead of relying on the hot reload mechanism that updates sections individually (II). Also, other users have their own tooling for refreshing the page, so they need to deactivate any refresh mechanism (III) entirely.

This PR introduces the --live-reload with three modes: I) full-page, II) hot-reload (default), and III) off.

WHAT is this pull request doing?

Main change

The new parameter (--live-reload) in the Theme::Command::Serve has three valid values:

• hot-reload - it's the current approach
• full-page - every time users perform a file change, the page is refreshed entirely
• off - the page is never automatically updated (the hot-reload.js#connect function is never called)

The ShopifyCLI::Theme::DevServer::ReloadMode class works like an enum and validates the parameter value when the Serve command calls ReloadMode.get.

The mode value is injected into the page with the hot-reload.js at the ShopifyCLI::Theme::DevServer::HotReload level. So, the parameter controls how the page refreshes in the client-side.

ShopifyCLI::Context change

Following the error/try-this convention introduced here, this PR introduces the ShopifyCLI::Context.abort(error_message, help_message = nil) API.

Now the abort API has an optional help message, which appears in the Try this frame.

How to test your changes?

Run shopify theme serve --live-reload=<MODE> with different reload modes and notice how the page behaves differently for each one:

• shopify theme serve --live-reload=hot-reload
  

• shopify theme serve --live-reload=full-page
  

• shopify theme serve --live-reload=off
  

• shopify theme serve (fast as the default)
  

• shopify theme serve --live-reload=other

Post-release steps

Update documentation with shopify theme serve parameters: shopify.dev/themes/tools/cli/theme-commands#serve.

Update checklist

• I've added a CHANGELOG entry for this PR (if the change is public-facing)
• I've considered possible cross-platform impacts (Mac, Linux, Windows).
• I've left the version number as is (we'll handle incrementing this when releasing).
• I've included any post-release steps in the section above.

[karreiro]

👋 Hi, @MeredithCastile! :)

This PR introduces a new flag for the theme serve command, the --live-reload-mode=MODE.

Currently, the live-reload mechanism has only a single mode (fast), so when partners change some file, theme serve shows the preview by:

• refreshing the entire page (automatically) when it's impossible to update components individually; or
• updating the page components individually with the edited ones.

However, some advanced users prefer to deactivate the mechanism above because they have custom tooling to auto-refresh the page. Other partners prefer to refresh the entire page always.

For handling these needs, the --live-reload-mode=MODE flag has 3 modes:

• fast - it's the current approach (default)
• full - every time users change a file, the page is refreshed entirely
• none - the page is never automatically updated, and the live reload is inactive

I personally like this terminology, but I'm not sure if this is the best one we can achieve for partners. What do you think about it? :)

Thanks! 🚀

[MeredithCastile]

Yes, those seem okay to me. You might consider exploring whether the word "mode" is necessary. I go back and forth on that.

You might consider, too, changing "full" to "full-page." To make it more intuitively graspable.

Suggestion, then:

theme serve --live-reload=fast
theme serve --live-reload=full-page
theme serve --live-reload=off

As always, we should have this in our help and documentation.

[macournoyer]

Looks right to me, other than comments.

Not too sure if we should rename "fast" to "hot reload". The feature is mentioned in the doc as "hot reload": https://shopify.dev/themes/tools/cli/theme-commands#serve. What do you think?

[karreiro]

Thanks for the review, @macournoyer!

Great suggestions, "hot reload" is more expressive than "fast"! I've updated the PR description and applied the changes/fixes in a new commit.

Thanks!

[notrealdev]

I have an error on Shopify 2.12

[karreiro]

Thanks a lot for reporting this and for sharing the stack, @notrealdev!

You may work around this issue by using the --live-reload flag without the equal sign, like this:

shopify theme serve --live-reload off

Still, I've just opened a PR fixing this issue #2092, so you will be able to use the equal sign again in the next CLI version.

We've done extensive work in the parameters parser to support glob parameters (#2066), which recently introduced that issue.