repository·main·Indexed 20 days ago
https://github.com/shopify/cliA command-line interface for developing Shopify apps, themes, and Hydrogen custom storefronts. It includes a plugin architecture based on @shopify/cli-kit, which provides a UI Kit for standardized terminal interactions, including prompts (select, confirmation, autocomplete, text), static output banners, and task visualizers for concurrent or sequential processes.
The Shopify CLI is a command-line tool used to manage various aspects of the Shopify development lifecycle. It allows developers to:
The Shopify CLI is a terminal-based tool used by merchants, partners, and developers to interact with the Shopify platform.
Its architecture is designed for horizontal feature expansion through plugins. Instead of a monolithic structure, specific capabilities are added via specialized packages that build on top of @shopify/cli-kit.
Examples of existing plugins include:
@shopify/theme: For developing Shopify themes.@shopify/app: For developing Shopify apps.@shopify/cli-hydrogen: For developing Hydrogen custom storefronts.The CLI UI Kit is a set of modules within the @shopify/cli-kit package designed for terminal interaction. It provides a standardized way to:
Using the UI Kit ensures that your CLI commands maintain a consistent look and feel with the rest of Shopify's tools and allows you to benefit from design improvements automatically without changing your code.
The useExtensionServerContext hook automatically manages extension state by listening to specific events. You do not need to manually subscribe to these to achieve the following behaviors:
update event is dispatched.focused property in the context state is set to true or false based on focus and unfocus events.refresh event is dispatched.The @shopify/create-app package builds a bundle at dist/commands/init.js.
Unlike other packages, it bundles @shopify/cli-kit directly into the command bundle rather than treating it as an external dependency. This allows Rollup to perform tree-shaking, ensuring that only the specific elements of @shopify/cli-kit required for app creation are included in the final bundle, keeping the installation lightweight.
Certain flags are considered 'reserved' and must use a specific, pre-defined environment variable name. Do not attempt to create custom environment variable mappings for these reserved flags, as it will violate the command-reserved-flags rule.
export default class Dev extends Command {
static flags = {
path: Flags.string({
hidden: true,
env: 'SHOPIFY_FLAG_APP_PATH', // Incorrect: It must be SHOPIFY_FLAG_PATH
}),
}
}To prevent accidental Git commits of sensitive or environment-specific identifiers, Shopify CLI uses two different persistence strategies depending on the workflow:
During development (dev command), the application ID (API key) is stored in a global cache associated with the project's directory. This allows the ID to be reused across multiple runs without being written to project-level configuration files. Extension IDs are generated randomly and are tied to the lifecycle of the specific dev command run.
During deployment, identifiers are persisted in a .env file at the root of the app. This ensures that all deployments target the same production Partners' App.
Best Practices for Deployment IDs:
.env file in their Git repository (it is common to exclude it)..env file.As of version 3.0, the Shopify CLI is a TypeScript-based tool that targets NodeJS as its primary runtime.
Key architectural characteristics include:
package.json at the root to manage dependencies for all app blocks, replacing scattered dependency management.theme-check used in Rails-based projects) remain in Ruby. The CLI handles this by including the Ruby code within the NPM package and verifying that a Ruby interpreter is present in the user's environment before executing theme workflows.The UI Kit is built on a principle of abstraction. All public functions are defined in public/node/ui.tsx and accept simple JavaScript objects as parameters.
Instead of requiring you to manage React components or JSX directly, the API allows you to focus on providing data structures (like tokens) to render functions. This abstraction allows the underlying implementation to be upgraded or restructured without breaking your command's public API.
The CLI UI Kit public interface is divided into three categories based on how they handle execution and rendering:
await.CRITICAL: Do not call two Prompts or Async tasks in succession without awaiting them. Doing so will instantiate multiple React rendering instances, causing rendering conflicts.
The CLI uses two primary mechanisms to classify non-fatal errors as environmental issues:
shouldReportErrorAsUnexpected: Determines if an error should be treated as a CLI bug.errorMessageImpliesEnvironmentIssue: Checks if an error message matches known environmental patterns.Common categories for environmental issues include:
EACCES: permission denied.socket hang up.EBUSY: resource busy or locked.Guidelines for adding new patterns:
const environmentIssueMessages = [
'EPERM: operation not permitted, scandir',
'EPERM: operation not permitted, rename',
'EACCES: permission denied',
'EPERM: operation not permitted, symlink',
'This version of npm supports the following node versions',
'EBUSY: resource busy or locked',
'ENOTEMPTY: directory not empty',
'getaddrinfo ENOTFOUND',
'Client network socket disconnected before secure TLS connection was established',
'spawn EPERM',
'socket hang up',
]Because the CLI avoids heavy bundling tools (like ESBuild or Webpack) to keep the tooling stack lean and debugging simple, dependencies are not tree-shaken. This means importing a module often loads its entire dependency graph. To maintain performance, follow these guidelines:
await import("dependency-name") to load it only when needed. Note that this makes the dependent module's API asynchronous.