feat: stabilize experimental preserveScriptOrder option (#14480)

Author: florian-lefebvre

.changeset/whole-geckos-think.md

@@ -0,0 +1,51 @@
+---
+'astro': major
+---
+
+Updates `<script>` and `<style>` tags to render in the order they are defined
+
+In Astro v5.5, the `experimental.preserveScriptOrder` flag was introduced to render multiple `<style>` and `<script>` tags in the same order as they were declared in the source code. Astro 5.x reversed their order in your generated HTML output. This could give unexpected results, for example, CSS styles being overridden by earlier defined style tags when your site was built.
+
+Astro 6.0 removes this experimental flag and makes this the new default behavior in Astro: scripts and styles are now rendered in the order defined in your code.
+
+#### What should I do?
+
+If you were previously using this experimental feature, you must remove this experimental flag from your configuration as it no longer exists:
+
+```diff
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  experimental: {
+-    preserveScriptOrder: true,
+  },
+})
+```
+
+Review your `<script>` and `<style>` tags to make sure they behave as desired. You may need to reverse their order:
+
+```diff
+<!-- src/components/MyComponent.astro -->
+<p>I am a component</p>
+<style>
+  body {
+-    background: red;
++    background: yellow;
+  }
+</style>
+<style>
+  body {
+-    background: yellow;
++    background: red;
+  }
+</style>
+<script>
+-    console.log("hello")
++    console.log("world")
+</script>
+<script>
+-    console.log("world!")
++    console.log("hello!")
+</script>
+```

packages/astro/package.json

@@ -106,7 +106,7 @@
     "test:integration": "astro-scripts test \"test/*.test.js\""
   },
   "dependencies": {
-    "@astrojs/compiler": "0.0.0-next-result-create-astro-20250926081949",
+    "@astrojs/compiler": "0.0.0-script-order-20251002140654",
     "@astrojs/internal-helpers": "workspace:*",
     "@astrojs/markdown-remark": "workspace:*",
     "@astrojs/telemetry": "workspace:*",

packages/astro/src/core/compile/compile.ts

@@ -62,7 +62,6 @@ export async function compile({
 				cssPartialCompileResults,
 				cssTransformErrors,
 			}),
-			experimentalScriptOrder: astroConfig.experimental.preserveScriptOrder ?? false,
 			async resolvePath(specifier) {
 				return resolvePath(specifier, filename);
 			},

packages/astro/src/core/config/schemas/base.ts

@@ -97,7 +97,6 @@ export const ASTRO_CONFIG_DEFAULTS = {
 		clientPrerender: false,
 		contentIntellisense: false,
 		headingIdCompat: false,
-		preserveScriptOrder: false,
 		liveContentCollections: false,
 		csp: false,
 		staticImportMetaEnv: false,
@@ -468,10 +467,6 @@ export const AstroConfigSchema = z.object({
 				.boolean()
 				.optional()
 				.default(ASTRO_CONFIG_DEFAULTS.experimental.headingIdCompat),
-			preserveScriptOrder: z
-				.boolean()
-				.optional()
-				.default(ASTRO_CONFIG_DEFAULTS.experimental.preserveScriptOrder),
 			fonts: z.array(z.union([localFontFamilySchema, remoteFontFamilySchema])).optional(),
 			liveContentCollections: z
 				.boolean()

packages/astro/src/types/public/config.ts

@@ -2358,48 +2358,6 @@ export interface ViteUserConfig extends OriginalViteUserConfig {
 					directives?: CspDirective[];
 			  };
 
-		/**
-		 * @name experimental.preserveScriptOrder
-		 * @type {boolean}
-		 * @default `false`
-		 * @version 5.5
-		 * @description
-		 *
-		 * When enabled, `<script>` and `<style>` tags are rendered in the same order as they are defined.
-		 *
-		 * ## Example
-		 *
-		 * Consider the following component:
-		 *
-		 * ```html
-		 * <p>I am a component</p>
-		 * <style>
-		 *   body {
-		 *     background: red;
-		 *   }
-		 * </style>
-		 * <style>
-		 *   body {
-		 *     background: yellow;
-		 *   }
-		 * </style>
-		 * ```
-		 *
-		 * By default, it will generate a CSS style where `red` will be applied:
-		 *
-		 * ```css
-		 * body {background:#ff0} body {background:red}
-		 * ```
-		 *
-		 * When this new option is set to `true`, the generated CSS style will apply `yellow`:
-		 *
-		 * ```css
-		 * body {background:red} body {background:#ff0}
-		 * ```
-		 *
-		 */
-		preserveScriptOrder?: boolean;
-
 		/**
 		 * @name experimental.liveContentCollections
 		 * @type {boolean}

packages/astro/test/astro-directives.test.js

@@ -70,7 +70,7 @@ describe('Directives', async () => {
 			$('#compound-style')
 				.attr('style')
 				.toString()
-				.includes('color:var(--fg);--fg: black;--bg: white;'),
+				.includes('color:var(--fg);--bg: white;--fg: black;'),
 			true,
 		);
 	});

packages/astro/test/fixtures/css-order-transparent/astro.config.mjs

@@ -1,7 +1,3 @@
 import { defineConfig } from 'astro/config';
 
-export default defineConfig({
-	experimental: {
-		preserveScriptOrder: true,
-	}
-});
+export default defineConfig({});