Skip to content

Add devToolbar.placement configuration option#15015

Merged
Princesseuh merged 9 commits intowithastro:mainfrom
tony:feat/devtoolbar-placement-conf
Jan 28, 2026
Merged

Add devToolbar.placement configuration option#15015
Princesseuh merged 9 commits intowithastro:mainfrom
tony:feat/devtoolbar-placement-conf

Conversation

@tony
Copy link
Contributor

@tony tony commented Dec 13, 2025

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: defaultSettingsconfiglocalStorage (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: image

    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
Copy link

changeset-bot bot commented Dec 13, 2025

🦋 Changeset detected

Latest commit: f412cfd

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

@github-actions github-actions bot added pkg: astro Related to the core `astro` package (scope) docs pr labels Dec 13, 2025
@tony tony changed the title Feat/devtoolbar placement conf Add devToolbar.placement configuration option Dec 13, 2025
@codspeed-hq
Copy link

codspeed-hq bot commented Dec 13, 2025

Merging this PR will not alter performance

✅ 9 untouched benchmarks


Comparing tony:feat/devtoolbar-placement-conf (f412cfd) with main (7db2fda)1

Open in CodSpeed

Footnotes

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

@tony tony marked this pull request as ready for review December 13, 2025 20:23
@tony tony force-pushed the feat/devtoolbar-placement-conf branch 2 times, most recently from bc17e05 to 8e300bb Compare December 22, 2025 11:39
@tony tony force-pushed the feat/devtoolbar-placement-conf branch from 8e300bb to 88b0cb2 Compare December 28, 2025 19:05
@tony tony force-pushed the feat/devtoolbar-placement-conf branch from 88b0cb2 to c6821fa Compare January 13, 2026 10:38
@tony
Copy link
Contributor Author

tony commented Jan 13, 2026

@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
Copy link
Member

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!

Copy link
Member

@Princesseuh Princesseuh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good with me, awesome work!

@Princesseuh Princesseuh added this to the 5.17.0 milestone Jan 13, 2026
Copy link
Member

@sarah11918 sarah11918 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 tony force-pushed the feat/devtoolbar-placement-conf branch from a78725a to 923d8c4 Compare January 14, 2026 00:39
@tony
Copy link
Contributor Author

tony commented Jan 14, 2026

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

@tony tony force-pushed the feat/devtoolbar-placement-conf branch 2 times, most recently from cef52b4 to 6b3689b Compare January 14, 2026 23:10
Copy link
Member

@sarah11918 sarah11918 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@tony
Copy link
Contributor Author

tony commented Jan 16, 2026

@sarah11918 Thank you!

@tony tony force-pushed the feat/devtoolbar-placement-conf branch 3 times, most recently from bd8c445 to b189236 Compare January 18, 2026 10:48
@Princesseuh Princesseuh self-assigned this Jan 21, 2026
@tony tony force-pushed the feat/devtoolbar-placement-conf branch from b189236 to 740a662 Compare January 21, 2026 23:14
tony added 4 commits January 22, 2026 17:37
Add exported type for toolbar placement options and extend
DevToolbarMetadata to include optional placement property.
Add optional `placement` property to devToolbar config schema
and interface with JSDoc documentation.
Pass the devToolbar.placement config value to the client via
__astro_dev_toolbar__ metadata injection.
Implement the settings priority chain:
1. defaultSettings (hardcoded 'bottom-center')
2. Config placement (from astro.config.mjs)
3. localStorage (user's persisted choice)

This allows project-level default placement while still
respecting user's UI-driven placement preferences.
tony and others added 5 commits January 22, 2026 17:37
Test that:
- Valid placement values are accepted
- Placement is optional (can be omitted)
- Invalid placement values are rejected
Minor version bump per Astro convention for new config options.
Include @Version added and tweak comment copy

Co-authored-by: Sarah Rainsberger <[email protected]>
Co-authored-by: Sarah Rainsberger <[email protected]>
- Add js syntax highlighting to code block
- Fix spacing in comment
- Fix "overriden" → "overridden" typo
@tony tony force-pushed the feat/devtoolbar-placement-conf branch from 740a662 to f412cfd Compare January 22, 2026 23:37
@Princesseuh Princesseuh merged commit 54f6006 into withastro:main Jan 28, 2026
27 checks passed
@astrobot-houston astrobot-houston mentioned this pull request Jan 28, 2026
dadezzz pushed a commit to dadezzz/ice-notes that referenced this pull request Feb 7, 2026
This PR contains the following updates:

| Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) |
|---|---|---|---|
| [astro](https://astro.build) ([source](https://github.com/withastro/astro/tree/HEAD/packages/astro)) | [`5.16.15` → `5.17.1`](https://renovatebot.com/diffs/npm/astro/5.16.15/5.17.1) | ![age](https://developer.mend.io/api/mc/badges/age/npm/astro/5.17.1?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/astro/5.16.15/5.17.1?slim=true) |

---

### Release Notes

<details>
<summary>withastro/astro (astro)</summary>

### [`v5.17.1`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#5171)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@5.17.1)

##### Patch Changes

- [#&#8203;15334](withastro/astro#15334) [`d715f1f`](withastro/astro@d715f1f) Thanks [@&#8203;florian-lefebvre](https://github.com/florian-lefebvre)! - **BREAKING CHANGE to the experimental Fonts API only**

  Removes the `getFontBuffer()` helper function exported from `astro:assets` when using the experimental Fonts API

  This experimental feature introduced in v15.6.13 ended up causing significant memory usage during build. This feature has been removed and will be reintroduced after further exploration and testing.

  If you were relying on this function, you can replicate the previous behavior manually:

  - On prerendered routes, read the file using `node:fs`
  - On server rendered routes, fetch files using URLs from `fontData` and `context.url`

### [`v5.17.0`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#5170)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@5.17.0)

##### Minor Changes

- [#&#8203;14932](withastro/astro#14932) [`b19d816`](withastro/astro@b19d816) Thanks [@&#8203;patrickarlt](https://github.com/patrickarlt)! - Adds support for returning a Promise from the `parser()` option of the `file()` loader

  This enables you to run asynchronous code such as fetching remote data or using async parsers when loading files with the Content Layer API.

  For example:

  ```js
  import { defineCollection } from 'astro:content';
  import { file } from 'astro/loaders';

  const blog = defineCollection({
    loader: file('src/data/blog.json', {
      parser: async (text) => {
        const data = JSON.parse(text);

        // Perform async operations like fetching additional data
        const enrichedData = await fetch(`https://api.example.com/enrich`, {
          method: 'POST',
          body: JSON.stringify(data),
        }).then((res) => res.json());

        return enrichedData;
      },
    }),
  });

  export const collections = { blog };
  ```

  See [the `parser()` reference documentation](https://docs.astro.build/en/reference/content-loader-reference/#parser) for more information.

- [#&#8203;15171](withastro/astro#15171) [`f220726`](withastro/astro@f220726) Thanks [@&#8203;mark-ignacio](https://github.com/mark-ignacio)! - Adds a new, optional `kernel` configuration option to select a resize algorithm in the Sharp image service

  By default, Sharp resizes images with the `lanczos3` kernel. This new config option allows you to set the default resizing algorithm to any resizing option supported by [Sharp](https://sharp.pixelplumbing.com/api-resize/#resize) (e.g. `linear`, `mks2021`).

  Kernel selection can produce quite noticeable differences depending on various characteristics of the source image - especially drawn art - so changing the kernel gives you more control over the appearance of images on your site:

  ```js
  export default defineConfig({
    image: {
      service: {
        entrypoint: 'astro/assets/services/sharp',
        config: {
          kernel: "mks2021"
        }
    }
  })
  ```

  This selection will apply to all images on your site, and is not yet configurable on a per-image basis. For more information, see [Sharps documentation on resizing images](https://sharp.pixelplumbing.com/api-resize/#resize).

- [#&#8203;15063](withastro/astro#15063) [`08e0fd7`](withastro/astro@08e0fd7) Thanks [@&#8203;jmortlock](https://github.com/jmortlock)! - Adds a new `partitioned` option when setting a cookie to allow creating partitioned cookies.

  [Partitioned cookies](https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies) can only be read within the context of the top-level site on which they were set. This allows cross-site tracking to be blocked, while still enabling legitimate uses of third-party cookies.

  You can create a partitioned cookie by passing `partitioned: true` when setting a cookie. Note that partitioned cookies must also be set with `secure: true`:

  ```js
  Astro.cookies.set('my-cookie', 'value', {
    partitioned: true,
    secure: true,
  });
  ```

  For more information, see the [`AstroCookieSetOptions` API reference](https://docs.astro.build/en/reference/api-reference/#astrocookiesetoptions).

- [#&#8203;15022](withastro/astro#15022) [`f1fce0e`](withastro/astro@f1fce0e) Thanks [@&#8203;ascorbic](https://github.com/ascorbic)! - Adds a new `retainBody` option to the `glob()` loader to allow reducing the size of the data store.

  Currently, the `glob()` loader stores the raw body of each content file in the entry, in addition to the rendered HTML.

  The `retainBody` option defaults to `true`, but you can set it to `false` to prevent the raw body of content files from being stored in the data store. This significantly reduces the deployed size of the data store and helps avoid hitting size limits for sites with very large collections.

  The rendered body will still be available in the `entry.rendered.html` property for markdown files, and the `entry.filePath` property will still point to the original file.

  ```js
  import { defineCollection } from 'astro:content';
  import { glob } from 'astro/loaders';

  const blog = defineCollection({
    loader: glob({
      pattern: '**/*.md',
      base: './src/content/blog',
      retainBody: false,
    }),
  });
  ```

  When `retainBody` is `false`, `entry.body` will be `undefined` instead of containing the raw file contents.

- [#&#8203;15153](withastro/astro#15153) [`928529f`](withastro/astro@928529f) Thanks [@&#8203;jcayzac](https://github.com/jcayzac)! - Adds a new `background` property to the `<Image />` component.

  This optional property lets you pass a background color to flatten the image with. By default, Sharp uses a black background when flattening an image that is being converted to a format that does not support transparency (e.g. `jpeg`). Providing a value for `background` on an `<Image />` component, or passing it to the `getImage()` helper, will flatten images using that color instead.

  This is especially useful when the requested output format doesn't support an alpha channel (e.g. `jpeg`) and can't support transparent backgrounds.

  ```astro
  ---
  import { Image } from 'astro:assets';
  ---

  <Image
    src="/transparent.png"
    alt="A JPEG with a white background!"
    format="jpeg"
    background="#ffffff"
  />
  ```

  See more about this new property in [the image reference docs](https://docs.astro.build/en/reference/modules/astro-assets/#background)

- [#&#8203;15015](withastro/astro#15015) [`54f6006`](withastro/astro@54f6006) Thanks [@&#8203;tony](https://github.com/tony)! - Adds optional `placement` config option for the dev toolbar.

  You can now configure the default toolbar position (`'bottom-left'`, `'bottom-center'`, or `'bottom-right'`) via `devToolbar.placement` in your Astro config. This option is helpful for sites with UI elements (chat widgets, cookie banners) that are consistently obscured by the toolbar in the dev environment.

  You can set a project default that is consistent across environments (e.g. dev machines, browser instances, team members):

  ```js
  // astro.config.mjs
  export default defineConfig({
    devToolbar: {
      placement: 'bottom-left',
    },
  });
  ```

  User preferences from the toolbar UI (stored in `localStorage`) still take priority, so this setting can be overridden in individual situations as necessary.

### [`v5.16.16`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#51616)

[Compare Source](https://github.com/withastro/astro/compare/[email protected]@5.16.16)

##### Patch Changes

- [#&#8203;15281](withastro/astro#15281) [`a1b80c6`](withastro/astro@a1b80c6) Thanks [@&#8203;matthewp](https://github.com/matthewp)! - Ensures server island requests carry an encrypted component export identifier so they do not accidentally resolve to the wrong component.

- [#&#8203;15304](withastro/astro#15304) [`02ee3c7`](withastro/astro@02ee3c7) Thanks [@&#8203;cameronapak](https://github.com/cameronapak)! - Fix: Remove await from getActionResult example

- [#&#8203;15324](withastro/astro#15324) [`ab41c3e`](withastro/astro@ab41c3e) Thanks [@&#8203;Princesseuh](https://github.com/Princesseuh)! - Fixes an issue where certain unauthorized links could be rendered as clickable in the error overlay

</details>

---

### Configuration

📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update again.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box

---

This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0Mi45Mi4xMiIsInVwZGF0ZWRJblZlciI6IjQyLjkyLjEyIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->

Co-authored-by: Renovate Bot <[email protected]>
Co-committed-by: Renovate Bot <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs pr pkg: astro Related to the core `astro` package (scope)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants