gt 2.22.4 → 2.23.0

package/dist/setup/onboarding.js

@@ -0,0 +1,289 @@
+import { logger } from "../console/logger.js";
+import "../utils/constants.js";
+import { displayHeader, getLastExitError, logErrorAndExit, stripAnsi } from "../console/logging.js";
+import findFilepath from "../fs/findFilepath.js";
+import { withJsonExtension } from "../fs/config/loadConfig.js";
+import { SETUP_FILE_FORMATS } from "../formats/files/supportedFiles.js";
+import { getFrameworkDisplayName, getReactFrameworkLibrary } from "./frameworkUtils.js";
+import { SUPPORTED_REACT_FRAMEWORKS } from "../types/index.js";
+import { getBuildToolSetup } from "./buildTools/index.js";
+import { NoPackageManagerError, getPackageManager, packageManagers } from "../utils/packageManager.js";
+import { installPackage } from "../utils/installPackage.js";
+import { createDiagnosticMessage, formatDiagnosticErrorDetails } from "generaltranslation/internal";
+import fs from "node:fs";
+import { Option } from "commander";
+//#region src/setup/onboarding.ts
+/** Flags for every configuration question; values prefill interactive runs. */
+function attachConfigureFlags(command, sourceHelp) {
+	return reportJsonArgumentErrors(command).option("--src <paths...>", sourceHelp).option("-c, --config <path>", "Filepath to config file, by default gt.config.json", findFilepath(["gt.config.json"])).option("--no-interactive", "Never prompt; fail listing the options still needed. Automatic when stdin or stdout is not a terminal").option("--json", "Write JSON events (sign-in, handoff, result) to stdout and all other output to stderr; implies --no-interactive").option("--defaults", "Accept the recommended value for every local choice that no flag or gt.config.json answers; never creates projects or keys").option("--no-defaults", "Do not offer the recommended defaults").option("--default-locale <locale>", "Default locale, e.g. en").option("--locales <locales...>", "Locales to translate into, e.g. fr es; replaces the configured list").addOption(new Option("--storage <storage>", "Where GT translations are stored for GT runtimes").choices(["local", "cdn"])).option("--translations-dir <path>", "Directory for local GT translation files").addOption(new Option("--file-formats <formats...>", "Additional file formats to translate, or none").choices([...SETUP_FILE_FORMATS, "none"])).option("--file-patterns <patterns...>", "Glob patterns as <format>=<glob> including [locale], e.g. json=./locales/[locale]/*.json; selects the format").option("--live-translations", "Local Vite storage: set up live development translations (creates a development key)").option("--no-live-translations", "Skip live development translations").option("--dev-credentials", "Save a project ID and a new development key to .env.local").option("--no-dev-credentials", "Do not create development credentials").option("--project-id <id>", "Existing project for the development credentials").option("--create-project", "Create a new project for the development credentials").option("--org-id <id>", "Organization that owns --create-project").option("--project-name <name>", "Name for --create-project").addOption(new Option("--package-manager <id>", "Package manager for installs when it cannot be detected").choices(packageManagers.map((packageManager) => packageManager.id)));
+}
+let commandBeforeOnboarding;
+function reportExitBeforeOnboarding(code) {
+	if (code === 0 || commandBeforeOnboarding === void 0) return;
+	fs.writeSync(process.stdout.fd, `${JSON.stringify({
+		type: "result",
+		command: commandBeforeOnboarding,
+		outcome: "failed",
+		completedSteps: [],
+		error: stripAnsi(getLastExitError() ?? "Setup exited before it started; see stderr")
+	})}\n`);
+}
+/**
+* Pre-action hooks, such as the monorepo version check, can exit before
+* runOnboarding installs its own result reporting; `--json` callers still
+* get a result. runOnboarding takes over once it starts.
+*/
+function reportJsonExitsBeforeOnboarding(command) {
+	commandBeforeOnboarding = command;
+	process.once("exit", reportExitBeforeOnboarding);
+}
+/**
+* Argument errors happen before the action runs, so `--json` callers would
+* otherwise get no result. Commander prints the error to stderr, then calls
+* this exit hook; returning lets it exit with the same code as before. The
+* hook replaces an exit override inherited from the program.
+*/
+function reportJsonArgumentErrors(command) {
+	return command.exitOverride((error) => {
+		if (error.exitCode === 0) return;
+		if (!(command.opts().json === true || process.argv.includes("--json"))) return;
+		fs.writeSync(process.stdout.fd, `${JSON.stringify({
+			type: "result",
+			command: command.name(),
+			outcome: "failed",
+			completedSteps: [],
+			error: stripAnsi(error.message)
+		})}\n`);
+	});
+}
+/** Configuration flags plus the React application setup and Locadex choices. */
+function attachInitFlags(command, sourceHelp) {
+	return attachConfigureFlags(command, sourceHelp).option("--locadex", "Mintlify and Next.js App Router: hand setup to the Locadex AI agent through GitHub instead").option("--no-locadex", "Set up this project locally").option("--react-setup", "React projects: install the GT library and add GTProvider or initializeGTSPA").option("--no-react-setup", "Do not modify application source").addOption(new Option("--framework <framework>", "React framework for --react-setup; overrides detection").choices(SUPPORTED_REACT_FRAMEWORKS)).option("--format", "Next.js App Router: format files changed by setup with the detected formatter").option("--no-format", "Leave files changed by setup unformatted");
+}
+/** Needs-input and validation failures, raised before setup changes files. */
+var OnboardingError = class extends Error {
+	constructor(message, missingOptions = []) {
+		super(message);
+		this.missingOptions = missingOptions;
+		this.name = "OnboardingError";
+	}
+};
+function isInteractiveTerminal() {
+	return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+/**
+* One setup run: how unanswered questions are resolved, which options are
+* still missing, and which steps already changed the project.
+*/
+var OnboardingSession = class {
+	interactive;
+	json;
+	defaults = false;
+	completedSteps = [];
+	/** Manual steps left for a person; they make the outcome needs_human_action. */
+	humanActions = [];
+	missing = /* @__PURE__ */ new Set();
+	invalid = [];
+	reported = false;
+	constructor(command, options) {
+		this.command = command;
+		this.json = options.json === true;
+		this.interactive = options.interactive !== false && !this.json && isInteractiveTerminal();
+	}
+	/**
+	* Explicit flag, then existing config, then the recommended value when
+	* defaults were accepted, then a prompt. Noninteractive runs use the
+	* fallback of an optional question, or record the option as missing.
+	*/
+	async answer(option, { explicit, configured, recommended, fallback, ask }) {
+		if (explicit !== void 0) return explicit;
+		if (configured !== void 0) return configured;
+		if (this.defaults && recommended !== void 0) return recommended;
+		if (this.interactive) return ask();
+		if (fallback !== void 0) return fallback;
+		this.require(option);
+	}
+	require(option) {
+		this.missing.add(option);
+	}
+	reject(problem) {
+		this.invalid.push(problem);
+	}
+	/** Stops before any change when an answer is missing or invalid. */
+	assertResolved() {
+		if (this.missing.size === 0 && this.invalid.length === 0) return;
+		const missingOptions = [...this.missing];
+		throw new OnboardingError(createDiagnosticMessage({
+			source: "gt",
+			severity: "Error",
+			whatHappened: missingOptions.length > 0 ? `Setup needs these options: ${missingOptions.join(", ")}` : "Setup received invalid options",
+			reassurance: "No project files were changed",
+			details: this.invalid,
+			fix: "Pass the options (see --help), add --defaults to accept the recommended local choices, or rerun in an interactive terminal"
+		}), missingOptions);
+	}
+	step(name) {
+		this.completedSteps.push(name);
+	}
+	emit(event) {
+		if (!this.json) return;
+		if (event.type === "result") this.reported = true;
+		fs.writeSync(process.stdout.fd, `${JSON.stringify(event)}\n`);
+	}
+	/** A result for exits that bypass runOnboarding (e.g. settings validation). */
+	reportUnexpectedExit(code) {
+		if (this.reported || code === 0) return;
+		this.emit({
+			type: "result",
+			command: this.command,
+			outcome: "failed",
+			completedSteps: this.completedSteps,
+			error: stripAnsi(getLastExitError() ?? "Setup exited before it finished; see stderr")
+		});
+	}
+};
+function partialSetupWarning(session) {
+	return createDiagnosticMessage({
+		source: "gt",
+		severity: "Warning",
+		whatHappened: `Setup stopped after these steps: ${session.completedSteps.join(", ")}`,
+		why: "the error below happened before the remaining steps ran",
+		fix: `Review those changes, fix the error, then rerun \`gt ${session.command}\`; it reuses the saved configuration and credentials`
+	});
+}
+/**
+* Runs one setup command: selects prompt and output modes, then reports the
+* outcome. Failures exit nonzero with the steps that already ran.
+*/
+async function runOnboarding(command, options, run) {
+	commandBeforeOnboarding = void 0;
+	process.removeListener("exit", reportExitBeforeOnboarding);
+	const session = new OnboardingSession(command, options);
+	if (session.json) logger.setConsoleOutput("stderr");
+	const progressWasAnimated = logger.setAnimatedProgress(session.interactive);
+	const reportExit = (code) => session.reportUnexpectedExit(code);
+	process.once("exit", reportExit);
+	try {
+		const result = await run(session);
+		const needsHuman = result.outcome === "needs_human_action" || session.humanActions.length > 0;
+		session.emit({
+			type: "result",
+			command,
+			outcome: needsHuman ? "needs_human_action" : "success",
+			completedSteps: session.completedSteps,
+			...result.outcome === "needs_human_action" && { url: result.url },
+			...session.humanActions.length > 0 && { actions: session.humanActions }
+		});
+	} catch (error) {
+		const message = error instanceof Error ? error.message : formatDiagnosticErrorDetails(error) ?? "Setup failed";
+		session.emit({
+			type: "result",
+			command,
+			outcome: "failed",
+			completedSteps: session.completedSteps,
+			error: stripAnsi(message),
+			...error instanceof OnboardingError && error.missingOptions.length > 0 && { missingOptions: error.missingOptions }
+		});
+		if (session.completedSteps.length > 0) logger.warn(partialSetupWarning(session));
+		return logErrorAndExit(message);
+	} finally {
+		process.removeListener("exit", reportExit);
+		logger.setAnimatedProgress(progressWasAnimated);
+	}
+}
+function asRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+/** Reads the setup config, failing before any change when it is unusable. */
+function readSetupConfig(configFilepath) {
+	if (!fs.existsSync(configFilepath)) return {};
+	try {
+		const config = asRecord(JSON.parse(fs.readFileSync(configFilepath, "utf8")));
+		if (config) return config;
+		throw new Error("the file does not contain a JSON object");
+	} catch (error) {
+		throw new OnboardingError(createDiagnosticMessage({
+			source: "gt",
+			severity: "Error",
+			whatHappened: `${configFilepath} is not a valid JSON config`,
+			reassurance: "No project files were changed",
+			details: formatDiagnosticErrorDetails(error),
+			fix: "Fix or remove the file, then rerun the command"
+		}));
+	}
+}
+const INIT_SOURCE_HELP = "Space-separated list of glob patterns containing the app's source code, by default 'src/**/*.{js,jsx,ts,tsx}' 'app/**/*.{js,jsx,ts,tsx}' 'pages/**/*.{js,jsx,ts,tsx}' 'components/**/*.{js,jsx,ts,tsx}'";
+function setupConfigPath(options) {
+	return options.config ? withJsonExtension(options.config) : "gt.config.json";
+}
+function getConfiguredFramework(config) {
+	const framework = config.framework;
+	return typeof framework === "string" && [...SUPPORTED_REACT_FRAMEWORKS, "mintlify"].includes(framework) ? framework : void 0;
+}
+/** JSON mode keeps the banner off stdout. */
+function displaySetupHeader(session, message) {
+	if (session.json) logger.startCommand(message);
+	else displayHeader(message);
+}
+function describeDefaults(framework) {
+	const buildTool = getBuildToolSetup(framework?.name);
+	const translationsDir = buildTool?.defaultTranslationsDir ?? "./public/_gt";
+	if (framework?.type !== "react") return `Files saved locally in ${translationsDir}`;
+	return `${getReactFrameworkLibrary(framework)} & ${buildTool?.initializer ?? "GTProvider"}, ${getFrameworkDisplayName(framework)}, Files saved locally in ${translationsDir}`;
+}
+/** Setup patterns name where each locale's files live, so they need [locale]. */
+function validateSetupPattern(pattern) {
+	return pattern.includes("[locale]") || `"${pattern}" must include [locale], e.g. ./locales/[locale]/*.json`;
+}
+/** Parses `--file-patterns <format>=<glob>` values, grouped by format. */
+function parseFilePatterns(session, values = []) {
+	const patterns = /* @__PURE__ */ new Map();
+	for (const value of values) {
+		const separator = value.indexOf("=");
+		const format = value.slice(0, separator);
+		const pattern = value.slice(separator + 1).trim();
+		if (separator < 0 || !SETUP_FILE_FORMATS.includes(format) || !pattern) {
+			session.reject(`--file-patterns "${value}" must look like <format>=<glob> with a format of ${SETUP_FILE_FORMATS.join(", ")}`);
+			continue;
+		}
+		const problem = validateSetupPattern(pattern);
+		if (problem !== true) {
+			session.reject(`--file-patterns "${value}": ${problem}`);
+			continue;
+		}
+		patterns.set(format, [...patterns.get(format) ?? [], pattern]);
+	}
+	return patterns;
+}
+/** Detects the package manager, or asks only when prompts are allowed. */
+async function resolvePackageManager(session, specified) {
+	try {
+		return await getPackageManager(process.cwd(), specified, !session.interactive);
+	} catch (error) {
+		if (!(error instanceof NoPackageManagerError)) throw error;
+		session.require("--package-manager");
+		return;
+	}
+}
+async function installWithProgress(session, packageName, packageManager, asDevDependency) {
+	const spinner = logger.createSpinner("timer");
+	spinner.start(`Installing ${packageName}${asDevDependency ? " as a dev dependency" : ""} with ${packageManager.name}...`);
+	try {
+		await installPackage(packageName, packageManager, asDevDependency);
+	} catch (error) {
+		spinner.stop(`Could not install ${packageName}.`, 2);
+		throw new Error(createDiagnosticMessage({
+			source: "gt",
+			severity: "Error",
+			whatHappened: `Failed to install ${packageName}`,
+			details: formatDiagnosticErrorDetails(error),
+			fix: `Install it with \`${packageManager.name} ${packageManager.installCommand} ${packageName}\`, then rerun the command`
+		}));
+	}
+	spinner.stop(`Installed ${packageName}.`);
+	session.step(`installed ${packageName}`);
+}
+//#endregion
+export { INIT_SOURCE_HELP, OnboardingError, OnboardingSession, asRecord, attachConfigureFlags, attachInitFlags, describeDefaults, displaySetupHeader, getConfiguredFramework, installWithProgress, parseFilePatterns, readSetupConfig, reportJsonExitsBeforeOnboarding, resolvePackageManager, runOnboarding, setupConfigPath, validateSetupPattern };
+
+//# sourceMappingURL=onboarding.js.map

package/dist/setup/onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.js","names":[],"sources":["../../src/setup/onboarding.ts"],"sourcesContent":["import fs from 'node:fs';\nimport { Command, Option, type CommanderError } from 'commander';\nimport {\n  createDiagnosticMessage,\n  formatDiagnosticErrorDetails,\n} from 'generaltranslation/internal';\nimport findFilepath from '../fs/findFilepath.js';\nimport { withJsonExtension } from '../fs/config/loadConfig.js';\nimport { logger } from '../console/logger.js';\nimport {\n  displayHeader,\n  getLastExitError,\n  logErrorAndExit,\n  stripAnsi,\n} from '../console/logging.js';\nimport {\n  SUPPORTED_REACT_FRAMEWORKS,\n  type FrameworkObject,\n  type SupportedReactFrameworks,\n} from '../types/index.js';\nimport { DEFAULT_TRANSLATIONS_DIR } from '../utils/constants.js';\nimport { getBuildToolSetup } from './buildTools/index.js';\nimport {\n  getFrameworkDisplayName,\n  getReactFrameworkLibrary,\n} from './frameworkUtils.js';\nimport {\n  SETUP_FILE_FORMATS,\n  type SetupFileFormat,\n} from '../formats/files/supportedFiles.js';\nimport {\n  getPackageManager,\n  NoPackageManagerError,\n  packageManagers,\n  type PackageManager,\n} from '../utils/packageManager.js';\nimport { installPackage } from '../utils/installPackage.js';\n\n/** Answers accepted by `gt configure` (and the gt-vue `gt init`). */\nexport type ConfigureOptions = {\n  config: string;\n  src?: string[];\n  interactive?: boolean;\n  json?: boolean;\n  defaults?: boolean;\n  defaultLocale?: string;\n  locales?: string[];\n  storage?: 'local' | 'cdn';\n  translationsDir?: string;\n  fileFormats?: Array<SetupFileFormat | 'none'>;\n  filePatterns?: string[];\n  liveTranslations?: boolean;\n  devCredentials?: boolean;\n  projectId?: string;\n  createProject?: boolean;\n  orgId?: string;\n  projectName?: string;\n  packageManager?: string;\n};\n\n/** Answers accepted by the React-aware `gt init`. */\nexport type InitOptions = ConfigureOptions & {\n  locadex?: boolean;\n  reactSetup?: boolean;\n  framework?: SupportedReactFrameworks;\n  format?: boolean;\n};\n\n/** Flags for every configuration question; values prefill interactive runs. */\nexport function attachConfigureFlags(\n  command: Command,\n  sourceHelp: string\n): Command {\n  return reportJsonArgumentErrors(command)\n    .option('--src <paths...>', sourceHelp)\n    .option(\n      '-c, --config <path>',\n      'Filepath to config file, by default gt.config.json',\n      findFilepath(['gt.config.json'])\n    )\n    .option(\n      '--no-interactive',\n      'Never prompt; fail listing the options still needed. Automatic when stdin or stdout is not a terminal'\n    )\n    .option(\n      '--json',\n      'Write JSON events (sign-in, handoff, result) to stdout and all other output to stderr; implies --no-interactive'\n    )\n    .option(\n      '--defaults',\n      'Accept the recommended value for every local choice that no flag or gt.config.json answers; never creates projects or keys'\n    )\n    .option('--no-defaults', 'Do not offer the recommended defaults')\n    .option('--default-locale <locale>', 'Default locale, e.g. en')\n    .option(\n      '--locales <locales...>',\n      'Locales to translate into, e.g. fr es; replaces the configured list'\n    )\n    .addOption(\n      new Option(\n        '--storage <storage>',\n        'Where GT translations are stored for GT runtimes'\n      ).choices(['local', 'cdn'])\n    )\n    .option(\n      '--translations-dir <path>',\n      'Directory for local GT translation files'\n    )\n    .addOption(\n      new Option(\n        '--file-formats <formats...>',\n        'Additional file formats to translate, or none'\n      ).choices([...SETUP_FILE_FORMATS, 'none'])\n    )\n    .option(\n      '--file-patterns <patterns...>',\n      'Glob patterns as <format>=<glob> including [locale], e.g. json=./locales/[locale]/*.json; selects the format'\n    )\n    .option(\n      '--live-translations',\n      'Local Vite storage: set up live development translations (creates a development key)'\n    )\n    .option('--no-live-translations', 'Skip live development translations')\n    .option(\n      '--dev-credentials',\n      'Save a project ID and a new development key to .env.local'\n    )\n    .option('--no-dev-credentials', 'Do not create development credentials')\n    .option(\n      '--project-id <id>',\n      'Existing project for the development credentials'\n    )\n    .option(\n      '--create-project',\n      'Create a new project for the development credentials'\n    )\n    .option('--org-id <id>', 'Organization that owns --create-project')\n    .option('--project-name <name>', 'Name for --create-project')\n    .addOption(\n      new Option(\n        '--package-manager <id>',\n        'Package manager for installs when it cannot be detected'\n      ).choices(packageManagers.map((packageManager) => packageManager.id))\n    );\n}\n\nlet commandBeforeOnboarding: string | undefined;\n\nfunction reportExitBeforeOnboarding(code: number): void {\n  if (code === 0 || commandBeforeOnboarding === undefined) return;\n  fs.writeSync(\n    process.stdout.fd,\n    `${JSON.stringify({\n      type: 'result',\n      command: commandBeforeOnboarding,\n      outcome: 'failed',\n      completedSteps: [],\n      error: stripAnsi(\n        getLastExitError() ?? 'Setup exited before it started; see stderr'\n      ),\n    } satisfies OnboardingEvent)}\\n`\n  );\n}\n\n/**\n * Pre-action hooks, such as the monorepo version check, can exit before\n * runOnboarding installs its own result reporting; `--json` callers still\n * get a result. runOnboarding takes over once it starts.\n */\nexport function reportJsonExitsBeforeOnboarding(command: string): void {\n  commandBeforeOnboarding = command;\n  process.once('exit', reportExitBeforeOnboarding);\n}\n\n/**\n * Argument errors happen before the action runs, so `--json` callers would\n * otherwise get no result. Commander prints the error to stderr, then calls\n * this exit hook; returning lets it exit with the same code as before. The\n * hook replaces an exit override inherited from the program.\n */\nfunction reportJsonArgumentErrors(command: Command): Command {\n  return command.exitOverride((error: CommanderError) => {\n    if (error.exitCode === 0) return; // help and version output\n    // An option after the failing argument is not parsed yet.\n    const json =\n      command.opts().json === true || process.argv.includes('--json');\n    if (!json) return;\n    fs.writeSync(\n      process.stdout.fd,\n      `${JSON.stringify({\n        type: 'result',\n        command: command.name(),\n        outcome: 'failed',\n        completedSteps: [],\n        error: stripAnsi(error.message),\n      } satisfies OnboardingEvent)}\\n`\n    );\n  });\n}\n\n/** Configuration flags plus the React application setup and Locadex choices. */\nexport function attachInitFlags(command: Command, sourceHelp: string) {\n  return attachConfigureFlags(command, sourceHelp)\n    .option(\n      '--locadex',\n      'Mintlify and Next.js App Router: hand setup to the Locadex AI agent through GitHub instead'\n    )\n    .option('--no-locadex', 'Set up this project locally')\n    .option(\n      '--react-setup',\n      'React projects: install the GT library and add GTProvider or initializeGTSPA'\n    )\n    .option('--no-react-setup', 'Do not modify application source')\n    .addOption(\n      new Option(\n        '--framework <framework>',\n        'React framework for --react-setup; overrides detection'\n      ).choices(SUPPORTED_REACT_FRAMEWORKS)\n    )\n    .option(\n      '--format',\n      'Next.js App Router: format files changed by setup with the detected formatter'\n    )\n    .option('--no-format', 'Leave files changed by setup unformatted');\n}\n\nexport type OnboardingEvent =\n  | {\n      type: 'authorization_required';\n      verificationUri: string;\n      verificationUriComplete?: string;\n      userCode: string;\n    }\n  | { type: 'handoff'; url: string; reason: 'locadex' }\n  | {\n      type: 'result';\n      command: string;\n      outcome: 'success' | 'needs_human_action' | 'failed';\n      completedSteps: string[];\n      url?: string;\n      /** Manual steps setup could not do, for needs_human_action. */\n      actions?: string[];\n      missingOptions?: string[];\n      error?: string;\n    };\n\n/** Needs-input and validation failures, raised before setup changes files. */\nexport class OnboardingError extends Error {\n  constructor(\n    message: string,\n    readonly missingOptions: string[] = []\n  ) {\n    super(message);\n    this.name = 'OnboardingError';\n  }\n}\n\nfunction isInteractiveTerminal(): boolean {\n  return process.stdin.isTTY === true && process.stdout.isTTY === true;\n}\n\n/**\n * One setup run: how unanswered questions are resolved, which options are\n * still missing, and which steps already changed the project.\n */\nexport class OnboardingSession {\n  readonly interactive: boolean;\n  readonly json: boolean;\n  defaults = false;\n  readonly completedSteps: string[] = [];\n  /** Manual steps left for a person; they make the outcome needs_human_action. */\n  readonly humanActions: string[] = [];\n  private readonly missing = new Set<string>();\n  private readonly invalid: string[] = [];\n  private reported = false;\n\n  constructor(\n    readonly command: string,\n    options: Pick<ConfigureOptions, 'json' | 'interactive'>\n  ) {\n    this.json = options.json === true;\n    this.interactive =\n      options.interactive !== false && !this.json && isInteractiveTerminal();\n  }\n\n  /**\n   * Explicit flag, then existing config, then the recommended value when\n   * defaults were accepted, then a prompt. Noninteractive runs use the\n   * fallback of an optional question, or record the option as missing.\n   */\n  async answer<T>(\n    option: string,\n    {\n      explicit,\n      configured,\n      recommended,\n      fallback,\n      ask,\n    }: {\n      explicit?: T;\n      configured?: T;\n      recommended?: T;\n      fallback?: T;\n      ask: () => Promise<T>;\n    }\n  ): Promise<T | undefined> {\n    if (explicit !== undefined) return explicit;\n    if (configured !== undefined) return configured;\n    if (this.defaults && recommended !== undefined) return recommended;\n    if (this.interactive) return ask();\n    if (fallback !== undefined) return fallback;\n    this.require(option);\n    return undefined;\n  }\n\n  require(option: string): void {\n    this.missing.add(option);\n  }\n\n  reject(problem: string): void {\n    this.invalid.push(problem);\n  }\n\n  /** Stops before any change when an answer is missing or invalid. */\n  assertResolved(): void {\n    if (this.missing.size === 0 && this.invalid.length === 0) return;\n    const missingOptions = [...this.missing];\n    throw new OnboardingError(\n      createDiagnosticMessage({\n        source: 'gt',\n        severity: 'Error',\n        whatHappened:\n          missingOptions.length > 0\n            ? `Setup needs these options: ${missingOptions.join(', ')}`\n            : 'Setup received invalid options',\n        reassurance: 'No project files were changed',\n        details: this.invalid,\n        fix: 'Pass the options (see --help), add --defaults to accept the recommended local choices, or rerun in an interactive terminal',\n      }),\n      missingOptions\n    );\n  }\n\n  step(name: string): void {\n    this.completedSteps.push(name);\n  }\n\n  emit(event: OnboardingEvent): void {\n    if (!this.json) return;\n    if (event.type === 'result') this.reported = true;\n    // Synchronous so events survive an immediate process.exit.\n    fs.writeSync(process.stdout.fd, `${JSON.stringify(event)}\\n`);\n  }\n\n  /** A result for exits that bypass runOnboarding (e.g. settings validation). */\n  reportUnexpectedExit(code: number): void {\n    if (this.reported || code === 0) return;\n    this.emit({\n      type: 'result',\n      command: this.command,\n      outcome: 'failed',\n      completedSteps: this.completedSteps,\n      error: stripAnsi(\n        getLastExitError() ?? 'Setup exited before it finished; see stderr'\n      ),\n    });\n  }\n}\n\nexport type OnboardingOutcome =\n  | { outcome: 'success' }\n  | { outcome: 'needs_human_action'; url: string };\n\nfunction partialSetupWarning(session: OnboardingSession): string {\n  return createDiagnosticMessage({\n    source: 'gt',\n    severity: 'Warning',\n    whatHappened: `Setup stopped after these steps: ${session.completedSteps.join(', ')}`,\n    why: 'the error below happened before the remaining steps ran',\n    fix: `Review those changes, fix the error, then rerun \\`gt ${session.command}\\`; it reuses the saved configuration and credentials`,\n  });\n}\n\n/**\n * Runs one setup command: selects prompt and output modes, then reports the\n * outcome. Failures exit nonzero with the steps that already ran.\n */\nexport async function runOnboarding(\n  command: string,\n  options: Pick<ConfigureOptions, 'json' | 'interactive'>,\n  run: (session: OnboardingSession) => Promise<OnboardingOutcome>\n): Promise<void> {\n  commandBeforeOnboarding = undefined;\n  process.removeListener('exit', reportExitBeforeOnboarding);\n  const session = new OnboardingSession(command, options);\n  if (session.json) logger.setConsoleOutput('stderr');\n  // Per-run modes; console routing is reset per command by BaseCLI.\n  const progressWasAnimated = logger.setAnimatedProgress(session.interactive);\n  const reportExit = (code: number) => session.reportUnexpectedExit(code);\n  process.once('exit', reportExit);\n  try {\n    const result = await run(session);\n    const needsHuman =\n      result.outcome === 'needs_human_action' ||\n      session.humanActions.length > 0;\n    session.emit({\n      type: 'result',\n      command,\n      outcome: needsHuman ? 'needs_human_action' : 'success',\n      completedSteps: session.completedSteps,\n      ...(result.outcome === 'needs_human_action' && { url: result.url }),\n      ...(session.humanActions.length > 0 && {\n        actions: session.humanActions,\n      }),\n    });\n  } catch (error) {\n    const message =\n      error instanceof Error\n        ? error.message\n        : (formatDiagnosticErrorDetails(error) ?? 'Setup failed');\n    session.emit({\n      type: 'result',\n      command,\n      outcome: 'failed',\n      completedSteps: session.completedSteps,\n      error: stripAnsi(message),\n      ...(error instanceof OnboardingError &&\n        error.missingOptions.length > 0 && {\n          missingOptions: error.missingOptions,\n        }),\n    });\n    if (session.completedSteps.length > 0) {\n      logger.warn(partialSetupWarning(session));\n    }\n    return logErrorAndExit(message);\n  } finally {\n    process.removeListener('exit', reportExit);\n    logger.setAnimatedProgress(progressWasAnimated);\n  }\n}\n\nexport function asRecord(value: unknown): Record<string, unknown> | undefined {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\n/** Reads the setup config, failing before any change when it is unusable. */\nexport function readSetupConfig(\n  configFilepath: string\n): Record<string, unknown> {\n  if (!fs.existsSync(configFilepath)) return {};\n  try {\n    const config = asRecord(\n      JSON.parse(fs.readFileSync(configFilepath, 'utf8'))\n    );\n    if (config) return config;\n    throw new Error('the file does not contain a JSON object');\n  } catch (error) {\n    throw new OnboardingError(\n      createDiagnosticMessage({\n        source: 'gt',\n        severity: 'Error',\n        whatHappened: `${configFilepath} is not a valid JSON config`,\n        reassurance: 'No project files were changed',\n        details: formatDiagnosticErrorDetails(error),\n        fix: 'Fix or remove the file, then rerun the command',\n      })\n    );\n  }\n}\n\nexport const INIT_SOURCE_HELP =\n  \"Space-separated list of glob patterns containing the app's source code, by default 'src/**/*.{js,jsx,ts,tsx}' 'app/**/*.{js,jsx,ts,tsx}' 'pages/**/*.{js,jsx,ts,tsx}' 'components/**/*.{js,jsx,ts,tsx}'\";\n\nexport function setupConfigPath(\n  options: Pick<ConfigureOptions, 'config'>\n): string {\n  return options.config ? withJsonExtension(options.config) : 'gt.config.json';\n}\n\nexport function getConfiguredFramework(\n  config: Record<string, unknown>\n): SupportedReactFrameworks | 'mintlify' | undefined {\n  const framework = config.framework;\n  return typeof framework === 'string' &&\n    [...SUPPORTED_REACT_FRAMEWORKS, 'mintlify'].includes(\n      framework as SupportedReactFrameworks\n    )\n    ? (framework as SupportedReactFrameworks | 'mintlify')\n    : undefined;\n}\n\n/** JSON mode keeps the banner off stdout. */\nexport function displaySetupHeader(\n  session: OnboardingSession,\n  message: string\n) {\n  if (session.json) logger.startCommand(message);\n  else displayHeader(message);\n}\n\nexport function describeDefaults(\n  framework: FrameworkObject | undefined\n): string {\n  const buildTool = getBuildToolSetup(framework?.name);\n  const translationsDir =\n    buildTool?.defaultTranslationsDir ?? DEFAULT_TRANSLATIONS_DIR;\n  if (framework?.type !== 'react') {\n    return `Files saved locally in ${translationsDir}`;\n  }\n  const library = getReactFrameworkLibrary(framework);\n  const setup = buildTool?.initializer ?? 'GTProvider';\n  return `${library} & ${setup}, ${getFrameworkDisplayName(framework)}, Files saved locally in ${translationsDir}`;\n}\n\n/** Setup patterns name where each locale's files live, so they need [locale]. */\nexport function validateSetupPattern(pattern: string): true | string {\n  return (\n    pattern.includes('[locale]') ||\n    `\"${pattern}\" must include [locale], e.g. ./locales/[locale]/*.json`\n  );\n}\n\n/** Parses `--file-patterns <format>=<glob>` values, grouped by format. */\nexport function parseFilePatterns(\n  session: OnboardingSession,\n  values: string[] = []\n): Map<SetupFileFormat, string[]> {\n  const patterns = new Map<SetupFileFormat, string[]>();\n  for (const value of values) {\n    const separator = value.indexOf('=');\n    const format = value.slice(0, separator) as SetupFileFormat;\n    const pattern = value.slice(separator + 1).trim();\n    if (separator < 0 || !SETUP_FILE_FORMATS.includes(format) || !pattern) {\n      session.reject(\n        `--file-patterns \"${value}\" must look like <format>=<glob> with a format of ${SETUP_FILE_FORMATS.join(', ')}`\n      );\n      continue;\n    }\n    const problem = validateSetupPattern(pattern);\n    if (problem !== true) {\n      session.reject(`--file-patterns \"${value}\": ${problem}`);\n      continue;\n    }\n    patterns.set(format, [...(patterns.get(format) ?? []), pattern]);\n  }\n  return patterns;\n}\n\n/** Detects the package manager, or asks only when prompts are allowed. */\nexport async function resolvePackageManager(\n  session: OnboardingSession,\n  specified?: string\n): Promise<PackageManager | undefined> {\n  try {\n    return await getPackageManager(\n      process.cwd(),\n      specified,\n      !session.interactive\n    );\n  } catch (error) {\n    if (!(error instanceof NoPackageManagerError)) throw error;\n    session.require('--package-manager');\n    return undefined;\n  }\n}\n\nexport async function installWithProgress(\n  session: OnboardingSession,\n  packageName: string,\n  packageManager: PackageManager,\n  asDevDependency: boolean\n): Promise<void> {\n  const spinner = logger.createSpinner('timer');\n  spinner.start(\n    `Installing ${packageName}${asDevDependency ? ' as a dev dependency' : ''} with ${packageManager.name}...`\n  );\n  try {\n    await installPackage(packageName, packageManager, asDevDependency);\n  } catch (error) {\n    spinner.stop(`Could not install ${packageName}.`, 2);\n    throw new Error(\n      createDiagnosticMessage({\n        source: 'gt',\n        severity: 'Error',\n        whatHappened: `Failed to install ${packageName}`,\n        details: formatDiagnosticErrorDetails(error),\n        fix: `Install it with \\`${packageManager.name} ${packageManager.installCommand} ${packageName}\\`, then rerun the command`,\n      })\n    );\n  }\n  spinner.stop(`Installed ${packageName}.`);\n  session.step(`installed ${packageName}`);\n}\n"],"mappings":"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"}

package/dist/setup/setupTarget.d.ts

@@ -0,0 +1 @@
+export declare function exitIfUnsupportedSetupTarget(): Promise<void>;

package/dist/setup/setupTarget.js

@@ -0,0 +1,52 @@
+import { isPackageInstalled, searchForPackageJson } from "../utils/packageJson.js";
+import { OnboardingError, asRecord } from "./onboarding.js";
+import path from "node:path";
+import fs from "node:fs";
+import { createDiagnosticMessage } from "generaltranslation/diagnostics";
+import YAML from "yaml";
+//#region src/setup/setupTarget.ts
+const workspaceRootSetupError = createDiagnosticMessage({
+	source: "gt",
+	severity: "Error",
+	whatHappened: "The setup wizard cannot run from a monorepo workspace root",
+	why: "GT must be configured in the specific app you want to localize",
+	fix: "Change to that app's directory and rerun `npx gt@latest`"
+});
+const electronSetupError = createDiagnosticMessage({
+	source: "gt",
+	severity: "Error",
+	whatHappened: "The automatic setup wizard is not ready for Electron applications",
+	docsUrl: "https://generaltranslation.com/docs/react"
+});
+/**
+* Whether workspace package patterns name packages besides the root itself.
+* A single app may list only '.' (or nothing, keeping pnpm settings there).
+*/
+function listsChildPackages(patterns) {
+	if (patterns === void 0 || patterns === null) return false;
+	if (!Array.isArray(patterns)) return true;
+	return patterns.some((pattern) => typeof pattern !== "string" || !/^(?:\.\/?|!.*)$/.test(pattern.trim()));
+}
+function isMonorepoRoot(packageJson) {
+	const pnpmWorkspace = path.join(process.cwd(), "pnpm-workspace.yaml");
+	if (fs.existsSync(pnpmWorkspace)) {
+		let packages;
+		try {
+			packages = asRecord(YAML.parse(fs.readFileSync(pnpmWorkspace, "utf8")))?.packages;
+		} catch {
+			return true;
+		}
+		if (listsChildPackages(packages)) return true;
+	}
+	const workspaces = packageJson?.workspaces;
+	return listsChildPackages(Array.isArray(workspaces) ? workspaces : asRecord(workspaces)?.packages);
+}
+async function exitIfUnsupportedSetupTarget() {
+	const packageJson = await searchForPackageJson();
+	if (packageJson && isPackageInstalled("electron", packageJson, false, true)) throw new OnboardingError(electronSetupError);
+	if (isMonorepoRoot(packageJson)) throw new OnboardingError(workspaceRootSetupError);
+}
+//#endregion
+export { exitIfUnsupportedSetupTarget };
+
+//# sourceMappingURL=setupTarget.js.map

package/dist/setup/setupTarget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupTarget.js","names":[],"sources":["../../src/setup/setupTarget.ts"],"sourcesContent":["import path from 'node:path';\nimport fs from 'node:fs';\nimport YAML from 'yaml';\nimport { createDiagnosticMessage } from 'generaltranslation/diagnostics';\nimport {\n  isPackageInstalled,\n  searchForPackageJson,\n} from '../utils/packageJson.js';\nimport { asRecord, OnboardingError } from './onboarding.js';\n\nconst workspaceRootSetupError = createDiagnosticMessage({\n  source: 'gt',\n  severity: 'Error',\n  whatHappened: 'The setup wizard cannot run from a monorepo workspace root',\n  why: 'GT must be configured in the specific app you want to localize',\n  fix: \"Change to that app's directory and rerun `npx gt@latest`\",\n});\n\nconst electronSetupError = createDiagnosticMessage({\n  source: 'gt',\n  severity: 'Error',\n  whatHappened:\n    'The automatic setup wizard is not ready for Electron applications',\n  docsUrl: 'https://generaltranslation.com/docs/react',\n});\n\n/**\n * Whether workspace package patterns name packages besides the root itself.\n * A single app may list only '.' (or nothing, keeping pnpm settings there).\n */\nfunction listsChildPackages(patterns: unknown): boolean {\n  if (patterns === undefined || patterns === null) return false;\n  if (!Array.isArray(patterns)) return true;\n  return patterns.some(\n    (pattern) =>\n      typeof pattern !== 'string' || !/^(?:\\.\\/?|!.*)$/.test(pattern.trim())\n  );\n}\n\nfunction isMonorepoRoot(packageJson: Record<string, unknown> | null): boolean {\n  const pnpmWorkspace = path.join(process.cwd(), 'pnpm-workspace.yaml');\n  if (fs.existsSync(pnpmWorkspace)) {\n    let packages: unknown;\n    try {\n      packages = asRecord(\n        YAML.parse(fs.readFileSync(pnpmWorkspace, 'utf8'))\n      )?.packages;\n    } catch {\n      return true; // Unreadable: keep refusing, as for any workspace file.\n    }\n    if (listsChildPackages(packages)) return true;\n  }\n  const workspaces = packageJson?.workspaces;\n  return listsChildPackages(\n    Array.isArray(workspaces) ? workspaces : asRecord(workspaces)?.packages\n  );\n}\n\nexport async function exitIfUnsupportedSetupTarget(): Promise<void> {\n  const packageJson = await searchForPackageJson();\n  if (packageJson && isPackageInstalled('electron', packageJson, false, true)) {\n    throw new OnboardingError(electronSetupError);\n  }\n  if (isMonorepoRoot(packageJson)) {\n    throw new OnboardingError(workspaceRootSetupError);\n  }\n}\n"],"mappings":";;;;;;;AAUA,MAAM,0BAA0B,wBAAwB;CACtD,QAAQ;CACR,UAAU;CACV,cAAc;CACd,KAAK;CACL,KAAK;CACN,CAAC;AAEF,MAAM,qBAAqB,wBAAwB;CACjD,QAAQ;CACR,UAAU;CACV,cACE;CACF,SAAS;CACV,CAAC;;;;;AAMF,SAAS,mBAAmB,UAA4B;AACtD,KAAI,aAAa,KAAA,KAAa,aAAa,KAAM,QAAO;AACxD,KAAI,CAAC,MAAM,QAAQ,SAAS,CAAE,QAAO;AACrC,QAAO,SAAS,MACb,YACC,OAAO,YAAY,YAAY,CAAC,kBAAkB,KAAK,QAAQ,MAAM,CAAC,CACzE;;AAGH,SAAS,eAAe,aAAsD;CAC5E,MAAM,gBAAgB,KAAK,KAAK,QAAQ,KAAK,EAAE,sBAAsB;AACrE,KAAI,GAAG,WAAW,cAAc,EAAE;EAChC,IAAI;AACJ,MAAI;AACF,cAAW,SACT,KAAK,MAAM,GAAG,aAAa,eAAe,OAAO,CAAC,CACnD,EAAE;UACG;AACN,UAAO;;AAET,MAAI,mBAAmB,SAAS,CAAE,QAAO;;CAE3C,MAAM,aAAa,aAAa;AAChC,QAAO,mBACL,MAAM,QAAQ,WAAW,GAAG,aAAa,SAAS,WAAW,EAAE,SAChE;;AAGH,eAAsB,+BAA8C;CAClE,MAAM,cAAc,MAAM,sBAAsB;AAChD,KAAI,eAAe,mBAAmB,YAAY,aAAa,OAAO,KAAK,CACzE,OAAM,IAAI,gBAAgB,mBAAmB;AAE/C,KAAI,eAAe,YAAY,CAC7B,OAAM,IAAI,gBAAgB,wBAAwB"}

package/dist/setup/setupViteSPA.d.ts

@@ -4,6 +4,37 @@ type SetupViteSPAOptions = {
     defaultLocale: string;
     locales: string[];
     translationsDir?: string;
+    previousTranslationsDir?: string;
 };
-export declare function setupViteSPA({ appDirectory, configFilepath, defaultLocale, locales, translationsDir, }: SetupViteSPAOptions): Promise<void>;
+/**
+ * Reads the Vite entry and bootstrap without writing, so setup can report an
+ * unsupported layout before changing any file.
+ */
+export declare function inspectViteSPA(appDirectory: string): Promise<{
+    indexHtmlPath: string;
+    sourceDirectory: string;
+    indexHtml: string;
+    script: string;
+    source: string;
+    isAlreadyConfigured: boolean;
+    customBootstrap: string | undefined;
+    bootstrapFilename: string;
+    bootstrapPath: string;
+    entryImport: string;
+}>;
+export type ViteLoaderResult = 'written' | 'custom' | 'missing';
+/**
+ * Points the generated src/loadTranslations.ts at translationsDir and adds
+ * empty locale stubs. Only a template matching the previous config is
+ * refreshed; other existing loaders are left unchanged. An absent loader
+ * is only created with `create`.
+ */
+export declare function writeViteLoader({ appDirectory, defaultLocale, locales, translationsDir, previousTranslationsDir, create, }: Omit<SetupViteSPAOptions, 'configFilepath' | 'translationsDir'> & {
+    translationsDir: string;
+    create: boolean;
+}): Promise<ViteLoaderResult>;
+export declare function setupViteSPA({ appDirectory, configFilepath, defaultLocale, locales, translationsDir, previousTranslationsDir, }: SetupViteSPAOptions): Promise<{
+    loader?: ViteLoaderResult;
+    manualAction?: string;
+}>;
 export {};

package/dist/setup/setupViteSPA.js

@@ -1,7 +1,9 @@
 import { logger } from "../console/logger.js";
+import "../types/libraries.js";
 import path from "node:path";
 import fs from "node:fs";
 import { createDiagnosticMessage } from "generaltranslation/diagnostics";
+import { parse } from "@babel/parser";
 //#region src/setup/setupViteSPA.ts
 const defaultBootstrapFilename = "gt-entry.ts";
 const alternateBootstrapFilename = "gt-bootstrap.ts";
@@ -21,16 +23,27 @@ function getLoaderContent(translationsImport) {
 }
 `;
 }
-function isGeneratedLoader(content) {
-	return /^export default async function loadTranslations\(locale: string\) \{\r?\n  const translations = await import\(`[^`]+\/\$\{locale\}\.json`\);\r?\n  return translations\.default;\r?\n\}\r?\n?$/.test(content);
+/**
+* Top-level statements, or undefined for syntax this inspector cannot parse
+* but Vite may accept, such as decorators.
+*/
+function parseModule(content, filename) {
+	try {
+		return parse(content, {
+			sourceType: "module",
+			plugins: /\.[cm]?ts$/i.test(filename) ? ["typescript"] : ["typescript", "jsx"]
+		}).program.body;
+	} catch {
+		return;
+	}
 }
 function toRelativeImport(fromDirectory, toPath) {
 	const relativePath = path.relative(fromDirectory, toPath).split(path.sep).join(path.posix.sep);
 	return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
 }
-function getEntryImport(appDirectory, sourceDirectory, source) {
+function getEntryPath(appDirectory, source) {
 	const sourcePath = source.replace(/[?#].*$/, "");
-	return toRelativeImport(sourceDirectory, sourcePath.startsWith("/") ? path.resolve(appDirectory, `.${sourcePath}`) : path.resolve(appDirectory, sourcePath)).replace(/\.(?:[cm]?[jt]sx?)$/i, "");
+	return sourcePath.startsWith("/") ? path.resolve(appDirectory, `.${sourcePath}`) : path.resolve(appDirectory, sourcePath);
 }
 function getBootstrapEntry(bootstrap) {
 	return bootstrap.match(/await\s+import\(\s*(['"])([^'"]+)\1\s*\)/)?.[2];
@@ -51,18 +64,29 @@ function getModuleEntry(indexHtml) {
 		fix: "Add a module script for the app entry and rerun `npx gt@latest`"
 	}));
 }
-async function setupViteSPA({ appDirectory, configFilepath, defaultLocale, locales, translationsDir }) {
+/**
+* Reads the Vite entry and bootstrap without writing, so setup can report an
+* unsupported layout before changing any file.
+*/
+async function inspectViteSPA(appDirectory) {
 	const indexHtmlPath = path.join(appDirectory, "index.html");
 	const sourceDirectory = path.join(appDirectory, "src");
 	const indexHtml = await fs.promises.readFile(indexHtmlPath, "utf8");
 	const { script, source } = getModuleEntry(indexHtml);
-	const declaredEntryImport = getEntryImport(appDirectory, sourceDirectory, source);
+	const declaredEntryPath = getEntryPath(appDirectory, source);
+	const declaredEntryImport = toRelativeImport(sourceDirectory, declaredEntryPath).replace(/\.(?:[cm]?[jt]sx?)$/i, "");
 	const configuredBootstrap = source.match(/^\/?src\/(gt-entry\.ts|gt-bootstrap\.ts)(?:[?#].*)?$/)?.[1];
+	let customBootstrap;
+	if (!configuredBootstrap && fs.existsSync(declaredEntryPath)) {
+		const entry = await fs.promises.readFile(declaredEntryPath, "utf8");
+		const mentionsInitializer = entry.includes("initializeGTSPA");
+		if (parseModule(entry, declaredEntryPath)?.some((statement) => statement.type === "ImportDeclaration" && statement.source.value === "gt-react" && statement.importKind !== "type" && statement.specifiers.some((specifier) => specifier.type === "ImportNamespaceSpecifier" && mentionsInitializer || specifier.type === "ImportSpecifier" && specifier.importKind !== "type" && specifier.imported.type === "Identifier" && specifier.imported.name === "initializeGTSPA")) ?? mentionsInitializer) customBootstrap = path.relative(appDirectory, declaredEntryPath);
+	}
 	const isAlreadyConfigured = configuredBootstrap !== void 0;
 	const bootstrapFilename = configuredBootstrap ?? (declaredEntryImport === "./gt-entry" ? alternateBootstrapFilename : defaultBootstrapFilename);
 	const bootstrapPath = path.join(sourceDirectory, bootstrapFilename);
 	let existingBootstrap;
-	if (fs.existsSync(bootstrapPath)) {
+	if (!customBootstrap && fs.existsSync(bootstrapPath)) {
 		existingBootstrap = await fs.promises.readFile(bootstrapPath, "utf8");
 		if (!existingBootstrap.includes("initializeGTSPA")) throw new Error(getBootstrapConflictError(bootstrapFilename));
 	}
@@ -73,22 +97,84 @@ async function setupViteSPA({ appDirectory, configFilepath, defaultLocale, local
 		whatHappened: "The existing Vite bootstrap has no app entry import",
 		fix: "Restore the app entry import and rerun `npx gt@latest`"
 	}));
+	return {
+		indexHtmlPath,
+		sourceDirectory,
+		indexHtml,
+		script,
+		source,
+		isAlreadyConfigured,
+		customBootstrap,
+		bootstrapFilename,
+		bootstrapPath,
+		entryImport
+	};
+}
+/**
+* Points the generated src/loadTranslations.ts at translationsDir and adds
+* empty locale stubs. Only a template matching the previous config is
+* refreshed; other existing loaders are left unchanged. An absent loader
+* is only created with `create`.
+*/
+async function writeViteLoader({ appDirectory, defaultLocale, locales, translationsDir, previousTranslationsDir, create }) {
+	const sourceDirectory = path.join(appDirectory, "src");
+	const translationsPath = path.resolve(appDirectory, translationsDir);
+	const loaderPath = path.join(sourceDirectory, "loadTranslations.ts");
+	const existingLoader = fs.existsSync(loaderPath) ? await fs.promises.readFile(loaderPath, "utf8") : void 0;
+	if (existingLoader === void 0 && !create) return "missing";
+	const content = getLoaderContent(toRelativeImport(sourceDirectory, translationsPath));
+	const previousContent = previousTranslationsDir === void 0 ? void 0 : getLoaderContent(toRelativeImport(sourceDirectory, path.resolve(appDirectory, previousTranslationsDir)));
+	const normalizedLoader = existingLoader?.replace(/\r\n/g, "\n").trimEnd();
+	const custom = existingLoader !== void 0 && normalizedLoader !== content.trimEnd() && normalizedLoader !== previousContent?.trimEnd();
+	await fs.promises.mkdir(translationsPath, { recursive: true });
+	for (const locale of new Set(locales)) {
+		if (locale === defaultLocale) continue;
+		const stubPath = path.join(translationsPath, `${locale}.json`);
+		if (!fs.existsSync(stubPath)) await fs.promises.writeFile(stubPath, "{}\n");
+	}
+	if (custom) return "custom";
+	await fs.promises.writeFile(loaderPath, content);
+	return "written";
+}
+function getLoaderExport(content) {
+	const statements = parseModule(content, "loadTranslations.ts");
+	if (!statements) return void 0;
+	const names = /* @__PURE__ */ new Set();
+	for (const statement of statements) {
+		if (statement.type === "ExportDefaultDeclaration" && statement.declaration.type !== "TSInterfaceDeclaration") names.add("default");
+		if (statement.type !== "ExportNamedDeclaration" || statement.exportKind === "type") continue;
+		for (const specifier of statement.specifiers) if (specifier.type === "ExportSpecifier" && specifier.exportKind !== "type") names.add(specifier.exported.type === "Identifier" ? specifier.exported.name : specifier.exported.value);
+		const declaration = statement.declaration;
+		if (declaration?.type === "FunctionDeclaration" && !declaration.declare && declaration.id) names.add(declaration.id.name);
+		if (declaration?.type === "VariableDeclaration" && !declaration.declare) {
+			for (const variable of declaration.declarations) if (variable.id.type === "Identifier") names.add(variable.id.name);
+		}
+	}
+	if (names.has("default")) return "default";
+	if (names.has("loadTranslations")) return "loadTranslations";
+}
+async function setupViteSPA({ appDirectory, configFilepath, defaultLocale, locales, translationsDir, previousTranslationsDir }) {
+	const { indexHtmlPath, sourceDirectory, indexHtml, script, source, isAlreadyConfigured, customBootstrap, bootstrapFilename, bootstrapPath, entryImport } = await inspectViteSPA(appDirectory);
+	if (customBootstrap) return { manualAction: `Verify the existing GT bootstrap ${customBootstrap} uses ${configFilepath}${translationsDir ? ` and loads translations from ${translationsDir}` : " with CDN loading"}` };
 	await fs.promises.mkdir(sourceDirectory, { recursive: true });
 	let loadTranslationsImport = "";
 	let loadTranslationsOption = "gtConfig";
+	let loader;
 	if (translationsDir) {
-		const translationsPath = path.resolve(appDirectory, translationsDir);
-		const loaderPath = path.join(sourceDirectory, "loadTranslations.ts");
-		const translationsImport = toRelativeImport(sourceDirectory, translationsPath);
-		const existingLoader = fs.existsSync(loaderPath) ? await fs.promises.readFile(loaderPath, "utf8") : void 0;
-		if (!existingLoader || isGeneratedLoader(existingLoader)) await fs.promises.writeFile(loaderPath, getLoaderContent(translationsImport));
-		await fs.promises.mkdir(translationsPath, { recursive: true });
-		for (const locale of new Set(locales)) {
-			if (locale === defaultLocale) continue;
-			const stubPath = path.join(translationsPath, `${locale}.json`);
-			if (!fs.existsSync(stubPath)) await fs.promises.writeFile(stubPath, "{}\n");
-		}
-		loadTranslationsImport = "import loadTranslations from './loadTranslations';\n";
+		loader = await writeViteLoader({
+			appDirectory,
+			defaultLocale,
+			locales,
+			translationsDir,
+			previousTranslationsDir,
+			create: true
+		});
+		const loaderExport = loader === "custom" ? getLoaderExport(await fs.promises.readFile(path.join(sourceDirectory, "loadTranslations.ts"), "utf8")) : "default";
+		if (!loaderExport) return {
+			loader,
+			manualAction: `Update your custom src/loadTranslations.ts to load translations from ${translationsDir} and export a default or named loadTranslations function, then rerun gt init`
+		};
+		loadTranslationsImport = loaderExport === "default" ? "import loadTranslations from './loadTranslations';\n" : "import { loadTranslations } from './loadTranslations';\n";
 		loadTranslationsOption = "{ ...gtConfig, loadTranslations }";
 	}
 	const configImport = toRelativeImport(sourceDirectory, path.resolve(appDirectory, configFilepath));
@@ -104,8 +190,12 @@ await import('${entryImport}');
 		await fs.promises.writeFile(indexHtmlPath, indexHtml.replace(script, updatedScript));
 	}
 	logger.success("Configured initializeGTSPA for this Vite application.");
+	return {
+		loader,
+		...loader === "custom" && { manualAction: `Verify your preserved custom src/loadTranslations.ts loads translations from ${translationsDir}` }
+	};
 }
 //#endregion
-export { setupViteSPA };
+export { inspectViteSPA, setupViteSPA, writeViteLoader };
 
 //# sourceMappingURL=setupViteSPA.js.map