Lazy imports and V8 compile cache

Defer heavy module imports to point of use across the codebase:
- base-command: lazy ui.js (600KB React/Ink), error-handler, notifications
- prerun hook: parallel imports via Promise.all
- postrun hook: lazy analytics and deprecations
- node-package-manager: lazy latest-version import
- context/local: lazy fs.js and system.js (break circular deps)
- is-global: lazy output.js, system.js, version.js, ui.js
- custom-oclif-loader: fire-and-forget init hooks via runHook override

Enable V8 compile cache via module.enableCompileCache() in dev.js/run.js,
caching bytecode between runs to eliminate ~30ms compile overhead.

Combined improvement: ~130ms across all commands

Made-with: Cursor

Author: gonzaloriestra

packages/cli-kit/src/public/node/base-command.test.ts

@@ -5,16 +5,26 @@ import {globalFlags} from './cli.js'
 import {inTemporaryDirectory, mkdir, writeFile} from './fs.js'
 import {joinPath, resolvePath, cwd} from './path.js'
 import {mockAndCaptureOutput} from './testing/output.js'
-import {terminalSupportsPrompting} from './system.js'
 import {unstyled} from './output.js'
-import {beforeEach, describe, expect, test, vi} from 'vitest'
+import {afterEach, beforeEach, describe, expect, test, vi} from 'vitest'
 import {Flags} from '@oclif/core'
 
-vi.mock('./system.js')
+let originalStdinIsTTY: boolean | undefined
+let originalStdoutIsTTY: boolean | undefined
 
 beforeEach(() => {
-  vi.mocked(terminalSupportsPrompting).mockReturnValue(true)
+  originalStdinIsTTY = process.stdin.isTTY
+  originalStdoutIsTTY = process.stdout.isTTY
   vi.unstubAllEnvs()
+  // Default: simulate interactive TTY environment
+  Object.defineProperty(process.stdin, 'isTTY', {value: true, configurable: true, writable: true})
+  Object.defineProperty(process.stdout, 'isTTY', {value: true, configurable: true, writable: true})
+  vi.stubEnv('CI', '')
+})
+
+afterEach(() => {
+  Object.defineProperty(process.stdin, 'isTTY', {value: originalStdinIsTTY, configurable: true, writable: true})
+  Object.defineProperty(process.stdout, 'isTTY', {value: originalStdoutIsTTY, configurable: true, writable: true})
 })
 
 let testResult: Record<string, unknown> = {}
@@ -406,8 +416,10 @@ describe('applying environments', async () => {
   )
 
   runTestInTmpDir('does not throw in TTY mode when a non-TTY required argument is missing', async (tmpDir: string) => {
-    // Given
-    vi.mocked(terminalSupportsPrompting).mockReturnValue(true)
+    // Given — simulate interactive terminal
+    Object.defineProperty(process.stdin, 'isTTY', {value: true, configurable: true, writable: true})
+    Object.defineProperty(process.stdout, 'isTTY', {value: true, configurable: true, writable: true})
+    vi.stubEnv('CI', '')
 
     // When
     await MockCommandWithRequiredFlagInNonTTY.run(['--path', tmpDir])
@@ -417,8 +429,8 @@ describe('applying environments', async () => {
   })
 
   runTestInTmpDir('throws in non-TTY mode when a non-TTY required argument is missing', async (tmpDir: string) => {
-    // Given
-    vi.mocked(terminalSupportsPrompting).mockReturnValue(false)
+    // Given — simulate non-interactive (CI) environment
+    vi.stubEnv('CI', 'true')
 
     // When
     await MockCommandWithRequiredFlagInNonTTY.run(['--path', tmpDir])

packages/cli-kit/src/public/node/base-command.ts

@@ -1,18 +1,13 @@
-import {errorHandler, registerCleanBugsnagErrorsFromWithinPlugins} from './error-handler.js'
-import {loadEnvironment, environmentFilePath} from './environments.js'
 import {isDevelopment} from './context/local.js'
 import {addPublicMetadata} from './metadata.js'
 import {AbortError} from './error.js'
-import {renderInfo, renderWarning} from './ui.js'
 import {outputContent, outputResult, outputToken} from './output.js'
 import {terminalSupportsPrompting} from './system.js'
 import {hashString} from './crypto.js'
 import {isTruthy} from './context/utilities.js'
-import {showNotificationsIfNeeded} from './notifications-system.js'
 import {setCurrentCommandId} from './global-context.js'
 import {JsonMap} from '../../private/common/json.js'
 import {underscore} from '../common/string.js'
-
 import {Command, Config, Errors} from '@oclif/core'
 import {OutputFlags, Input, ParserOutput, FlagInput, OutputArgs} from '@oclif/core/parser'
 
@@ -45,6 +40,7 @@ abstract class BaseCommand extends Command {
 
   async catch(error: Error & {skipOclifErrorHandling: boolean}): Promise<void> {
     error.skipOclifErrorHandling = true
+    const {errorHandler} = await import('./error-handler.js')
     await errorHandler(error, this.config)
     return Errors.handle(error)
   }
@@ -54,10 +50,12 @@ abstract class BaseCommand extends Command {
     setCurrentCommandId(this.id ?? '')
     if (!isDevelopment()) {
       // This function runs just prior to `run`
+      const {registerCleanBugsnagErrorsFromWithinPlugins} = await import('./error-handler.js')
       await registerCleanBugsnagErrorsFromWithinPlugins(this.config)
     }
     await removeDuplicatedPlugins(this.config)
     this.showNpmFlagWarning()
+    const {showNotificationsIfNeeded} = await import('./notifications-system.js')
     await showNotificationsIfNeeded()
     return super.init()
   }
@@ -71,13 +69,16 @@ abstract class BaseCommand extends Command {
     const possibleNpmEnvVars = commandFlags.map((key) => `npm_config_${underscore(key).replace(/^no_/, '')}`)
 
     if (possibleNpmEnvVars.some((flag) => process.env[flag] !== undefined)) {
-      renderWarning({
-        body: [
-          'NPM scripts require an extra',
-          {command: '--'},
-          'separator to pass the flags. Example:',
-          {command: 'npm run dev -- --reset'},
-        ],
+      // eslint-disable-next-line no-void
+      void import('./ui.js').then(({renderWarning}) => {
+        renderWarning({
+          body: [
+            'NPM scripts require an extra',
+            {command: '--'},
+            'separator to pass the flags. Example:',
+            {command: 'npm run dev -- --reset'},
+          ],
+        })
       })
     }
   }
@@ -143,6 +144,7 @@ This flag is required in non-interactive terminal environments, such as a CI env
 
     if (!environmentsFileName) return originalResult
 
+    const {environmentFilePath} = await import('./environments.js')
     const environmentFileExists = await environmentFilePath(environmentsFileName, {from: flags.path})
 
     // Handle both string and array cases for environment flag
@@ -202,6 +204,7 @@ This flag is required in non-interactive terminal environments, such as a CI env
     environmentsFileName: string,
     specifiedEnvironment: string | undefined,
   ): Promise<{environment: JsonMap | undefined; isDefaultEnvironment: boolean}> {
+    const {loadEnvironment} = await import('./environments.js')
     if (specifiedEnvironment) {
       const environment = await loadEnvironment(specifiedEnvironment, environmentsFileName, {from: path})
       return {environment, isDefaultEnvironment: false}
@@ -254,9 +257,12 @@ function reportEnvironmentApplication<
   if (Object.keys(changes).length === 0) return
 
   const items = Object.entries(changes).map(([name, value]) => `${name}: ${value}`)
-  renderInfo({
-    headline: ['Using applicable flags from', {userInput: environmentName}, 'environment:'],
-    body: [{list: {items}}],
+  // eslint-disable-next-line no-void
+  void import('./ui.js').then(({renderInfo}) => {
+    renderInfo({
+      headline: ['Using applicable flags from', {userInput: environmentName}, 'environment:'],
+      body: [{list: {items}}],
+    })
   })
 }
 
@@ -342,6 +348,7 @@ async function removeDuplicatedPlugins(config: Config): Promise<void> {
   const pluginsToRemove = plugins.filter((plugin) => bundlePlugins.includes(plugin.name))
   if (pluginsToRemove.length > 0) {
     const commandsToRun = pluginsToRemove.map((plugin) => `  - shopify plugins remove ${plugin.name}`).join('\n')
+    const {renderWarning} = await import('./ui.js')
     renderWarning({
       headline: `Unsupported plugins detected: ${pluginsToRemove.map((plugin) => plugin.name).join(', ')}`,
       body: [
@@ -351,6 +358,7 @@ async function removeDuplicatedPlugins(config: Config): Promise<void> {
     })
   }
   const filteredPlugins = plugins.filter((plugin) => !bundlePlugins.includes(plugin.name))
+  // eslint-disable-next-line require-atomic-updates -- config.plugins won't be modified by renderWarning above
   config.plugins = new Map(filteredPlugins.map((plugin) => [plugin.name, plugin]))
 }
 

packages/cli-kit/src/public/node/context/local.ts

@@ -1,14 +1,22 @@
 import {isTruthy} from './utilities.js'
 import {getCIMetadata, isSet, Metadata} from '../../../private/node/context/utilities.js'
 import {defaultThemeKitAccessDomain, environmentVariables, pathConstants} from '../../../private/node/constants.js'
-import {fileExists} from '../fs.js'
-import {exec} from '../system.js'
-
 import isInteractive from 'is-interactive'
 import macaddress from 'macaddress'
-
 import {homedir} from 'os'
 
+// Dynamic imports to avoid circular dependency: context/local → fs → output → context/local
+// fileExists and exec are only used in specific async functions, not at module init.
+async function lazyFileExists(path: string): Promise<boolean> {
+  const {fileExists} = await import('../fs.js')
+  return fileExists(path)
+}
+
+async function lazyExec(command: string, args: string[]): Promise<void> {
+  const {exec} = await import('../system.js')
+  await exec(command, args)
+}
+
 /**
  * It returns true if the terminal is interactive.
  *
@@ -68,7 +76,7 @@ export async function isShopify(env = process.env): Promise<boolean> {
   if (Object.prototype.hasOwnProperty.call(env, environmentVariables.runAsUser)) {
     return !isTruthy(env[environmentVariables.runAsUser])
   }
-  const devInstalled = await fileExists(pathConstants.executables.dev)
+  const devInstalled = await lazyFileExists(pathConstants.executables.dev)
   return devInstalled
 }
 
@@ -217,7 +225,7 @@ export function cloudEnvironment(env: NodeJS.ProcessEnv = process.env): {
  */
 export async function hasGit(): Promise<boolean> {
   try {
-    await exec('git', ['--version'])
+    await lazyExec('git', ['--version'])
     return true
     // eslint-disable-next-line no-catch-all/no-catch-all
   } catch {

packages/cli-kit/src/public/node/custom-oclif-loader.ts

@@ -17,7 +17,6 @@ export class ShopifyConfig extends Config {
 
   constructor(options: Options) {
     if (isDevelopment()) {
-      // eslint-disable-next-line @shopify/cli/no-process-cwd
       const currentPath = cwd()
 
       let path = sniffForPath() ?? currentPath

packages/cli-kit/src/public/node/error.ts

@@ -1,10 +1,11 @@
-import {AlertCustomSection, renderFatalError} from './ui.js'
 import {normalizePath} from './path.js'
 import {OutputMessage, stringifyMessage, TokenizedString} from './output.js'
 import {InlineToken, TokenItem, tokenItemToString} from '../../private/node/ui/components/TokenizedText.js'
 
 import {Errors} from '@oclif/core'
 
+import type {AlertCustomSection} from './ui.js'
+
 export {ExtendableError} from 'ts-error'
 
 export enum FatalErrorType {
@@ -146,6 +147,7 @@ export async function handler(error: unknown): Promise<unknown> {
     }
   }
 
+  const {renderFatalError} = await import('./ui.js')
   renderFatalError(fatal)
   return Promise.resolve(error)
 }

packages/cli-kit/src/public/node/hooks/postrun.ts

@@ -1,13 +1,7 @@
-import {postrun as deprecationsHook} from './deprecations.js'
-import {reportAnalyticsEvent} from '../analytics.js'
-import {outputDebug, outputWarn} from '../output.js'
-import {getOutputUpdateCLIReminder, runCLIUpgrade, versionToAutoUpgrade, warnIfUpgradeAvailable} from '../upgrade.js'
-import {inferPackageManagerForGlobalCLI} from '../is-global.js'
-import BaseCommand from '../base-command.js'
-import * as metadata from '../metadata.js'
-import {runAtMinimumInterval} from '../../../private/node/conf-store.js'
-import {CLI_KIT_VERSION} from '../../common/version.js'
-import {isMajorVersionChange} from '../version.js'
+/**
+ * Postrun hook — uses dynamic imports to avoid loading heavy modules (base-command, analytics)
+ * at module evaluation time. These are only needed after the command has already finished.
+ */
 import {Command, Hook} from '@oclif/core'
 
 let postRunHookCompleted = false
@@ -24,9 +18,14 @@ export function postRunHookHasCompleted(): boolean {
 // This hook is called after each successful command run. More info: https://oclif.io/docs/hooks
 export const hook: Hook.Postrun = async ({config, Command}) => {
   await detectStopCommand(Command as unknown as typeof Command)
+
+  const {reportAnalyticsEvent} = await import('../analytics.js')
   await reportAnalyticsEvent({config, exitMode: 'ok'})
+
+  const {postrun: deprecationsHook} = await import('./deprecations.js')
   deprecationsHook(Command)
 
+  const {outputDebug} = await import('../output.js')
   const command = Command.id.replace(/:/g, ' ')
   outputDebug(`Completed command ${command}`)
   postRunHookCompleted = true
@@ -48,6 +47,7 @@ export const hook: Hook.Postrun = async ({config, Command}) => {
  * @returns Resolves when the upgrade attempt (or fallback warning) is complete.
  */
 export async function autoUpgradeIfNeeded(): Promise<void> {
+  const {versionToAutoUpgrade, warnIfUpgradeAvailable} = await import('../upgrade.js')
   const newerVersion = versionToAutoUpgrade()
   if (!newerVersion) {
     await warnIfUpgradeAvailable()
@@ -60,6 +60,7 @@ export async function autoUpgradeIfNeeded(): Promise<void> {
   if (forced) {
     await performAutoUpgrade(newerVersion)
   } else {
+    const {runAtMinimumInterval} = await import('../../../private/node/conf-store.js')
     // Rate-limit the entire upgrade flow to once per day to avoid repeated attempts and major-version warnings.
     await runAtMinimumInterval('auto-upgrade', {days: 1}, async () => {
       await performAutoUpgrade(newerVersion)
@@ -68,6 +69,18 @@ export async function autoUpgradeIfNeeded(): Promise<void> {
 }
 
 async function performAutoUpgrade(newerVersion: string): Promise<void> {
+  const [
+    {CLI_KIT_VERSION},
+    {isMajorVersionChange},
+    {outputWarn, outputDebug},
+    {getOutputUpdateCLIReminder, runCLIUpgrade},
+  ] = await Promise.all([
+    import('../../common/version.js'),
+    import('../version.js'),
+    import('../output.js'),
+    import('../upgrade.js'),
+  ])
+
   if (isMajorVersionChange(CLI_KIT_VERSION, newerVersion)) {
     return outputWarn(getOutputUpdateCLIReminder(newerVersion))
   }
@@ -79,8 +92,10 @@ async function performAutoUpgrade(newerVersion: string): Promise<void> {
     const errorMessage = `Auto-upgrade failed: ${error}`
     outputDebug(errorMessage)
     outputWarn(getOutputUpdateCLIReminder(newerVersion))
-    // Report to Observe as a handled error without showing anything extra to the user
-    const {sendErrorToBugsnag} = await import('../error-handler.js')
+    const [{sendErrorToBugsnag}, {inferPackageManagerForGlobalCLI}] = await Promise.all([
+      import('../error-handler.js'),
+      import('../is-global.js'),
+    ])
     const enrichedError = Object.assign(new Error(errorMessage), {
       packageManager: inferPackageManagerForGlobalCLI(),
       platform: process.platform,
@@ -93,13 +108,20 @@ async function performAutoUpgrade(newerVersion: string): Promise<void> {
 /**
  * Override the command name with the stop one for analytics purposes.
  *
- * @param commandClass - Oclif command class.
+ * @param commandClass - Command.Class.
  */
-async function detectStopCommand(commandClass: Command.Class | typeof BaseCommand): Promise<void> {
+async function detectStopCommand(commandClass: Command.Class): Promise<void> {
   const currentTime = new Date().getTime()
-  if (commandClass && Object.prototype.hasOwnProperty.call(commandClass, 'analyticsStopCommand')) {
-    const stopCommand = (commandClass as typeof BaseCommand).analyticsStopCommand()
+  // Check for analyticsStopCommand without importing BaseCommand
+  if (
+    commandClass &&
+    'analyticsStopCommand' in commandClass &&
+    typeof commandClass.analyticsStopCommand === 'function'
+  ) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const stopCommand = (commandClass as any).analyticsStopCommand()
     if (stopCommand) {
+      const metadata = await import('../metadata.js')
       const {commandStartOptions} = metadata.getAllSensitiveMetadata()
       if (!commandStartOptions) return
       await metadata.addSensitiveMetadata(() => ({