Configuration

yRest options can be set in three places: schema defaults, a yrest.config.yml file, and CLI flags. The resolution order is schema defaults → config file → CLI flags — each source overrides the one to its left.

The config file

yrest.config.yml lives in the same directory as your db.yml. The init command creates both files at once:

# bash - init command
npx @yrest/cli init

A complete config file with all options looks like this:

yrest.config.yml

port: 3070
host: localhost
base: ""
watch: false
readonly: false
delay: 0
snapshot: false
pageable: false
idStrategy: increment
# handlers: ./yrest.handlers.js

You only need to include the options you want to override — any key you omit falls back to the schema default.

Priority rules

Source	Priority	When it applies
Schema defaults	Lowest	Always — the built-in fallback
yrest.config.yml	Middle	When the file exists in the working directory
CLI flags	Highest	When explicitly passed to yrest serve

A flag passed on the command line always wins over the config file. The config file always wins over the built-in defaults.

Options reference

All options below can be set in yrest.config.yml, passed as CLI flags to yrest serve, or both. Values from the config file override built-in defaults; CLI flags override everything. Start with the defaults and add only what you need — for most projects a couple of entries are enough.

port

The TCP port the server listens on. Port 3070 was chosen to avoid conflicts with the most common development ports (3000, 3001, 4000, 8080, 8000), so you can run yRest alongside your frontend dev server without changing any config.

Type	number
Default	3070
CLI flag	-p, --port <n>

port: 4000

npx @yrest/cli serve db.yml --port 4000

---

host

The hostname or IP address the server binds to. The default localhost makes the server reachable only from the same machine. Set to 0.0.0.0 to expose the server on all network interfaces — useful inside Docker containers or when other devices on the LAN need to reach it.

Type	string
Default	"localhost"
CLI flag	-H, --host <host>

host: 0.0.0.0 # expose on all interfaces

---

base

A URL prefix prepended to every route — both CRUD collection routes and custom _routes entries. A leading slash is added automatically if you omit it.

With base: /api/v1, the collection users is exposed at /api/v1/users instead of /users. The /_about and /_snapshot meta endpoints are not prefixed.

Type	string
Default	"" (none)
CLI flag	-b, --base <path>

base: /api/v1

3070/api/v1/users

npx @yrest/cli serve db.yml --base /api/v1

---

watch

When enabled, yRest watches db.yml for file system changes and reloads automatically without restarting the process. Any collection, relation, or custom route you add to the file appears immediately in the running server.

This is useful during active development when you are editing the data file frequently. In CI or production-like environments, leave it false so the data stays stable throughout a test run.

Type	boolean
Default	false
CLI flag	-w, --watch

watch: true

---

readonly

When enabled, all mutating requests — POST, PUT, PATCH and DELETE — are rejected with 405 Method Not Allowed. GET requests and meta endpoints (/_about, /_snapshot) continue to work normally.

Use this when you want to share a stable mock that cannot be accidentally modified — for example, a shared staging environment, a demo, or a read-only API fixture in a test suite where writes are not expected.

Type	boolean
Default	false
CLI flag	-r, --readonly

readonly: true

---

delay

Adds a fixed latency to every response before it is sent. This simulates a slow network or a high-latency backend, making it easier to test loading states, skeleton screens, and timeout handling in your frontend.

The delay applies to all routes — collection endpoints, custom routes, and SSE connections. For per-route latency on individual _routes entries, use the delay: key inside the route definition instead.

Type	number (milliseconds)
Default	0 (disabled)
CLI flag	-d, --delay <ms>

delay: 300 # simulate a 300 ms round trip

---

snapshot

When enabled, yRest saves the initial state of the database at startup and exposes three meta endpoints for saving and restoring it on demand. This is the recommended approach for keeping test suites isolated — reset the database to a known state before each test without restarting the server.

Type	boolean
Default	false
CLI flag	-s, --snapshot

The three endpoints exposed when snapshot: true:

Endpoint	Method	Description
/_snapshot	GET	Returns snapshot metadata (timestamp of last save)
/_snapshot/save	POST	Replaces the saved snapshot with the current live state
/_snapshot/reset	POST	Restores the database to the last saved snapshot

This is most useful in integration test suites: call POST /_snapshot/reset in a beforeEach hook to guarantee a clean, deterministic state before every test. Changes accumulated during one test never leak into the next.

snapshot: true

# Reset the database to its initial state between test runs
curl -X POST http://localhost:3070/_snapshot/reset

---

pageable

When enabled, GET collection responses are wrapped in a { data, pagination } envelope instead of returning a plain array. This is useful when your frontend expects a structured response with metadata, rather than a raw array. Accepts true for the default page size (10) or a number to set a custom default.

Type	boolean or number
Default	false
CLI flag	--pageable [limit]

With pageable enabled, the response shape looks like this:

{
  "data": [
    { "id": 1, "name": "Ana" },
    { "id": 2, "name": "Luis" }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "pages": 5
  }
}

Accepts three forms:

Value	Behaviour
false	Disabled — plain array responses (default)
true	Enabled with a default page size of 10
number	Enabled with a custom default page size

pageable: true   # enabled, 10 items per page by default
pageable: 20     # enabled, 20 items per page by default

The per-request ?_page and ?_limit query parameters always override the configured default. If a client sends ?_page=2&_limit=5 the server uses those values regardless of what pageable is set to.

---

idStrategy

Controls how id values are generated when a new item is created via POST without an explicit id in the request body. Use uuid when your frontend expects string IDs, when items from multiple collections need globally unique identifiers, or when you need IDs that are stable and meaningful across restarts.

Type	"increment" | "uuid"
Default	"increment"
CLI flag	--id-strategy <strategy>

Strategy	Behaviour
increment	Next integer above the current maximum id in the collection
uuid	A random UUID v4 string from crypto.randomUUID()

idStrategy: uuid

--uuid is a shorthand CLI flag for --id-strategy uuid:

npx @yrest/cli serve db.yml --uuid

This flag only affects IDs assigned to new items created via POST. To pre-populate your db.yml with UUID-based IDs from the start, use the __uuid_gen directive in the file instead.

---

handlers

Path to a JavaScript file exporting handler functions used by _routes entries. yRest loads the file at startup and calls the exported function whose name matches the handler: key in the route definition. If omitted, yRest still auto-discovers yrest.handlers.js (or .mjs) in the current working directory.

Type	string (file path)
Default	(auto-discovered)
CLI flag	--handlers <file>

handlers: ./yrest.handlers.js

Use the explicit path when your handlers file has a different name or lives in a subdirectory.

---

Full example

A config file for a CI environment that simulates realistic latency and resets cleanly between test runs:

yrest.config.yml

port: 3070
host: 0.0.0.0 # expose on all interfaces (Docker / CI runner)
base: /api/v1
watch: false # stable data during the test run
readonly: false # tests need to write
delay: 120 # simulate realistic network latency
snapshot: true # enable POST /_snapshot/reset between test suites
pageable: 20 # default page size for list endpoints
idStrategy: uuid # string IDs expected by the frontend
handlers: ./tests/handlers.js

Next steps

• Server Modes — deeper explanation of watch, readonly, delay, snapshot and pageable behaviour
• CLI Reference — full flag syntax for every command
• Handler Functions — the handler: key and the handlers file format