fix(dev): forward documented flags to the background dev server process

[kdelay]

Changes

• astro dev --background spawns a plain astro dev child process, but only forwarded --port, --host, --config, --root, --allowed-hosts, and --json. The documented --mode, --site, --base, --outDir, --verbose, and --silent flags were silently dropped, so a background dev server could behave differently from a foreground one started with the same flags (e.g. astro dev --background --mode staging starts the server in the default mode).
• Extracts the child argv construction into buildDevProcessArgs(flags) in packages/astro/src/cli/dev/background.ts and forwards the missing flags. --open, --force, and --ignore-lock are intentionally not forwarded since they are handled at the parent level or don't apply to the child process.
• Same class of issue as fix(cli): background with host #17158 (--host not taken into account with --background), for the remaining documented dev flags.
• Changeset included (astro patch).

Reproduction (before, from packages/astro/test/fixtures/astro-basic):

$ node ../../../bin/astro.mjs dev --background --mode staging --port 4877
$ ps -p <pid> -o command
node .../bin/astro.mjs dev --port 4877 --json   # --mode dropped

After this change the child process argv is dev --port 4877 --mode staging --json.

Testing

• Adds test/units/dev/background-args.test.ts (12 unit tests) covering the child argv mapping: defaults, port/host variants (--host with and without a value), config/root, allowed-hosts, each newly forwarded flag, and that --background itself is never passed to the child.
• Manually verified on macOS that the spawned child process argv now contains --mode staging (checked via ps), and that astro dev stop still works.
• Existing dev and cli unit suites pass.

Docs

No docs changes needed: this makes astro dev --background honor already-documented astro dev flags.

[changeset-bot]

🦋 Changeset detected

Latest commit: 25220f0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 399 packages

Name	Type
astro	Patch
@e2e/astro-linked-lib	Patch
@e2e/actions-blog	Patch
@e2e/actions-react-19	Patch
@e2e/astro-component	Patch
@e2e/astro-envs	Patch
@e2e/astro-island-hydration-error	Patch
@test/astro-cloudflare-node-prerender-mdx	Patch
@test/astro-cloudflare	Patch
@e2e/content-collections	Patch
@e2e/csp-server-islands	Patch
@e2e/css	Patch
@test/custom-client-directives	Patch
@e2e/dev-toolbar	Patch
@e2e/error-cyclic	Patch
@e2e/error-sass	Patch
@e2e/errors	Patch
@e2e/hydration-race	Patch
@e2e/i18n	Patch
@test/nested-style-bug-e22e	Patch
@e2e/preact-compat-component	Patch
@e2e/preact-component	Patch
@e2e/preact-lazy-component	Patch
@e2e/prefetch	Patch
@e2e/react-component	Patch
@e2e/server-islands-key	Patch
@e2e/server-islands	Patch
@e2e/solid-circular	Patch
@e2e/solid-component	Patch
@e2e/solid-recurse	Patch
@e2e/svelte-component	Patch
@e2e/e2e-tailwindcss	Patch
@e2e/ts-resolution	Patch
@e2e/view-transitions	Patch
@e2e/vue-component	Patch
@performance/md	Patch
@performance/mdoc	Patch
@performance/mdx	Patch
@test/0-css	Patch
fake-astro-library	Patch
@test/actions	Patch
@test/alias-css-url	Patch
@test/alias-path-alias-style	Patch
@test/ts-paths-no-baseurl	Patch
@test/aliases-tsconfig	Patch
@test/aliases	Patch
@test/api-routes	Patch
@test/asset-query-params-chunks	Patch
@test/asset-url-base	Patch
@test/astro-pages	Patch
@test/astro-assets-prefix	Patch
@test/astro-assets	Patch
@test/astro-basic	Patch
@test/astro-check-errors	Patch
@test/astro-check-no-errors	Patch
@test/astro-check-watch	Patch
@test/astro-children	Patch
@test/astro-client-only	Patch
@test/astro-component-bundling	Patch
@test/astro-component-code	Patch
@test/astro-css-bundling	Patch
@test/astro-dev-headers	Patch
@test/astro-dev-http2	Patch
@test/astro-doctype	Patch
@test/astro-dynamic	Patch
@test/astro-env-content-collections	Patch
@test/astro-env-required-public	Patch
@test/astro-env-server-fail	Patch
@test/astro-env-server-secret	Patch
@test/astro-env	Patch
@test/astro-envs	Patch
@test/astro-expr	Patch
@test/astro-get-static-paths	Patch
@test/astro-head	Patch
@test/astro-manifest-client-script	Patch
@test/astro-manifest-invalid	Patch
@test/astro-manifest	Patch
@test/astro-markdown-frontmatter-injection	Patch
@test/astro-markdown-plugins	Patch
@test/astro-markdown-remarkRehype	Patch
@test/astro-markdown-skiki-default-color	Patch
@test/astro-markdown-skiki-langs	Patch
@test/astro-markdown-skiki-themes-custom	Patch
@test/astro-markdown-skiki-themes-integrated	Patch
@test/astro-markdown-skiki-wrap-false	Patch
@test/astro-markdown-skiki-wrap-null	Patch
@test/astro-markdown-skiki-wrap-true	Patch
@test/astro-markdown-url	Patch
@test/astro-markdown	Patch
@test/astro-mode	Patch
@test/astro-page-directory-url	Patch
@test/astro-partial-html	Patch
@test/astro-preview-allowed-hosts	Patch
@test/astro-preview-headers	Patch
@test/astro-public	Patch
@test/astro-script-template-dedup	Patch
@test/astro-scripts	Patch
@test/astro-slots-nested	Patch
@test/concurrency	Patch
@test/build-readonly-file	Patch
@test/cache-memory-query-include	Patch
@test/cache-memory-query	Patch
@test/client-address-node	Patch
@test/client-only-child-styles	Patch
@test/client-only-css-chunk-leak	Patch
@test/code-component	Patch
@test/component-library	Patch
@test/config-vite-css-target-no-minify	Patch
@test/config-vite-css-target	Patch
@test/config-vite	Patch
@test/react-container	Patch
@test/content-with-spaces-in-folder-name	Patch
@test/content-collection-picture-render	Patch
@example/content-collection-references	Patch
@test/content-collection-tla-svg	Patch
@test/content-collections-base	Patch
@test/content-collections-empty-dir	Patch
@test/content-collections-empty-md-file	Patch
@test/content-collections-image-hmr	Patch
@test/content-collections-mutation	Patch
@test/content-collections-number-id	Patch
@test/content-collections-type-inference	Patch
@test/content-collections-with-config-mjs	Patch
@test/content-collections	Patch
@test/content-frontmatter	Patch
@test/content-intellisense	Patch
@test/content-layer-loader-schema-function	Patch
@test/content-layer-remark-plugins	Patch
@test/content-layer	Patch
@test/content-ssr-integration	Patch
@test/content-static-paths-integration	Patch
@test/content	Patch
@test/core-image-data-url	Patch
@test/core-image-deletion-ssr	Patch
@test/core-image-deletion	Patch
@test/core-image-errors	Patch
@test/core-image-fs-config	Patch
@test/core-image-remark-infersize	Patch
@test/core-image-layout	Patch
@test/core-image-picture-emit-file	Patch
@test/core-image-remark-imgattr	Patch
@test/core-image-ssg	Patch
@test/core-image-ssr	Patch
@test/core-image-svg-in-client	Patch
@test/core-image-svg	Patch
@test/core-image-unconventional-settings	Patch
@test/core-image	Patch
@test/csp-adapter	Patch
@test/csp-fonts	Patch
@test/csp	Patch
@test/css-assets	Patch
@test/css-dangling-references	Patch
@test/css-deduplication	Patch
@test/css-double-bundle	Patch
@test/css-dynamic-import-dev	Patch
@test/css-import-as-inline	Patch
@test/css-inline-stylesheets	Patch
@test/css-no-code-split	Patch
@test/css-path-case	Patch
@test/css-pure-chunk-query-params	Patch
@test/css-server-output-dedup	Patch
@test/custom-404-injected-from-dep	Patch
@test/custom-404-pkg	Patch
custom-fetch-error-pages	Patch
@test/custom-renderer	Patch
@test/data-collections-schema	Patch
@test/data-collections	Patch
@test/debug-component	Patch
@test/dev-container	Patch
@test/dev-render	Patch
@test/dev-request-url	Patch
@test/dynamic-endpoint-collision	Patch
@test/dynamic-route-build-file	Patch
@test/endpoint-routing	Patch
@test/error-bad-js	Patch
@test/error-build-location	Patch
@test/error-non-error	Patch
@test/extension-matching	Patch
@test/fetch	Patch
@test/fonts	Patch
@test/astro-fontsource-package	Patch
@test/get-static-paths-pages	Patch
@test/glob-pages-css	Patch
@test/head-propagation-prerender-env	Patch
@test/hmr-markdown	Patch
@test/hmr-new-page	Patch
@test/hmr-slots-render	Patch
@test/hoisted-imports	Patch
@test/html-component	Patch
@test/html-escape	Patch
@test/html-page	Patch
@test/html-slots	Patch
@test/hydration-race	Patch
@test/i18n-client-import	Patch
@test/i18n-css-leak-basic	Patch
@test/import-ts-with-js	Patch
@test/impostor-md-file	Patch
@test/integration-add-page-extension	Patch
@test/integration-server-setup	Patch
@test/jsx-queue-rendering	Patch
@test/large-array-solid	Patch
@test/legacy-collections-backwards-compat	Patch
@test/lightningcss-css-modules-content	Patch
@test/lightningcss-scoped-nesting	Patch
@test/live-loaders	Patch
@test/markdown	Patch
@test/middleware-dev	Patch
@test/middleware-full-ssr	Patch
@test/middleware-no-user-middlewaqre	Patch
@test/middleware-tailwind	Patch
@test/minification-html-default	Patch
@test/minification-html-jsx	Patch
@test/minification-html	Patch
@test/non-ascii-path	Patch
@test/non-html-pages	Patch
@test/page-format	Patch
@test/page-level-styles	Patch
@test/parallel-components	Patch
@test/partials-css-boundary	Patch
@test/partials	Patch
@test/passthrough-image-service	Patch
@test/postcss	Patch
@test/preact-compat-component	Patch
@test/preact-component	Patch
@test/remote-css	Patch
@test/request-signal	Patch
@test/reuse-injected-entrypoint	Patch
@test/root-srcdir-css	Patch
@test/scoped-style-strategy	Patch
@test/server-entry-fake-adapter	Patch
@test/server-entry	Patch
@test/server-islands-hybrid	Patch
@test/server-islands-ssr	Patch
@test/sessions	Patch
@test/slots-preact	Patch
@test/slots-react	Patch
@test/slots-solid	Patch
@test/slots-svelte	Patch
@test/slots-vue	Patch
@test/solid-component	Patch
@test/sourcemap	Patch
@test/space-in-folder-name	Patch
@test/special-chars-in-component-imports	Patch
@test/ssr-assets	Patch
@test/ssr-dynamic	Patch
@test/ssr-partytown	Patch
@test/ssr-prerender-get-static-paths	Patch
@test/ssr-prerender	Patch
@test/ssr-preview	Patch
@test/ssr-renderers-static-vue	Patch
@test/ssr-request	Patch
@test/ssr-hoisted-script	Patch
@test/ssr-scripts	Patch
@test/static-build-code-component	Patch
@test/static-build-dir	Patch
@test/static-build-frameworks	Patch
@test/static-build-page-url-format	Patch
@test/static-build-ssr	Patch
@test/static-build	Patch
@test/static-redirect	Patch
@test/svelte-component	Patch
@test/svg-deduplication	Patch
@test/tailwindcss	Patch
@e2e/third-party-astro	Patch
@test/url-import-suffix	Patch
@test/view-transitions	Patch
@test/virtual-astro-file	Patch
@test/vite-virtual-modules	Patch
@test/vitest	Patch
@test/vue-component	Patch
@test/vue-with-multi-renderer	Patch
@test/alpinejs-basics	Patch
@test/alpinejs-directive	Patch
@test/alpinejs-plugin-script-import	Patch
@test/astro-cloudflare-allowed-hosts	Patch
@test/astro-cloudflare-astro-dev-platform	Patch
@test/astro-cloudflare-astro-env	Patch
@test/astro-cloudflare-binding-image-service	Patch
@test/astro-cloudflare-cache-provider-wait-until	Patch
@test/astro-cloudflare-cache-provider	Patch
@test/astro-cloudflare-client-address	Patch
@test/astro-cloudflare-compile-custom-image-service	Patch
@test/astro-cloudflare-compile-image-service	Patch
@test/astro-cloudflare-custom-entryfile	Patch
@test/astro-cloudflare-dev-image-endpoint	Patch
@test/astro-cloudflare-external-image-service	Patch
@test/astro-cloudflare-external-redirects	Patch
@test/astro-cloudflare-internal-redirects	Patch
@test/astro-cloudflare-no-output	Patch
@test/astro-cloudflare-prerender-node-env	Patch
@test/astro-cloudflare-prerender-queue-consumers	Patch
@test/astro-cloudflare-prerender-styles	Patch
@test/astro-cloudflare-prerenderer-errors	Patch
@test/astro-cloudflare-prerenderer-render-error	Patch
@test/routing-priority-cloudflare	Patch
@test/cf-server-entry	Patch
@test/astro-cloudflare-server-island-prerender-framework	Patch
@test/astro-cloudflare-sql-import	Patch
@test/cf-ssr-deps	Patch
@test/astro-cloudflare-static	Patch
@test/astro-cloudflare-svelte-rune-deps	Patch
@test/astro-cloudflare-top-level-return	Patch
@test/cf-user-optimize-deps	Patch
@test/astro-cloudflare-vite-plugin	Patch
@test/astro-cloudflare-with-base	Patch
@test/astro-cloudflare-with-react	Patch
@test/astro-cloudflare-with-solid-js	Patch
@test/astro-cloudflare-with-svelte	Patch
@test/astro-cloudflare-with-vue	Patch
@test/astro-cloudflare-wrangler-preview-platform	Patch
@test/markdoc-content-collections	Patch
@test/content-layer-markdoc	Patch
@test/headings-custom	Patch
@test/headings	Patch
@test/image-assets-custom	Patch
@test/image-assets	Patch
@test/markdoc-propagated-assets	Patch
@test/markdoc-render-with-space	Patch
@test/markdoc-render-html	Patch
@test/markdoc-render-null	Patch
@test/markdoc-render-partials	Patch
@test/markdoc-render-simple	Patch
@test/markdoc-render-table-attrs	Patch
@test/markdoc-render-this-context	Patch
@test/markdoc-render-typographer	Patch
@test/markdoc-render-with-components	Patch
@test/markdoc-render-with-config	Patch
@test/markdoc-render-with-extends-components	Patch
@test/markdoc-render-with-indented-components	Patch
@test/markdoc-render-with-transform	Patch
@test/markdoc-variables	Patch
@test/content-layer-rendering	Patch
@test/mdx-css-head-mdx	Patch
@test/image-remark-imgattr	Patch
@test/mdx-astro-container-escape	Patch
@test/mdx-frontmatter-injection	Patch
@test/netlify-skew-protection	Patch
@test/netlify-hosted-astro-project	Patch
@test/nodejs-api-route	Patch
@test/nodejs-badurls	Patch
@test/nodejs-encoded	Patch
@test/nodejs-errors	Patch
@test/nodejs-headers	Patch
@test/nodejs-image	Patch
@test/locals	Patch
@test/node-middleware	Patch
@test/nodejs-prerender-404-500	Patch
@test/nodejs-prerender	Patch
@test/nodejs-prerendered-error-page-fetch	Patch
@test/nodejs-preview-headers	Patch
@test/redirects	Patch
@test/node-sessions	Patch
@test/ssr-assets-middleware	Patch
@test/node-static-headers	Patch
@test/node-trailingslash	Patch
@test/url	Patch
@test/well-known-locations	Patch
@test/react-component	Patch
@test/sitemap-chunks	Patch
@test/sitemap-dynamic	Patch
@test/sitemap-i18n-fallback	Patch
@test/sitemap-ssr	Patch
@test/sitemap-static	Patch
@test/sitemap-trailing-slash	Patch
async-rendering	Patch
conditional-rendering	Patch
@test/empty-class	Patch
svelte-prop-types	Patch
@test/astro-vercel-basic	Patch
@test/astro-vercel-image	Patch
@test/astro-vercel-integration-assets	Patch
@test/vercel-isr	Patch
@test/vercel-max-duration	Patch
@test/vercel-edge-middleware-with-edge-file	Patch
@test/vercel-edge-middleware-without-edge-file	Patch
@test/astro-vercel-no-output	Patch
@test/astro-vercel-prerendered-error-pages	Patch
@test/astro-vercel-redirects-serverless	Patch
@test/astro-vercel-redirects	Patch
@test/vercel-server-islands	Patch
@test/astro-vercel-serverless-prerender	Patch
@test/astro-vercel-serverless-with-dynamic-routes	Patch
@test/astro-vercel-static-assets	Patch
@test/vercel-static-headers	Patch
@test/astro-vercel-static	Patch
@test/vercel-streaming	Patch
@test/astro-vercel-with-web-analytics-enabled-output-as-static	Patch
vercel-hosted-astro-project	Patch
@test/vue-app-entrypoint-async	Patch
@test/vue-app-entrypoint-css	Patch
@test/vue-app-entrypoint-no-export-default	Patch
@test/vue-app-entrypoint-relative	Patch
@test/vue-app-entrypoint-src-absolute	Patch
@test/vue-app-entrypoint	Patch
@test/vue-basics	Patch
vue-prop-types	Patch
astro-benchmark	Patch
@benchmark/adapter	Patch
@benchmark/timer	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codspeed-hq]

Merging this PR will not alter performance

✅ 21 untouched benchmarks

---

_{Comparing kdelay:fix/dev-background-flag-forwarding (25220f0) with main (296e1b0)}

[kdelay]

The red Test (integrations): macos-14 (node@24) job looks unrelated to this change.

It fails inside @astrojs/cloudflare, which reports tests 277 / pass 276 / fail 0 and then exits 1 on a teardown race:

ℹ Error: Test hook "before" at test/with-svelte.test.ts:9:2 generated asynchronous activity
  after the test ended. This activity created the error "Error: socket hang up" and would have
  caused the test to fail, but instead triggered an uncaughtException event.

No assertion failed, and the same job is green on the other matrix entries.

This PR only touches packages/astro/src/cli/dev/background.ts plus a new unit file. The extracted buildDevProcessArgs is reached exclusively from background(), and the Cloudflare integration suite goes through fixture.build() and fixture.preview(), never astro dev --background, so there is no path from this diff into that suite. Other branches from the last day hit the same integration job in different packages (@astrojs/node, @astrojs/mdx), which points at the job rather than at any one change.

Let me know if you would like me to push a no-op commit so the job gets another run.