DevTools

A development overlay for your app. A small launcher sits on the page, and you can drag it anywhere. It opens a panel with five screens:

  • Home: what is on the page at a glance, with a card for each screen.
  • Components: every Astralis component on the page. Each one opens a page of its own with its props, how it reaches the browser, and the findings about it.
  • Findings: what the validator says is broken, live, as you save.
  • Recommendations: what works but could be better.
  • Report: a problem sent to the Astralis maintainers with the evidence they need to reproduce it.

It runs in development only. A production build contains none of it.

Why a UI library needs its own#

React DevTools shows the component tree, but it can only show what hydrates in the browser, and many Astralis components never do: 91 of the 238 components and parts in the system spec are Server Components that ship no JavaScript. It also knows nothing about your design system, such as which props a component was configured with, whether those values are valid, or where the component is documented.

The Astralis DevTools read the library itself. In development every component names itself on the element it renders, and a bridge in your dev server runs the same validator as astralis validate and CI.

Set up#

From your project's root:

npx astralis-cli init --devtools

It installs astralis-devtools as a devDependency and wires it in:

  • Next.js: <AstralisDevTools /> goes at the end of <body> in your root layout, and the bridge's route is written to app/api/astralis-devtools/[...path]/route.ts.
  • Vite: astralisDevtools() is added to the plugins of your vite.config.

Projects made with npm create astralis have the DevTools already; pass --no-devtools to leave them out. Running init --devtools again changes nothing.

By hand#

For Next.js, add the component to the root layout:

import { AstralisDevTools } from "astralis-devtools/next";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <AstralisDevTools />
      </body>
    </html>
  );
}

Then create app/api/astralis-devtools/[...path]/route.ts:

export { GET, POST } from "astralis-devtools/next/route";

For Vite, add the plugin:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { astralisDevtools } from "astralis-devtools/vite";

export default defineConfig({
  plugins: [react(), astralisDevtools()],
});

Shortcuts#

KeysWhat it does
Shift Alt AOpen the DevTools on Home, or close them
Shift Alt CPick a component on the page, then open its page
EscStop picking, or close the panel from inside it

On a Mac, Alt is Option. The launcher's crosshair button picks too.

Picking a component#

Press Shift Alt C or the crosshair, hover the page, and click. The panel steps aside while you pick, and clicks go to the DevTools, not to your app, so a link does not navigate and a trigger does not open its menu. Press Esc to stop.

Components#

The Components screen lists the Astralis components on the page, grouped by kind, with how many of each there are. A coloured dot says how each reaches the browser, and a count shows the findings and recommendations about it. Pointing at a row outlines that component on the page. A kind with several on the page expands to list them, each with its text and first props.

A component's page shows:

  • Its name, as you would write it: Card.Body, not div.

  • The findings and recommendations about it. The validator names the component, attribute and value each finding is on, so when the page gives this very component that value the finding is marked This one.

  • The props it was given: variant, size, colour scheme and style props, including responsive values such as p={{ base: "4", md: "8" }}. Children, text, links and event handlers are never shown.

  • How it reaches the browser, from the system spec:

    LabelMeaning
    Server ComponentRenders on the server and ships no library JavaScript
    Server shell, client islandRenders on the server; a small interactive part hydrates
    Client ComponentHydrates in the browser to be interactive

    A Vite app renders everything in the browser, so there the label tells you what the component would ship in a server-rendered app.

  • Where it sits: the Astralis components around it and inside it, each one click away, a Locate on page button, and a link to its documentation.

When one component renders through another onto the same element, you see the whole chain. A Modal.Trigger wrapping a Button shows as Modal.Trigger → Button, with each one's props.

Findings and recommendations#

Findings lists the errors astralis validate would report for your project: things that render wrong or not at all. Recommendations lists its warnings: things that work but could be better, such as a Flex column that is a VStack, a Button that shows only an icon and has no aria-label, or a raw colour where a theme token would follow dark mode. Each shows the file, line, rule and, when the page has it, the component it is on, one click away. Both update as you save, usually in well under a second. The badge on the launcher counts the errors, or the recommendations when there are no errors.

On Next.js, the files that render the page you are looking at (its page file and every layout and template above it) are listed first, under This page.

Report#

When something in Astralis looks wrong, open the component's page and press Report a problem, or open the Report screen and pick it. Write a title and, if you like, what happened and what you expected. The screen builds an issue snapshot:

  • the Astralis components under the one you picked, each with the props it was given (only those the spec describes; never links, image sources or event handlers);
  • the versions of astralis-ui, your framework and React, your browser and window size, and whether the page is light or dark;
  • the page's path, without its query string;
  • the validator's findings for the files that render the page (on Vite, for the project), unless you untick them.

Page text is replaced by placeholders unless you tick Include page text. Console errors from this session and a screenshot are left out unless you add them.

Below the form is exactly the JSON that would be sent, updated as you type. Nothing leaves your machine until you press Open issue on GitHub. The report then opens as an issue on the Astralis repository, from your own GitHub account, and its page opens. The issue carries your words, the versions in use, the findings, a small repro.tsx built from the component tree, and the snapshot itself. GitHub cannot take images through its API, so a screenshot stays with you: save it from the Report screen and drop it into the issue. Copy JSON and Download keep the snapshot without sending it.

Without signing in#

Open on GitHub instead needs no sign-in and no app: it opens GitHub's own new-issue form in a new tab, with the title and report filled in, and you check it and press Create there. A link holds about 8 kB, so for a large snapshot the JSON is left out; Download keeps it to attach.

Already reported?#

Before you send, the Report screen checks the repository for an issue that already reports the same problem: the same component, the same rule codes in its findings, and the same minor version of astralis-ui. If there is one, it shows it above the button, and Add my report here adds your report to that issue as a comment instead of opening a second one, which tells the maintainers the problem reaches more people. Other open issues about the same component are listed too. Every issue a report opens carries the short keys this match uses, so a later report can find it.

Signing in#

The first time, press Sign in with GitHub. The Report screen shows a short code; open GitHub, enter it, and approve the Astralis DevTools app. The app can do one thing: read and write issues on the Astralis repository. It cannot see your code or your other repositories.

The sign-in is kept by the bridge, in a file in your user config directory that only you can read (%APPDATA%\astralis on Windows, ~/.config/astralis elsewhere). Your app's page never sees the token, only your GitHub name. You stay signed in across restarts, and astralis report uses the same sign-in. Sign out forgets it; to revoke the app's access entirely, remove it at github.com/settings/applications.

Your issues#

The Your issues tab lists the issues you have opened on the Astralis repository, with where each stands: open, closed and done, or closed as not planned, with its comments and labels. Each one opens on GitHub. Home shows how many are open.

From the terminal, astralis report builds the same snapshot from your source files and opens it the same way.

How it works#

In development, every astralis-ui component adds two attributes to the element it renders:

<div data-astralis="Card.Body" data-astralis-props='[{}]'>

They are part of the server-rendered HTML, which is how Server Components can be inspected. In production the attributes are never rendered: the library's production HTML is byte-for-byte what it would be without the DevTools, and a test holds it to that for every component.

The bridge runs inside your dev server. On Next.js that is the route handler above; on Vite it is dev-server middleware, fed by Vite's own file watcher. It validates your .tsx and .jsx files against the installed astralis-ui's system spec, re-validates each file when you save it, and streams the findings to the overlay.

The overlay brings its own look: the Astralis brand and fonts, embedded in the package and drawn in a shadow root, so it loads nothing from the network and your app's styles never reach it, nor its styles your app. It remembers where you left the launcher, and whether the panel was open.

Privacy and security#

  • Nothing leaves your machine unless you send it. The overlay talks only to your own dev server, and there is no telemetry. The bridge talks to GitHub only for you: to sign you in when you ask, to open a report you have read and sent, and, while you are signed in, to fetch the list of issues you opened.
  • Your GitHub token stays with the bridge. It lives in a file only you can read, never in the page, and the app it belongs to can only read and write issues on the Astralis repository.
  • The bridge answers this machine only. A request from another device, or from a page on another site, is refused, even when the dev server is open to your network (next dev -H 0.0.0.0).
  • Nothing runs in production. In a production build the Next.js route answers 404 without loading the bridge, and the Vite plugin applies only to vite dev.