Getting Started
Install @axiljs/studio, launch it with axil run on app port + 1, point it at SQLite, PostgreSQL or MySQL, and fix common startup problems.
On this page7
Requirements
- An AxilJS project run with
axil run(from@axiljs/cli). @axiljs/studioin the project.- For the database views, the driver for your database installed in the project:
better-sqlite3(SQLite),pg(PostgreSQL) ormysql2(MySQL). Studio loads it at runtime; without it the database views stay empty and the terminal says which package is missing.
Install
New projects
Existing projects
Start the dev server
Launch output
Once Studio is listening, it prints its URL:
If the browser does not open, visit that URL yourself. http://localhost:3001 works too.
Ports
Studio always uses app port + 1. The app port is PORT from your .env, or 3000 when it is not set:
PORT | App | Studio |
|---|---|---|
| not set | 3000 | 3001 |
4000 | 4000 | 4001 |
8080 | 8080 | 8081 |
PORT=4000Database detection
Studio reads your .env and opens its own connection:
1# SQLite (a path relative to the project directory, or absolute)
2DATABASE_FILENAME=./dev.db
3
4# PostgreSQL
5DATABASE_URL=postgres://user:password@localhost:5432/mydb
6
7# MySQL
8DATABASE_URL=mysql://user:password@localhost:3306/mydb| Variable | Driver |
|---|---|
DATABASE_FILENAME | SQLite (takes precedence when both are set) |
DATABASE_URL starting with postgres | PostgreSQL |
DATABASE_URL starting with mysql | MySQL |
The terminal reports the result, for example [Studio] Connected to SQLite: /path/to/dev.db or [Studio] PostgreSQL connection failed: ....
What Studio lists:
- SQLite: every table except
_migrationsand SQLite's internalsqlite_*tables. - PostgreSQL: base tables in the
publicschema, except_migrations. - MySQL: tables in the current database, except
_migrations.
Note
If the SQLite file does not exist yet (your app creates it on first start), Studio retries five times, two seconds apart. Opening a table later also triggers a new connection attempt.
Routes and realtime detection
Studio does not ask your running app for its routes. It scans the .ts and .js files under src/ (skipping node_modules) for calls such as:
app.get('/health', handler)
router.post('/users', authenticate(jwt), validate({ body }), createUser)
this.delete('/users/:id', removeUser)The first argument must be a string path starting with /. Later arguments become the middleware list and the handler name. WebSocket and SSE endpoints are detected the same way; see Realtime.
Troubleshooting
Studio skipped in the terminal
@axiljs/studio is not installed in the project. Run npm install -D @axiljs/studio and restart axil run.
No tables in Database, Schema or the SQL console
- Check
DATABASE_FILENAMEorDATABASE_URLin.env. - Install the driver package (
better-sqlite3,pgormysql2). The terminal prints... not installed — database browser disabledwhen it is missing. - For SQLite, start your app once so it creates the file, then press Refresh data.
"Can't reach your app" when sending a request
The Studio proxy could not connect to http://localhost: followed by your app port. Make sure the app is running (the sidebar shows App not running when it isn't).
Port already in use
Studio needs app port + 1 to be free. Change PORT so both ports are available:
PORT=3005
# Studio: 3006"No routes discovered"
Studio only finds routes registered with a literal path on app, router or this inside src/. Routes built from variables or registered outside src/ are not listed.
Was this page helpful?