Axil Studio
Axil Studio is the local dev dashboard that opens with axil run on app port + 1. Explore endpoints, browse your database, run read-only SQL and more.
On this page14
Axil Studio (@axiljs/studio) is a local developer dashboard for AxilJS applications. When you start your app with axil run, Studio starts next to it on app port + 1 and opens in your browser. It shows what your app exposes (HTTP routes, WebSocket and SSE channels) and what your database holds (tables, rows, foreign keys, indexes), lets you call endpoints and query data without leaving the page, and shows whether the running app keeps the contracts its decorators declare.
Info
If your app listens on port 3000, Studio opens at http://127.0.0.1:3001. The app port comes from PORT in your .env (default 3000).
What's inside
Endpoints
Grouped, searchable route list with a request builder, response viewer, cURL export and per-route history.
Database
Table browser with server-side sort, search and filters, row details, CSV/JSON export, structure and relations.
Schema
Entity-relationship diagram of every table and foreign key, with pan, zoom, fit and find.
SQL console
Read-only SQL editor with highlighting, a schema tree, history, saved snippets and a result grid.
Realtime
Connect to detected WebSocket and Server-Sent Events endpoints and watch traffic in a live log.
Intent
Live view of intent mode, contract violations, SLOs, circuit breakers and enforced decorators from @axiljs/runtime.
Export
Download or copy Postman, Insomnia and OpenAPI 3.0 collections generated from your routes.
QR access
QR codes for the app URL and the Studio URL.
Keyboard shortcuts
Command palette, g-key navigation and every shortcut Studio understands.
Launching Studio
axil run compiles and starts your app, then starts Studio with:
- Port: app port + 1, bound to
127.0.0.1. - App name: the
namefield of yourpackage.json. - Database: detected from
.env.DATABASE_FILENAMEselects SQLite; aDATABASE_URLstarting withpostgresselects PostgreSQL and one starting withmysqlselects MySQL.
Projects created with axil create on CLI 0.3.3 or later already list @axiljs/studio in devDependencies. In an older or hand-made project, install it yourself:
Without the package, axil run prints Studio skipped with that install hint and the dev server starts normally. See Getting Started for details.
Read-only by design
Studio opens its own database connection, separate from your app's (under axil run your app runs in a child process, so the two can't share a driver).
- SQLite files are opened with a read-only handle.
- The SQL console accepts only
SELECT,WITH,SHOW,DESCRIBE,EXPLAINandPRAGMA. On PostgreSQL and MySQL each query also runs inside a read-only transaction that is rolled back afterwards. - The table browser only issues
SELECTandCOUNT(*)queries. Table and column names are checked against the schema and quoted, and filter values are bound parameters.
Studio is a local development tool: it only answers requests addressed to local host names and only grants CORS to local origins. See Configuration.
A self-contained page
The whole UI is one HTML document served by Studio. CSS, the SVG icons, the AxilJS logo and the client script are inlined, and it uses system font stacks. It loads nothing from CDNs, font services or other external hosts, so Studio works offline. Every view is rendered in the browser from Studio's own JSON API.
Layout
Sidebar
The sidebar shows the AxilJS logo, "Axil Studio" and your app name, then two groups of views:
| Group | Views |
|---|---|
| Workspace | Overview, Endpoints, Database, Schema, SQL console |
| Tools | Realtime, Intent, Export, QR access |
Endpoints, Database and Realtime show counts (routes, tables, WebSocket + SSE channels).
- Collapse: on desktop, the sidebar button (or the
[key) collapses it to an icon rail. The choice is remembered in the browser. - Mobile drawer: below 768 px wide the sidebar becomes a drawer. Open it with the menu button in the top bar and close it by tapping the backdrop, picking a view or pressing
Esc. Two-pane views (Endpoints, Database) show the list first and the detail after you pick an item, with a back button to return.
App status
The bottom of the sidebar shows whether your app is reachable, plus a link to the app URL. Studio checks by sending GET / to the app through its proxy:
| Indicator | Meaning |
|---|---|
| Connecting… / Checking app… | Studio data or the app check is loading |
| App running | The app answered (any HTTP status counts) |
| App not running | The app could not be reached |
| Studio connected | The Studio server has no proxy endpoint, so the app check was skipped |
| Studio unreachable | The Studio API itself did not respond |
Sending a request from the Endpoints view updates the indicator too.
Top bar
Breadcrumbs (app name, then the current view and item), a Search… button that opens the command palette (Ctrl K), a theme toggle and a Refresh data button.
Overview page
The landing view summarises the project:
- Header: app name, database driver badge (or "no database"), when Studio started and the app URL, plus Export and SQL console buttons.
- Stat cards: Endpoints (with a per-method bar and how many routes use auth middleware), Tables (columns and relations), Total rows, Realtime channels (WebSocket and SSE counts). Each card links to its view.
- Quick links to every tool.
- Largest tables: the six tables with the most rows, with bars.
- Recent queries: your last five SQL console queries. Clicking one opens it in the console and runs it.
- Endpoints by resource: routes grouped by first path segment with their methods.
Theme
Studio has a light and a dark theme, both using the orange AxilJS accent.
- By default it follows your operating system (
prefers-color-scheme) and switches live when the system theme changes. - The theme button in the top bar (or
t) toggles between light and dark. Your choice is saved in the browser and from then on overrides the system setting. - Adding
?theme=lightor?theme=darkto the Studio URL forces a theme for that page load without saving it.
Hash routes
Each view has its own URL hash, so you can bookmark or share a view and use the browser's back and forward buttons:
| Hash | View |
|---|---|
#/overview | Overview (also the fallback for unknown hashes) |
#/endpoints | Endpoint list |
#/endpoints/GET/%2Fusers%2F%3Aid | Request builder for one route: the method, then the URL-encoded route path |
#/database | Table list |
#/database/users | Data tab of a table |
#/database/users?f=... | Data tab with filters (a URL-encoded JSON array) |
#/database/users/structure | Structure tab |
#/database/users/relations | Relations tab |
#/schema | ER diagram |
#/sql | SQL console (#/sql?run runs the current editor text) |
#/realtime | WebSocket and SSE testers |
#/intent | Intent view |
#/export | Collection export |
#/qr | QR codes |
Refreshing data
- Refresh data (top bar, or the palette action) re-reads routes from
src/and tables from the database. - While the tab is visible, Studio reloads its data every 30 seconds. The Overview re-renders if the number of routes, tables, row counts or channels changed.
- On the server, collected data is cached for 5 seconds.
GET /api/studio/dataalways bypasses the cache.
Where things are stored
Studio keeps UI preferences and history in your browser's localStorage (prefix axil-studio:). Nothing is written back to your project:
| Stored item | Used by |
|---|---|
| Theme, collapsed sidebar | Shell |
| Rows per page, hidden columns per table | Database |
| Bearer token, last 10 requests per endpoint | Endpoints |
| Editor draft, last 50 queries, saved snippets, side-panel tab | SQL console |
Next steps
- Getting Started: install, launch and troubleshoot.
- Keyboard shortcuts: get around without the mouse.
- Configuration: run Studio programmatically and understand its security model.
Was this page helpful?