Add devToolbar.placement configuration option

[tony]

RFC / Context: Dev Toolbar: allow configuring default position roadmap#1277

DX / Quality of life tweak for dev toolbar placement.

Changes

Adds optional devToolbar.placement configuration option.

• New config property: devToolbar.placement accepts 'bottom-left', 'bottom-center', or 'bottom-right'

• Priority: defaultSettings → config → localStorage (user's UI choice still wins)

• Use case: Sites with bottom-center UI elements (chat widgets, cookie banners) can set a project-wide default that persists across team members and localStorage clears

  Example:

  Before this PR, it would require manually setting the placement every time localStorage is cleared. Doesn't persist as a project default.

Exampe usage, astro.config.mjs:

export default defineConfig({
  devToolbar: {
    placement: 'bottom-left',
  },
});

Files changed

File	Change
types/public/toolbar.ts	Export DevToolbarPlacement type
types/public/config.ts	Add placement to interface with JSDoc
core/config/schemas/base.ts	Add Zod schema validation
vite-plugin-astro-server/pipeline.ts	Pass placement to client metadata
runtime/client/dev-toolbar/settings.ts	Implement priority chain
test/units/config/config-validate.test.js	Add validation tests

Testing

• Added unit tests for config validation:
  • Valid placement values are accepted
  • Invalid placement values are rejected
  • Omitting placement is allowed (optional)

Testing only test/units/config/config-validate.test.js:

pnpm:

pnpm --filter=astro exec astro-scripts test "test/units/config/config-validate.test.js"

npm:

node --test packages/astro/test/units/config/config-validate.test.js

Docs

@withastro/maintainers-docs for feedback, Documentation needed for:

• Configuration reference: new devToolbar.placement option
• Default value: 'bottom-center'
• Behavior: config acts as default, localStorage overrides persist user choice

[changeset-bot]

🦋 Changeset detected

Latest commit: bd8c445

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

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

✅ 9 untouched benchmarks

---

_{Comparing tony:feat/devtoolbar-placement-conf (bd8c445) with main (9e7a3c8)¹}

Footnotes

1. No successful run was found on main (33b65d7) during the generation of this report, so 9e7a3c8 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[tony]

@withastro Dev toolbar placement is tied to a site’s layout rather than an individual user preference, so defining it in config makes the default explicit and consistent across environments (e.g. dev machines, browser instances), while still preserving local overrides.

Assuming the case is sound, is this the right approach for introducing the config option? Are there any other boxes I should be ticking?

[Princesseuh]

Hello! Apologies for the delay, with the upcoming Astro 6 and the holidays, some things fell through the cracks. I'll be reviewing this shortly!

[Princesseuh]

Good with me, awesome work!

[sarah11918]

Thanks for providing this new feature! Left a note on the kind of changeset message we'd typically like to have with an example you can use as a model. And the docs look good! Just tiny updates!

[tony]

@Princesseuh @sarah11918 Thank you - Rebased! Let me know if this works!

[sarah11918]

Approving for docs! Thanks for making the dev toolbar even more usable! 🥳

[tony]

@sarah11918 Thank you!