ORM Studio

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.

7 min readUpdated DocumentationEdit this page
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

Launching Studio

Terminal
❯axil run

axil run compiles and starts your app, then starts Studio with:

  • Port: app port + 1, bound to 127.0.0.1.
  • App name: the name field of your package.json.
  • Database: detected from .env. DATABASE_FILENAME selects SQLite; a DATABASE_URL starting with postgres selects PostgreSQL and one starting with mysql selects 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:

❯npm install -D @axiljs/studio
❯pnpm add -D @axiljs/studio
❯yarn add -D @axiljs/studio
❯bun add -d @axiljs/studio

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, EXPLAIN and PRAGMA. On PostgreSQL and MySQL each query also runs inside a read-only transaction that is rolled back afterwards.
  • The table browser only issues SELECT and COUNT(*) 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

The sidebar shows the AxilJS logo, "Axil Studio" and your app name, then two groups of views:

GroupViews
WorkspaceOverview, Endpoints, Database, Schema, SQL console
ToolsRealtime, 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:

IndicatorMeaning
Connecting… / Checking app…Studio data or the app check is loading
App runningThe app answered (any HTTP status counts)
App not runningThe app could not be reached
Studio connectedThe Studio server has no proxy endpoint, so the app check was skipped
Studio unreachableThe 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=light or ?theme=dark to 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:

HashView
#/overviewOverview (also the fallback for unknown hashes)
#/endpointsEndpoint list
#/endpoints/GET/%2Fusers%2F%3AidRequest builder for one route: the method, then the URL-encoded route path
#/databaseTable list
#/database/usersData tab of a table
#/database/users?f=...Data tab with filters (a URL-encoded JSON array)
#/database/users/structureStructure tab
#/database/users/relationsRelations tab
#/schemaER diagram
#/sqlSQL console (#/sql?run runs the current editor text)
#/realtimeWebSocket and SSE testers
#/intentIntent view
#/exportCollection export
#/qrQR 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/data always 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 itemUsed by
Theme, collapsed sidebarShell
Rows per page, hidden columns per tableDatabase
Bearer token, last 10 requests per endpointEndpoints
Editor draft, last 50 queries, saved snippets, side-panel tabSQL console

Next steps

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY