@stencil/cli 5.0.0-alpha.4 → 5.0.0-alpha.5

package/dist/index.d.mts

@@ -11,7 +11,7 @@ type TaskCommand = 'build' | 'docs' | 'generate' | 'g' | 'help' | 'info' | 'migr
 /**
  * All the Boolean options supported by the Stencil CLI
  */
-declare const BOOLEAN_CLI_FLAGS: readonly ["build", "cache", "checkVersion", "ci", "compare", "debug", "dev", "devtools", "docs", "dryRun", "esm", "help", "log", "open", "prerender", "prerenderExternal", "prod", "profile", "serviceWorker", "serve", "skipNodeCheck", "ssr", "verbose", "version", "watch"];
+declare const BOOLEAN_CLI_FLAGS: readonly ["build", "cache", "checkVersion", "ci", "compare", "debug", "dev", "devtools", "docs", "dryRun", "help", "log", "open", "prerender", "prerenderExternal", "profile", "serviceWorker", "serve", "skipNodeCheck", "ssr", "verbose", "version", "watch"];
 /**
  * All the Number options supported by the Stencil CLI
  */

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { LOG_LEVELS } from "@stencil/core/compiler";
-import { buildError, catchError, hasError, isFunction, isOutputTargetDocs, isOutputTargetHydrate, isOutputTargetWww, isString, normalizePath, readOnlyArrayHasStringMember, result, shouldIgnoreError, toCamelCase, validateComponentTag } from "@stencil/core/compiler/utils";
+import { buildError, catchError, hasError, isFunction, isOutputTargetDocs, isOutputTargetSsr, isOutputTargetWww, isString, normalizePath, readOnlyArrayHasStringMember, result, shouldIgnoreError, toCamelCase, validateComponentTag } from "@stencil/core/compiler/utils";
 import { isAbsolute, join, parse, relative } from "path";
 import ts from "typescript";
 import { start } from "@stencil/dev-server";
@@ -18,13 +18,11 @@ const BOOLEAN_CLI_FLAGS = [
 	"devtools",
 	"docs",
 	"dryRun",
-	"esm",
 	"help",
 	"log",
 	"open",
 	"prerender",
 	"prerenderExternal",
-	"prod",
 	"profile",
 	"serviceWorker",
 	"serve",
@@ -561,7 +559,7 @@ const startupCompilerLog = (coreCompiler, config) => {
 *
 * This function applies command-line flags to the config, with CLI flags
 * taking precedence over config file values. This is the canonical place
-* where flag values are translated into config properties.?
+* where flag values are translated into config properties.
 *
 * @param config The config object (from stencil.config.ts or empty)
 * @param flags The parsed CLI flags
@@ -569,13 +567,11 @@ const startupCompilerLog = (coreCompiler, config) => {
 */
 const mergeFlags = (config, flags) => {
 	const merged = { ...config };
-	if (flags.prod === true) merged.devMode = false;
-	else if (flags.dev === true) merged.devMode = true;
+	if (flags.dev === true) merged.devMode = true;
 	if (flags.debug === true || flags.verbose === true) merged.logLevel = "debug";
 	else if (flags.logLevel) merged.logLevel = flags.logLevel;
 	if (typeof flags.watch === "boolean") merged.watch = flags.watch;
-	if (typeof flags.docs === "boolean") merged.buildDocs = flags.docs;
-	if (typeof flags.esm === "boolean") merged.buildDist = flags.esm;
+	if (flags.docs === true) merged._docsFlag = true;
 	if (typeof flags.profile === "boolean") merged.profile = flags.profile;
 	if (typeof flags.log === "boolean") merged.writeLog = flags.log;
 	if (typeof flags.cache === "boolean") merged.enableCache = flags.cache;
@@ -618,6 +614,164 @@ const printCheckVersionResults = async (versionChecker) => {
 	}
 };
 //#endregion
+//#region src/migrations/rules/build-dist-docs.ts
+/**
+* Migration rule for buildDist and buildDocs removal.
+*
+* In Stencil v5, these global config options are replaced with per-output-target
+* `skipInDev` property. This migration:
+* - Detects `buildDist` or `buildDocs` in stencil.config.ts
+* - Removes the property
+* - For `buildDist: true` or `buildDocs: true`, adds `skipInDev: false` to relevant output targets
+*/
+const buildDistDocsRule = {
+	id: "build-dist-docs",
+	name: "buildDist/buildDocs Removal",
+	description: "Remove deprecated buildDist and buildDocs config options",
+	fromVersion: "4.x",
+	toVersion: "5.x",
+	detect(sourceFile) {
+		const matches = [];
+		const visit = (node) => {
+			if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name)) {
+				const propName = node.name.text;
+				if (propName === "buildDist" || propName === "buildDocs") {
+					const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+					const isTrue = node.initializer.kind === ts.SyntaxKind.TrueKeyword;
+					matches.push({
+						node,
+						message: `Deprecated '${propName}' found${isTrue ? " (set to true)" : ""} - will be removed and skipInDev added to output targets`,
+						line: line + 1,
+						column: character + 1
+					});
+				}
+			}
+			ts.forEachChild(node, visit);
+		};
+		visit(sourceFile);
+		return matches;
+	},
+	transform(sourceFile, matches) {
+		if (matches.length === 0) return sourceFile.getFullText();
+		let text = sourceFile.getFullText();
+		const targetTypesNeedingSkipInDev = [];
+		for (const match of matches) {
+			const prop = match.node;
+			const propName = prop.name.text;
+			if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+				if (propName === "buildDist") targetTypesNeedingSkipInDev.push("dist", "dist-custom-elements", "dist-hydrate-script", "loader-bundle", "standalone", "ssr");
+				else if (propName === "buildDocs") targetTypesNeedingSkipInDev.push("docs-readme", "docs-json", "docs-custom", "docs-vscode", "docs-custom-elements-manifest");
+			}
+		}
+		const outputTargetsToModify = [];
+		const findOutputTargets = (node) => {
+			if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === "outputTargets" && ts.isArrayLiteralExpression(node.initializer)) {
+				for (const element of node.initializer.elements) if (ts.isObjectLiteralExpression(element)) {
+					const typeProp = element.properties.find((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "type");
+					if (typeProp && ts.isStringLiteral(typeProp.initializer)) {
+						const targetType = typeProp.initializer.text;
+						if (targetTypesNeedingSkipInDev.includes(targetType)) {
+							if (!element.properties.some((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "skipInDev")) outputTargetsToModify.push(element);
+						}
+					}
+				}
+			}
+			ts.forEachChild(node, findOutputTargets);
+		};
+		findOutputTargets(sourceFile);
+		const allModifications = [];
+		for (const match of matches) {
+			const prop = match.node;
+			const start = prop.getStart();
+			let end = prop.getEnd();
+			const afterProp = text.slice(end).match(/^\s*,/);
+			if (afterProp) end = end + afterProp[0].length;
+			allModifications.push({
+				type: "remove",
+				start,
+				end,
+				node: prop
+			});
+		}
+		for (const target of outputTargetsToModify) {
+			const lastProp = target.properties[target.properties.length - 1];
+			if (lastProp) allModifications.push({
+				type: "addSkipInDev",
+				start: lastProp.getEnd(),
+				end: lastProp.getEnd(),
+				node: target
+			});
+		}
+		allModifications.sort((a, b) => b.start - a.start);
+		for (const mod of allModifications) if (mod.type === "remove") text = text.slice(0, mod.start) + text.slice(mod.end);
+		else if (mod.type === "addSkipInDev") {
+			const firstProp = mod.node.properties[0];
+			let indent = "      ";
+			if (firstProp) {
+				const propStart = firstProp.getStart();
+				const lineStart = text.lastIndexOf("\n", propStart) + 1;
+				const leadingWhitespace = text.slice(lineStart, propStart);
+				if (/^\s+$/.test(leadingWhitespace)) indent = leadingWhitespace;
+			}
+			const afterLastProp = text.slice(mod.start).match(/^(\s*,)?/);
+			const skipLength = afterLastProp && afterLastProp[1] ? afterLastProp[0].length : 0;
+			text = text.slice(0, mod.start) + `,\n${indent}skipInDev: false,` + text.slice(mod.start + skipLength);
+		}
+		text = text.replace(/,\s*\n\s*\n/g, ",\n");
+		text = text.replace(/{\s*\n\s*\n/g, "{\n");
+		return text;
+	}
+};
+//#endregion
+//#region src/migrations/rules/dev-mode.ts
+/**
+* Migration rule for `devMode` config option removal.
+*
+* In Stencil v5, `devMode` is no longer a user-settable config option in `stencil.config.ts`.
+* Build mode is controlled exclusively by the `--dev` CLI flag (default is production).
+* This migration removes `devMode` from the config object.
+*/
+const devModeRule = {
+	id: "dev-mode",
+	name: "devMode Config Removal",
+	description: "Remove deprecated devMode config option - use --dev CLI flag instead",
+	fromVersion: "4.x",
+	toVersion: "5.x",
+	detect(sourceFile) {
+		const matches = [];
+		const visit = (node) => {
+			if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name)) {
+				if (node.name.text === "devMode") {
+					const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+					matches.push({
+						node,
+						message: `Deprecated 'devMode' config option found - build mode is now set via the --dev CLI flag (production is the default)`,
+						line: line + 1,
+						column: character + 1
+					});
+				}
+			}
+			ts.forEachChild(node, visit);
+		};
+		visit(sourceFile);
+		return matches;
+	},
+	transform(sourceFile, matches) {
+		if (matches.length === 0) return sourceFile.getFullText();
+		let text = sourceFile.getFullText();
+		for (const match of [...matches].reverse()) {
+			const node = match.node;
+			const start = node.getFullStart();
+			const end = node.getEnd();
+			let removeEnd = end;
+			const trailingComma = text.slice(end).match(/^\s*,/);
+			if (trailingComma) removeEnd = end + trailingComma[0].length;
+			text = text.slice(0, start) + text.slice(removeEnd);
+		}
+		return text;
+	}
+};
+//#endregion
 //#region src/migrations/rules/encapsulation-api.ts
 /**
 * Migration rule for the @Component encapsulation API change.
@@ -820,6 +974,376 @@ const formAssociatedRule = {
 	}
 };
 //#endregion
+//#region src/migrations/rules/global-style-inject.ts
+/**
+* Migration rule for `extras.addGlobalStyleToComponents` → `global-style` output target `inject`.
+*
+* In v5, the `addGlobalStyleToComponents` extras option is removed. Instead, configure
+* the `inject` option on the `global-style` output target.
+*
+* Migration mapping:
+* - `addGlobalStyleToComponents: true` → `inject: 'all'`
+* - `addGlobalStyleToComponents: 'client'` → `inject: 'client'`
+* - `addGlobalStyleToComponents: false` → omit (default is 'none')
+*
+* Note: This migration only acts on explicitly set `addGlobalStyleToComponents`.
+* Users who relied on the implicit v4 default ('client') will need to manually
+* add `inject: 'client'` to their global-style output target if desired.
+*/
+const globalStyleInjectRule = {
+	id: "global-style-inject",
+	name: "Global Style Inject Migration",
+	description: "Migrate extras.addGlobalStyleToComponents to global-style output target inject option",
+	fromVersion: "4.x",
+	toVersion: "5.x",
+	detect(sourceFile) {
+		const matches = [];
+		const visit = (node) => {
+			if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === "addGlobalStyleToComponents") {
+				const parent = node.parent;
+				if (ts.isObjectLiteralExpression(parent)) {
+					const grandparent = parent.parent;
+					if (ts.isPropertyAssignment(grandparent) && ts.isIdentifier(grandparent.name) && grandparent.name.text === "extras") {
+						const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+						matches.push({
+							node,
+							message: `extras.addGlobalStyleToComponents is removed. Use 'inject' on global-style output target instead.`,
+							line: line + 1,
+							column: character + 1
+						});
+					}
+				}
+			}
+			ts.forEachChild(node, visit);
+		};
+		visit(sourceFile);
+		return matches;
+	},
+	transform(sourceFile, matches) {
+		if (matches.length === 0) return sourceFile.getFullText();
+		let text = sourceFile.getFullText();
+		const matchNode = matches[0].node;
+		if (!ts.isPropertyAssignment(matchNode)) return text;
+		let injectValue = null;
+		if (matchNode.initializer.kind === ts.SyntaxKind.TrueKeyword) injectValue = "all";
+		else if (ts.isStringLiteral(matchNode.initializer) && matchNode.initializer.text === "client") injectValue = "client";
+		let insertionOffset = 0;
+		if (injectValue) {
+			const result = addGlobalStyleOutputTarget(text, sourceFile, injectValue);
+			insertionOffset = result.length - text.length;
+			text = result;
+		}
+		let start = matchNode.getStart();
+		let end = matchNode.getEnd();
+		const outputTargetsEnd = findOutputTargetsEnd(sourceFile);
+		if (insertionOffset !== 0 && outputTargetsEnd !== null && matchNode.getStart() > outputTargetsEnd) {
+			start += insertionOffset;
+			end += insertionOffset;
+		}
+		const afterProp = text.slice(end).match(/^\s*,/);
+		if (afterProp) end = end + afterProp[0].length;
+		else {
+			const beforeProp = text.slice(0, start).match(/,\s*$/);
+			if (beforeProp) {
+				text = text.slice(0, start - beforeProp[0].length) + text.slice(end);
+				end = -1;
+			}
+		}
+		if (end !== -1) text = text.slice(0, start) + text.slice(end);
+		text = cleanupEmptyExtras(text);
+		return text;
+	}
+};
+/**
+* Find the end position of the outputTargets array in the source file.
+* @param sourceFile The source file to search
+* @returns The end position of the outputTargets array, or null if not found
+*/
+function findOutputTargetsEnd(sourceFile) {
+	let endPos = null;
+	const visit = (node) => {
+		if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === "outputTargets") endPos = node.getEnd();
+		ts.forEachChild(node, visit);
+	};
+	visit(sourceFile);
+	return endPos;
+}
+/**
+* Clean up empty extras object after removing addGlobalStyleToComponents.
+* @param text The source text to clean up
+* @returns The cleaned up text with empty extras removed
+*/
+function cleanupEmptyExtras(text) {
+	return text.replace(/,?\s*extras\s*:\s*\{\s*\},?/g, "");
+}
+/**
+* Add a global-style output target with the specified inject value.
+* @param text The source text to modify
+* @param sourceFile The source file for position info
+* @param injectValue The inject value to set on the new global-style output target
+* @returns The modified text with the new global-style output target added
+*/
+function addGlobalStyleOutputTarget(text, sourceFile, injectValue) {
+	if (text.includes("type: 'global-style'")) return text;
+	let outputTargetsArray = null;
+	const findOutputTargets = (node) => {
+		if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === "outputTargets" && ts.isArrayLiteralExpression(node.initializer)) outputTargetsArray = node.initializer;
+		ts.forEachChild(node, findOutputTargets);
+	};
+	findOutputTargets(sourceFile);
+	if (!outputTargetsArray) return text;
+	const array = outputTargetsArray;
+	let indent = "    ";
+	if (array.elements.length > 0) {
+		const elemStart = array.elements[0].getStart();
+		const lineStart = text.lastIndexOf("\n", elemStart) + 1;
+		const leadingWhitespace = text.slice(lineStart, elemStart);
+		if (/^\s+$/.test(leadingWhitespace)) indent = leadingWhitespace;
+	}
+	const lastElement = array.elements[array.elements.length - 1];
+	if (!lastElement) {
+		const arrayStart = array.getStart() + 1;
+		const newTarget = `\n${indent}{\n${indent}  type: 'global-style',\n${indent}  inject: '${injectValue}',\n${indent}}\n${indent.slice(2)}`;
+		return text.slice(0, arrayStart) + newTarget + text.slice(arrayStart);
+	}
+	let insertPos = lastElement.getEnd();
+	const afterLastElement = text.slice(insertPos).match(/^(\s*,)?/);
+	const hasTrailingComma = afterLastElement && afterLastElement[1];
+	if (hasTrailingComma) insertPos += afterLastElement[0].length;
+	const newTarget = `{\n${indent}  type: 'global-style',\n${indent}  inject: '${injectValue}',\n${indent}}`;
+	const insertion = (hasTrailingComma ? "" : ",") + "\n" + indent + newTarget;
+	return text.slice(0, insertPos) + insertion + text.slice(insertPos);
+}
+//#endregion
+//#region src/migrations/rules/output-target-renames.ts
+/**
+* Migration rule for output target renames in Stencil v5.
+*
+* This migration:
+* - Renames `dist` → `loader-bundle`
+* - Renames `dist-custom-elements` → `standalone`
+* - Renames `dist-hydrate-script` → `ssr`
+* - Renames `dist-collection` → `stencil-rebundle`
+* - Renames `dist-types` → `types`
+* - Extracts `collectionDir` from loader-bundle into separate `stencil-rebundle` output
+* - Extracts `typesDir` from loader-bundle into separate `types` output
+* - Renames `esmLoaderPath` → `loaderPath` (applies to all module formats, not just ESM)
+* - Removes `isPrimaryPackageOutputTarget` (no longer needed, package.json validation auto-detects)
+* - Removes `generateTypeDeclarations` (types are now auto-generated via the `types` output target)
+*/
+const outputTargetRenamesRule = {
+	id: "output-target-renames",
+	name: "Output Target Renames",
+	description: "Rename output targets to new v5 names",
+	fromVersion: "4.x",
+	toVersion: "5.x",
+	detect(sourceFile) {
+		const matches = [];
+		const oldToNewNames = {
+			dist: "loader-bundle",
+			"dist-custom-elements": "standalone",
+			"dist-hydrate-script": "ssr",
+			"dist-collection": "stencil-rebundle",
+			"dist-types": "types"
+		};
+		const visit = (node) => {
+			if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === "type" && ts.isStringLiteral(node.initializer)) {
+				const typeValue = node.initializer.text;
+				if (typeValue in oldToNewNames) {
+					const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+					matches.push({
+						node,
+						message: `Output target type '${typeValue}' → '${oldToNewNames[typeValue]}'`,
+						line: line + 1,
+						column: character + 1
+					});
+				}
+			}
+			if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && (node.name.text === "collectionDir" || node.name.text === "typesDir")) {
+				const parent = node.parent;
+				if (ts.isObjectLiteralExpression(parent)) {
+					if (parent.properties.some((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "type")) {
+						const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+						const propName = node.name.text;
+						const newType = propName === "collectionDir" ? "stencil-rebundle" : "types";
+						matches.push({
+							node,
+							message: `Property '${propName}' will be extracted to separate '${newType}' output target`,
+							line: line + 1,
+							column: character + 1
+						});
+					}
+				}
+			}
+			if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === "esmLoaderPath") {
+				const parent = node.parent;
+				if (ts.isObjectLiteralExpression(parent)) {
+					if (parent.properties.some((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "type")) {
+						const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+						matches.push({
+							node,
+							message: `Property 'esmLoaderPath' renamed to 'loaderPath' (applies to all module formats)`,
+							line: line + 1,
+							column: character + 1
+						});
+					}
+				}
+			}
+			if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && (node.name.text === "isPrimaryPackageOutputTarget" || node.name.text === "generateTypeDeclarations")) {
+				const parent = node.parent;
+				if (ts.isObjectLiteralExpression(parent)) {
+					if (parent.properties.some((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "type")) {
+						const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+						const propName = node.name.text;
+						const reason = propName === "isPrimaryPackageOutputTarget" ? "Package.json validation now auto-detects based on configured outputs" : "Types are now auto-generated via the 'types' output target";
+						matches.push({
+							node,
+							message: `Property '${propName}' is removed in v5. ${reason}`,
+							line: line + 1,
+							column: character + 1
+						});
+					}
+				}
+			}
+			ts.forEachChild(node, visit);
+		};
+		visit(sourceFile);
+		return matches;
+	},
+	transform(sourceFile, matches) {
+		if (matches.length === 0) return sourceFile.getFullText();
+		let text = sourceFile.getFullText();
+		const oldToNewNames = {
+			dist: "loader-bundle",
+			"dist-custom-elements": "standalone",
+			"dist-hydrate-script": "ssr",
+			"dist-collection": "stencil-rebundle",
+			"dist-types": "types"
+		};
+		const outputTargetsToExtract = [];
+		const findOutputTargetsToExtract = (node) => {
+			if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === "outputTargets" && ts.isArrayLiteralExpression(node.initializer)) {
+				for (const element of node.initializer.elements) if (ts.isObjectLiteralExpression(element)) {
+					let collectionDir;
+					let typesDir;
+					for (const prop of element.properties) if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+						if (prop.name.text === "collectionDir" && ts.isStringLiteral(prop.initializer)) collectionDir = prop.initializer.text;
+						else if (prop.name.text === "typesDir" && ts.isStringLiteral(prop.initializer)) typesDir = prop.initializer.text;
+					}
+					if (collectionDir || typesDir) outputTargetsToExtract.push({
+						targetNode: element,
+						collectionDir,
+						typesDir
+					});
+				}
+			}
+			ts.forEachChild(node, findOutputTargetsToExtract);
+		};
+		findOutputTargetsToExtract(sourceFile);
+		const modifications = [];
+		for (const match of matches) {
+			const prop = match.node;
+			const propName = prop.name.text;
+			if (propName === "type" && ts.isStringLiteral(prop.initializer)) {
+				const newType = oldToNewNames[prop.initializer.text];
+				if (newType) {
+					const start = prop.initializer.getStart() + 1;
+					const end = prop.initializer.getEnd() - 1;
+					modifications.push({
+						type: "replace",
+						start,
+						end,
+						replacement: newType
+					});
+				}
+			} else if (propName === "esmLoaderPath") {
+				const nameNode = prop.name;
+				modifications.push({
+					type: "replace",
+					start: nameNode.getStart(),
+					end: nameNode.getEnd(),
+					replacement: "loaderPath"
+				});
+				if (ts.isStringLiteral(prop.initializer)) {
+					const newPath = "../" + prop.initializer.text;
+					modifications.push({
+						type: "replace",
+						start: prop.initializer.getStart() + 1,
+						end: prop.initializer.getEnd() - 1,
+						replacement: newPath
+					});
+				}
+			} else if (propName === "collectionDir" || propName === "typesDir" || propName === "isPrimaryPackageOutputTarget" || propName === "generateTypeDeclarations") {
+				const start = prop.getStart();
+				let end = prop.getEnd();
+				const beforeProp = text.slice(0, start).match(/,\s*$/);
+				const afterProp = text.slice(end).match(/^\s*,/);
+				if (afterProp) end = end + afterProp[0].length;
+				else if (beforeProp) {
+					const commaStart = start - beforeProp[0].length;
+					modifications.push({
+						type: "remove",
+						start: commaStart,
+						end
+					});
+					continue;
+				}
+				modifications.push({
+					type: "remove",
+					start,
+					end
+				});
+			}
+		}
+		modifications.sort((a, b) => b.start - a.start);
+		for (const mod of modifications) if (mod.type === "replace") text = text.slice(0, mod.start) + mod.replacement + text.slice(mod.end);
+		else if (mod.type === "remove") text = text.slice(0, mod.start) + text.slice(mod.end);
+		if (outputTargetsToExtract.length > 0) text = addExtractedOutputTargets(text, sourceFile, outputTargetsToExtract);
+		text = text.replace(/,\s*\n\s*\n/g, ",\n");
+		text = text.replace(/{\s*\n\s*\n/g, "{\n");
+		text = text.replace(/,\s*,/g, ",");
+		return text;
+	}
+};
+/**
+* Add new output targets for extracted collectionDir and typesDir.
+* @param text The original source text
+* @param sourceFile The TypeScript source file object
+* @param toExtract An array of objects containing the output target nodes and their collectionDir/typesDir values to extract
+* @returns The modified source text with new output targets added
+*/
+function addExtractedOutputTargets(text, sourceFile, toExtract) {
+	let outputTargetsArray = null;
+	const findOutputTargets = (node) => {
+		if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === "outputTargets" && ts.isArrayLiteralExpression(node.initializer)) outputTargetsArray = node.initializer;
+		ts.forEachChild(node, findOutputTargets);
+	};
+	findOutputTargets(sourceFile);
+	if (!outputTargetsArray || toExtract.length === 0) return text;
+	const array = outputTargetsArray;
+	let indent = "    ";
+	if (array.elements.length > 0) {
+		const elemStart = array.elements[0].getStart();
+		const lineStart = text.lastIndexOf("\n", elemStart) + 1;
+		const leadingWhitespace = text.slice(lineStart, elemStart);
+		if (/^\s+$/.test(leadingWhitespace)) indent = leadingWhitespace;
+	}
+	const lastElement = array.elements[array.elements.length - 1];
+	if (!lastElement) return text;
+	let insertPos = lastElement.getEnd();
+	const afterLastElement = text.slice(insertPos).match(/^(\s*,)?/);
+	if (afterLastElement && afterLastElement[1]) insertPos += afterLastElement[0].length;
+	const newTargets = [];
+	for (const extracted of toExtract) {
+		if (extracted.collectionDir) newTargets.push(`{\n${indent}  type: 'stencil-rebundle',\n${indent}  dir: '${extracted.collectionDir}',\n${indent}}`);
+		if (extracted.typesDir) newTargets.push(`{\n${indent}  type: 'types',\n${indent}  dir: '${extracted.typesDir}',\n${indent}}`);
+	}
+	if (newTargets.length === 0) return text;
+	const insertion = ",\n" + newTargets.map((t) => `${indent}${t}`).join(",\n");
+	text = text.slice(0, insertPos) + insertion + text.slice(insertPos);
+	return text;
+}
+//#endregion
 //#region src/migrations/index.ts
 /**
 * Build a map of local import names to their original names from @stencil/core.
@@ -857,7 +1381,14 @@ const isStencilDecorator = (decoratorName, expectedOriginalName, importMap) => {
 * Registry of all available migration rules.
 * Rules are applied in order, so add new rules at the end.
 */
-const migrationRules = [encapsulationApiRule, formAssociatedRule];
+const migrationRules = [
+	encapsulationApiRule,
+	formAssociatedRule,
+	buildDistDocsRule,
+	outputTargetRenamesRule,
+	devModeRule,
+	globalStyleInjectRule
+];
 /**
 * Get all migration rules for a specific version upgrade.
 * @param fromVersion Source version (e.g., '4')
@@ -1041,27 +1572,32 @@ async function getTypeScriptFiles(config, sys, logger) {
 		return [];
 	}
 	if (results.errors && results.errors.length > 0) for (const err of results.errors) logger.warn(ts.flattenDiagnosticMessageText(err.messageText, "\n"));
-	return results.fileNames.filter((f) => (f.endsWith(".ts") || f.endsWith(".tsx")) && !f.endsWith(".d.ts"));
+	const files = results.fileNames.filter((f) => (f.endsWith(".ts") || f.endsWith(".tsx")) && !f.endsWith(".d.ts"));
+	const configFile = config.configPath;
+	if (configFile && (configFile.endsWith(".ts") || configFile.endsWith(".mts"))) {
+		if (!files.includes(configFile)) files.push(configFile);
+	}
+	return files;
 }
 //#endregion
 //#region src/task-prerender.ts
 const taskPrerender = async (coreCompiler, config, flags) => {
 	startupCompilerLog(coreCompiler, config);
-	const hydrateAppFilePath = flags.unknownArgs[0];
-	if (typeof hydrateAppFilePath !== "string") {
+	const ssrAppFilePath = flags.unknownArgs[0];
+	if (typeof ssrAppFilePath !== "string") {
 		config.logger.error(`Missing hydrate app script path`);
 		return config.sys.exit(1);
 	}
 	const srcIndexHtmlPath = config.srcIndexHtml;
-	const diagnostics = await runPrerenderTask(coreCompiler, config, hydrateAppFilePath, void 0, srcIndexHtmlPath);
+	const diagnostics = await runPrerenderTask(coreCompiler, config, ssrAppFilePath, void 0, srcIndexHtmlPath);
 	config.logger.printDiagnostics(diagnostics);
 	if (diagnostics.some((d) => d.level === "error")) return config.sys.exit(1);
 };
-const runPrerenderTask = async (coreCompiler, config, hydrateAppFilePath, componentGraph, srcIndexHtmlPath) => {
+const runPrerenderTask = async (coreCompiler, config, ssrAppFilePath, componentGraph, srcIndexHtmlPath) => {
 	const diagnostics = [];
 	try {
 		const results = await (await coreCompiler.createPrerenderer(config)).start({
-			hydrateAppFilePath,
+			ssrAppFilePath,
 			componentGraph,
 			srcIndexHtmlPath
 		});
@@ -1393,7 +1929,7 @@ const anonymizeConfigForTelemetry = (config) => {
 			if (OUTPUT_TARGET_KEYS_TO_KEEP.includes(key)) return value;
 			return "omitted";
 		}));
-		if (isOutputTargetHydrate(target) && target.external) anonymizedOT["external"] = target.external.concat();
+		if (isOutputTargetSsr(target) && target.external) anonymizedOT["external"] = target.external.concat();
 		return anonymizedOT;
 	});
 	for (const prop of CONFIG_PROPS_TO_DELETE) delete anonymizedConfig[prop];
@@ -1587,6 +2123,23 @@ const taskBuild = async (coreCompiler, config, flags) => {
 	let exitCode = 0;
 	try {
 		startupCompilerLog(coreCompiler, config);
+		const preBuildMigrationResult = await detectMigrations(coreCompiler, config);
+		if (preBuildMigrationResult.hasMigrations) {
+			const action = await promptForMigration(config, preBuildMigrationResult, "pre-build");
+			if (action === "run") {
+				await taskMigrate(coreCompiler, config, {
+					...flags,
+					dryRun: false
+				});
+				config.logger.info("\nMigrations applied. Starting build...\n");
+			} else if (action === "dry-run") {
+				await taskMigrate(coreCompiler, config, {
+					...flags,
+					dryRun: true
+				});
+				return config.sys.exit(1);
+			} else return config.sys.exit(1);
+		}
 		const versionChecker = startCheckVersion(config, coreCompiler.version, flags);
 		const compiler = await coreCompiler.createCompiler(config);
 		const results = await compiler.build();
@@ -1595,7 +2148,7 @@ const taskBuild = async (coreCompiler, config, flags) => {
 		if (results.hasError) {
 			const migrationResult = await detectMigrations(coreCompiler, config);
 			if (migrationResult.hasMigrations) {
-				const action = await promptForMigrationOnBuildError(config, migrationResult);
+				const action = await promptForMigration(config, migrationResult, "post-error");
 				if (action === "run") {
 					await taskMigrate(coreCompiler, config, {
 						...flags,
@@ -1608,7 +2161,7 @@ const taskBuild = async (coreCompiler, config, flags) => {
 					if (!newResults.hasError) {
 						exitCode = 0;
 						if (flags.prerender) {
-							const prerenderDiagnostics = await runPrerenderTask(coreCompiler, config, newResults.hydrateAppFilePath, newResults.componentGraph, void 0);
+							const prerenderDiagnostics = await runPrerenderTask(coreCompiler, config, newResults.ssrAppFilePath, newResults.componentGraph, void 0);
 							config.logger.printDiagnostics(prerenderDiagnostics);
 							if (prerenderDiagnostics.some((d) => d.level === "error")) exitCode = 1;
 						}
@@ -1622,7 +2175,7 @@ const taskBuild = async (coreCompiler, config, flags) => {
 				} else exitCode = 1;
 			} else exitCode = 1;
 		} else if (flags.prerender) {
-			const prerenderDiagnostics = await runPrerenderTask(coreCompiler, config, results.hydrateAppFilePath, results.componentGraph, void 0);
+			const prerenderDiagnostics = await runPrerenderTask(coreCompiler, config, results.ssrAppFilePath, results.componentGraph, void 0);
 			config.logger.printDiagnostics(prerenderDiagnostics);
 			if (prerenderDiagnostics.some((d) => d.level === "error")) exitCode = 1;
 		}
@@ -1634,24 +2187,26 @@ const taskBuild = async (coreCompiler, config, flags) => {
 	if (exitCode > 0) return config.sys.exit(exitCode);
 };
 /**
-* Prompt the user about available migrations when a build fails.
+* Prompt the user about available migrations.
 * Shows what migrations are available and lets them choose to run them.
 * @param config the Stencil config
 * @param migrationResult the result of migration detection with available migrations
+* @param context whether this is a pre-build check or post-error check
 * @returns the user's chosen action for handling migrations
 */
-async function promptForMigrationOnBuildError(config, migrationResult) {
+async function promptForMigration(config, migrationResult, context) {
 	const logger = config.logger;
 	logger.info("");
-	logger.info(logger.bold(logger.yellow("Migrations Available")));
+	logger.info(logger.bold(logger.yellow("Migrations Required")));
 	logger.info("─".repeat(40));
-	logger.info(`Found ${migrationResult.totalMatches} item(s) in ${migrationResult.filesAffected} file(s) that can be automatically migrated.`);
+	logger.info(`Found ${migrationResult.totalMatches} item(s) in ${migrationResult.filesAffected} file(s) that need to be migrated for Stencil v5.`);
 	for (const migration of migrationResult.migrations) {
 		const relPath = relative(config.rootDir, migration.filePath);
 		logger.info(`  ${logger.cyan(relPath)}: ${migration.matches.length} item(s)`);
 	}
 	logger.info("");
-	logger.info("These migrations may help resolve the build errors above.");
+	if (context === "pre-build") logger.info("Your config contains deprecated options that must be migrated before building.");
+	else logger.info("These migrations may help resolve the build errors above.");
 	const prompt = (await import("prompts")).default;
 	const response = await prompt({
 		name: "action",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stencil/cli",
-  "version": "5.0.0-alpha.4",
+  "version": "5.0.0-alpha.5",
   "description": "CLI for Stencil - Web component compiler",
   "keywords": [
     "components",
@@ -38,14 +38,14 @@
   },
   "dependencies": {
     "prompts": "^2.4.2",
-    "@stencil/dev-server": "5.0.0-alpha.4"
+    "@stencil/dev-server": "5.0.0-alpha.5"
   },
   "devDependencies": {
     "@types/prompts": "^2.4.9",
-    "tsdown": "^0.21.6",
-    "typescript": "~6.0.2",
+    "tsdown": "^0.21.7",
+    "typescript": ">4.0.0",
     "vitest": "^4.1.1",
-    "@stencil/core": "5.0.0-alpha.4"
+    "@stencil/core": "5.0.0-alpha.5"
   },
   "peerDependencies": {
     "@stencil/core": "^5.0.0-0"