shopify-extensions is an add-on to the Shopify CLI 2.0, which is installed automatically when installing the CLI. It is not meant to be invoked directly. Instead, invocation of shopify-extensions occurs through shopify extension. Today, shopify-extensions' main purpose is to power the experience of shopify extension serve, shopify extension build and augment shopify extension create.
The information below is mainly targeting contributors rather than users. If you want to learn more about how to build extensions and how to use the Shopify CLI in general, please consult the official documentation.
Note that Shopify CLI 2.0 is deprecated and will be sunset on May 31, 2023. We encourage using Shopify CLI 3.0 to develop apps, custom storefronts, and themes.
Prerequisites:
- Go, version 1.17 or higher
- The current LTS version of Node.JS
Install Go by running
brew install goInstall Node.JS by running:
brew install nodeOPTIONAL: If you are a Shopify employee, your machine may be configured to use
npm.shopify.io. To avoidyarnerrors, install the project by runningdev up.
Next, familiarize yourself with the Makefile. It defines several useful tasks for building and testing the project.
To build the project, bootstrap some example extensions and install all of their dependencies, run:
make bootstrapThis will create extensions in the tmp/ folder and install the node dependencies. It will also build the Dev Console app. For more information on creating extensions, see Creating Extensions. Next, you can run the server by executing the following shell command:
make run serve testdata/extension.config.ymlSubsequently, you should be able to retrieve sample assets as follows:
curl http://localhost:8000/extensions/00000000-0000-0000-0000-000000000001/assets/main.jsGoing to root end point http://localhost:8000 will take you to the Dev Console app.
To run the Go and JavaScript Unit tests, simply execute the following shell command:
make testThe project also provides integration tests, which can be executed as follows:
make integration-testBoth sets of tests are executed for all pull-requests and commits to the main branch. The automated integration test only tests the integration between the Go and the JavaScript layer. It does not test the integration with Shopify CLI. For information on how to manually test the full end to end flow, see Testing the integration with the Shopify CLI.
This project contains multiple publishable artifacts: a Go binary and and several Node packages.
To publish the UI Extension Server kit and Node Shopify CLI Extensions, create a new branch. Then do a version bump.
yarn version-bumpThen push up bump, plus changes.
git push --follow-tagsOnce the PR for the new branch is merged, you can deploy the packages on Shipit.
Please choose latest as the distribution tag in ShipIt if you're deploying a stable version and next if you're deploying a pre-release version.
These tags allow developers to reference our libraries without having to specify a particular version.
Npm Dist Tags shouldn't be confused with Git Tags, which are created during the release process as well.
Publishing the Go Binary is done through GitHub Releases, which also allows to create a Git tag in the process. Simply create a new release and publish it. Subsequently, a GitHub Action will cross-compile the binaries and attach the resulting assets to the release.
To create new extension projects, simply execute the following shell command:
make run create testdata/extension.config.ymlThis will create new extensions inside the tmp folder. You can update testdata/extension.config.yml if you want to test different options.
The YAML file is in the format of
extensions:
- uuid: 00000000-0000-0000-0000-000000000001
type: TYPE
development:
root_dir: 'api/testdata'
build_dir: 'build'
template: TEMPLATE_NAME
renderer:
name: RENDERER_LIBRARYRENDERER_LIBRARY
- @shopify/checkout-ui-extensions
TYPE
- checkout_ui_extension
TEMPLATE_NAME
- typescript
- javascript
- typescript-react
- javascript-react
To use the Dev Server with a local version of Shopify CLI, first follow these set up steps:
-
Clone the Shopify CLI repo
-
Set up an alias for your terminal to point to the repo's
bin/shopify. For example, inside the~/.zshrc, add the following:alias shopify-local="~/src/github.com/Shopify/shopify-cli/bin/shopify" -
Enable the beta flag for your local Shopify CLI by running
shopify-local config feature extension_server_beta --enable.
- Inside the Shopify CLI project run
rake extensions:installto download the latest extension server binary and place it inext/shopify-extensions
Afterwards, the following three commands will be executed by the new extension server:
shopify-local extension createshopify-local extension serveshopify-local extension build
Testing against a development build is possible, too. Follow these steps:
- Clone this repository and make sure that it is located in the same parent directory as
shopify-cliand namedshopify-cli-extensions. - Run
make buildinshopify-cli-extensionsand wait for the build process to complete. - Navigate into the Shopify CLI directory via
cd ../shopify-cliand runrake extensions:symlinkto create a symlink to the binary you just created. Just like before you require the above feature flag for testing.
You can test a development build of the Dev Server with the production version of the Shopify CLI, first follow these set up steps:
- Enable the beta flag for your production Shopify CLI by running
shopify config feature extension_server_beta --enable. - Clone this repository.
- Run
make buildinshopify-cli-extensionsand wait for the build process to complete. - Find the folder where
shopify-cliwas installed and cd into that folder. If you are using Homebrew, runbrew --prefix shopify-cli. If you have installed it from a gem, rungem info shopify-clito find the "Installed at" path. The Dev Server should be installed inside the localgems/shopify-cli-<version>/ext/shopify-extensionsfolder. - Rename the Dev Server production binary so you have a copy of it to fallback on:
mv gems/shopify-cli-<version>/ext/shopify-extensions gems/shopify-cli-<version>/ext/shopify-extensions/shopify-extensions-prod. - Set up a symlink to the local Go binary:
ln -s ~/src/github.com/Shopify/shopify-cli-extensions/shopify-extensions gems/shopify-cli-<version>/ext/shopify-extensions/shopify-extensions
Afterwards, the following three commands will be executed by the development build of the Dev Server:
shopify extension createshopify extension serveshopify extension build
To stop using the development build of the Dev Server, follow these steps:
- Remove the symlink to the local Go binary:
rm gems/shopify-cli-<version>/ext/shopify-extensions/shopify-extensions - Rename the Dev Server production binary back to its original name:
mv gems/shopify-cli-<version>/ext/shopify-extensions-prod gems/shopify-cli-<version>/ext/shopify-extensions/shopify-extensions.
The build process is taken care of in the dev server build step. You can also run it yourself.
make bootstrap
# or
yarn buildThe Dev Console needs a built dev server to connect to via a WebSocket.
# If you haven't already
make bootstrapThen, run the DevConsole app and Dev Server simultaneously when developing for the DevConsole.
# This will run `make run serve testdata/extension.config.yml` and `yarn start`
make serve-dev testdata/extension.config.ymlstart: Start up the DevConsole apptest: Run Jest testsbuild: Builds the Dev Server Kit and Dev Console applint: Runs lintingversion-bump: Version bumpdeploy: Publishes Dev Server Kit and Dev Console