gio dev

Run the GioJS server in development mode: the project is watched, edits restart the Node worker and reload open tabs, and errors show in an overlay.

npx gio dev

pnpm exec gio dev

yarn gio dev

bunx gio dev

gio dev [--port <port>] [--host <ip>] [--open]

Reference

Behavior

1. Finds the server binary (GIO_SERVER_BIN, else the @gio.js/server-<platform> package). Without one it prints which package to install and exits with 1 (see When the server binary is missing).
2. Asks the binary where it will listen (giojs-server --check-config), so the address comes from the same sources the server uses: GIO_PORT / GIO_HOST (which --port / --host set), then PORT - each from the environment or, when the environment does not set it, the .env files - then gio.toml's [server] table, then 0.0.0.0:3000.
3. Starts the server with NODE_ENV=development, whatever the shell had, and with GIO_EXIT_ON_STDIN_EOF=1 and a stdin pipe it never writes: if the gio process dies, even by SIGKILL, the server sees the pipe close and shuts down instead of holding the port.
4. Polls /_gio/health until it reports the Node worker ready (or, with [health] enabled = false, until anything answers), then prints the banner below and opens the browser for --open.
5. Stays in the foreground until the server exits, and exits with the server's exit code (1 if the server was killed by a signal). Ctrl+C and SIGTERM shut the server down gracefully.

  GioJS 0.1.0-beta.8 (dev)
  - Local:    http://localhost:3000
  - Network:  http://192.168.1.20:3000

Network lists one URL per non-internal IPv4 address when the server listens on every interface. With a loopback host it says not exposed (listening on loopback only; use --host 0.0.0.0). The banner is skipped when the configuration has an error (the server prints it and exits 1) and when the port is 0.

What development mode changes

The mode is the server's, and the Node worker always runs in the same one. In development:

• The .env.development.local, .env.local, .env.development and .env files load (see Environment Variables).
• Render errors show in the error overlay with a code frame and an open-in-editor link, and /_gio/devtools serves the dev dashboard. Both answer only local hosts unless [dev] allowed_hosts lists more (see Dev endpoints); [dev] devtools = false turns them off.
• require_session guards work without GIO_SESSION_SECRET: the server generates an ephemeral secret, so sessions reset when it restarts.
• One render worker, whatever [server] workers says: every edit restarts it with a fresh build.
• The project is watched (next section).

File watching

The whole project is watched, not just app/. A change under app/, in components/, lib/, src/, hooks/, or to gio.toml, gio.config.ts, middleware.ts or tsconfig.json clears the page cache, re-transforms app CSS, restarts the Node worker and reloads open tabs. Edits under public/ refresh which files are served at the site root and reload the browser without a restart.

• A gio.toml edit restarts the worker, but the new settings do not apply: the Rust server reads gio.toml once, at startup. Stop and start gio dev after changing it. The same goes for the .env files, which are read once too; editing them restarts nothing.
• Any change under app/ restarts the worker. Elsewhere only these extensions do: .ts .tsx .js .jsx .mjs .cjs .mts .cts .json .css .toml, plus directories created, deleted or moved. Databases, logs and uploads the app writes into the project never restart the worker that wrote them.
• Never watched: node_modules/ at any depth, hidden directories such as .git/ and .gio/ (except .well-known/), and the top-level out/, dist/, build/, target/, standalone/ and coverage/. Editor scratch files (~ backups, .swp / .swx, 4913, .# locks) are ignored.
• [dev] watch_ignore globs exclude more (data files with a source extension, like data/*.json), and [dev] watch = false turns the watcher off.
• Ignored directories are kept out of the watch registration, so a large node_modules/ does not use up Linux inotify watches. If a project hits the limit anyway, the server logs which directory went unwatched; raise fs.inotify.max_user_watches.

Examples

Pick a port and open the browser

gio dev --port 4000 --open

Listen on this machine only

$ gio dev --host 127.0.0.1

  GioJS 0.1.0-beta.8 (dev)
  - Local:    http://localhost:3000
  - Network:  not exposed (listening on loopback only; use --host 0.0.0.0)

From a package.json script

{
  "scripts": {
    "dev": "gio dev",
    "start": "gio start"
  }
}

Starters made by create-giojs run the server through cross-env NODE_ENV=development giojs-server instead (see giojs-server); both start the same server. With the Tailwind feature, keep npm run dev: it runs the Tailwind watcher next to the server, which gio dev alone does not.

A mistyped option

$ gio dev --prot 4000
gio: unknown option "--prot" - did you mean --port?
Run `gio dev --help` for usage.
$ echo $?
2

Good to know

• NODE_ENV from the shell is ignored: gio dev always runs development and gio start always runs production. NODE_ENV in a .env file is ignored too.
• There is no build step before the server starts. Routes and client bundles are built at startup into .gio/build, and .gio/routes.d.ts is rewritten.
• The server binds its port only once the first worker is ready, so a request never reaches a server that cannot render yet.
• Exit codes: 0 after a clean shutdown, 1 for a missing binary or when the server fails (its own code is passed through), 2 for a usage error.

Related

• gio start - the same command in production mode
• gio doctor - check the setup when gio dev will not start
• Listen address and dev watcher settings in gio.toml
• Installation
• CLI overview

Version history