// ██████╗ ███████╗██╗ ██╗███████╗██╗ ██████╗ ██████╗ // ██╔══██╗██╔════╝██║ ██║██╔════╝██║ ██╔═══██╗██╔══██╗ // ██║ ██║█████╗ ██║ ██║█████╗ ██║ ██║ ██║██████╔╝ // ██║ ██║██╔══╝ ╚██╗ ██╔╝██╔══╝ ██║ ██║ ██║██╔═══╝ // ██████╔╝███████╗ ╚████╔╝ ███████╗███████╗╚██████╔╝██║ // ╚═════╝ ╚══════╝ ╚═══╝ ╚══════╝╚══════╝ ╚═════╝ ╚═╝ // MIT License (c) 2020–present Cezar Augusto & the Extension.js authors, presence implies inheritance import { loadBrowserConfig, loadCommandConfig, loadProjectConfigDefaults } from './lib/config-loader' import {withDarkMode} from './lib/dark-mode' import { ensureDevelopArtifacts, ensureUserProjectDependencies } from './lib/ensure-develop-artifacts' import {generateExtensionTypes} from './lib/generate-extension-types' import { DEV_COMMAND_DEFAULTS, falseProfileSource, mergeOptionLayers } from './lib/merge-options' import * as messages from './lib/messages' import {debugLine, isDebug} from './lib/messaging' import {getDirs, normalizeBrowser} from './lib/paths' import {getProjectStructure} from './lib/project' import {resolveSafariIdentity} from './lib/safari-identity' import {assertNoManagedDependencyConflicts} from './lib/validate-user-dependencies' import { type BrowserLauncherFn, BrowsersPlugin, BuildEmitter, type RunnerPlugin } from './plugin-browsers' import {SafariDevPlugin} from './plugin-browsers/safari-dev-plugin' import { ensureTypeScriptConfig, isUsingTypeScript } from './plugin-js-frameworks/js-tools/typescript' import type {BrowserConfig, DevOptions} from './types' export async function extensionDev( pathOrRemoteUrl: string | undefined, devOptions: DevOptions & { // Called once when the session is usable: the browser opened with the // extension loaded, or the first compile finished when none is launched. onReady?: () => void launcher?: BrowserLauncherFn // Called once every refusal that can end the run before a server exists // has passed, so a caller can announce the session only when there is one. onSessionStart?: () => void // Called with the failure right before exitOnError ends the process, so // a caller can report a run that died after its session was announced. onExitError?: (error: unknown, code?: string) => void } ): Promise { let browsersPlugin: RunnerPlugin | undefined let emitter: BuildEmitter = new BuildEmitter() // The CLI wrapper passes exitOnError=true; as a library import a failed dev // session must be a rejected promise, never a process.exit inside the host. const shouldExitOnError = (devOptions.exitOnError ?? false) && process.env.VITEST !== 'true' const projectStructure = await getProjectStructure(pathOrRemoteUrl) try { const isAuthor = isDebug() const debug = isAuthor const {manifestDir, packageJsonDir} = getDirs(projectStructure) await ensureDevelopArtifacts() if (devOptions.install !== false) { await ensureUserProjectDependencies(packageJsonDir) } // Create/validate tsconfig (and surface the "missing tsconfig" error) // before deciding whether to generate extension type defs. ensureTypeScriptConfig(manifestDir) if (isUsingTypeScript(manifestDir)) { await generateExtensionTypes(manifestDir, packageJsonDir) } const userManifestPath = projectStructure.packageJsonPath || projectStructure.denoJsonPath if (userManifestPath) { assertNoManagedDependencyConflicts(userManifestPath, packageJsonDir) } // commands.dev.browser must be read before the target is picked, or the // config file can never choose the browser when no --browser flag arrived. const commandConfig = await loadCommandConfig(packageJsonDir, 'dev') const configBrowser = (commandConfig as {browser?: DevOptions['browser']}) .browser const browser = normalizeBrowser( devOptions.browser || configBrowser || 'chrome', devOptions.chromiumBinary, devOptions.geckoBinary || devOptions.firefoxBinary, devOptions.safariBinary ) const geckoBinary = devOptions.geckoBinary || devOptions.firefoxBinary if (debug) { debugLine(messages.debugDirs(manifestDir, packageJsonDir)) debugLine( messages.debugBrowser(browser, devOptions.chromiumBinary, geckoBinary) ) } // stock defaults, then top-level config, then browser.*, then // commands.dev, then CLI. Unset CLI keys fall through so shared // extension.config.js values apply. const projectConfig = await loadProjectConfigDefaults(packageJsonDir) const browserConfig = await loadBrowserConfig(packageJsonDir, browser) const merged = withDarkMode({ ...mergeOptionLayers( DEV_COMMAND_DEFAULTS, projectConfig, browserConfig, commandConfig, devOptions ), browser }) if ( (browser === 'safari' || browser === 'webkit-based') && !devOptions.noBrowser && devOptions.safariPackager ) { // Identity/packaging inputs: CLI flags win over extension.config.js // `browser.safari` (already merged CLI-last above). const safariPackager = devOptions.safariPackager const safariOverrides = { ...resolveSafariIdentity(merged, packageJsonDir), noOpen: merged.noOpen, startingUrl: merged.startingUrl } browsersPlugin = new SafariDevPlugin((distPath, packagerMode) => safariPackager(distPath, packagerMode, safariOverrides) ) emitter = browsersPlugin.emitter } else if (devOptions.launcher && !devOptions.noBrowser) { browsersPlugin = new BrowsersPlugin({ launcher: devOptions.launcher, browserOptions: { browser, mode: 'development', enableDevtools: true, noOpen: merged.noOpen, profile: merged.profile, profileSource: falseProfileSource(merged.profile, devOptions.profile), persistProfile: merged.persistProfile, keepProfileChanges: merged.keepProfileChanges, copyFromProfile: merged.copyFromProfile, preferences: merged.preferences, browserFlags: merged.browserFlags, excludeBrowserFlags: merged.excludeBrowserFlags, startingUrl: merged.startingUrl, chromiumBinary: merged.chromiumBinary, geckoBinary: merged.geckoBinary || merged.firefoxBinary, port: merged.port, logLevel: merged.logLevel, logContexts: merged.logContexts, logFormat: merged.logFormat, logTimestamps: merged.logTimestamps, logColor: merged.logColor, logUrl: merged.logUrl, logTab: merged.logTab } }) emitter = browsersPlugin.emitter } if (process.env.EXTENSION_DEV_DRY_RUN === 'true') { return emitter } // Heavy deps are imported lazily so preview can stay minimal. const {devServer} = await import('./dev-server') // Pass the merged options so bundler-facing flags (polyfill, logger // options) ride the same defaults-config-CLI precedence as the browser // launcher above. await devServer(projectStructure, { ...merged, onReady: devOptions.onReady, mode: 'development', browser, geckoBinary, browsersPlugin, onSessionStart: devOptions.onSessionStart, onExitError: devOptions.onExitError } as Parameters[1]) return emitter } catch (error) { // Always surface a minimal error: contract errors print once, clean, no stack; // author mode keeps the full trace. if (isDebug()) { console.error(error) } else { console.error(messages.devCommandFailed(error)) } if (!shouldExitOnError) { throw error } try { devOptions.onExitError?.(error) } catch { // Best-effort: a caller's report must never change how the run ends. } process.exit(1) } }