How to Configure Custom Port and Host in JSON Server: Complete Guide

You can configure custom port and host in JSON Server using CLI flags (--port and --host), environment variables (PORT and HOST), or programmatic configuration when embedding the server.

JSON Server provides flexible networking options to adapt to different development environments, from local testing to Docker containers. Whether you need to avoid port conflicts or expose your mock API to external devices, understanding the configuration hierarchy in typicode/json-server ensures reliable deployment.

CLI Configuration Options

The command-line interface defined in src/bin.ts accepts explicit flags for network configuration. These options take precedence over all other configuration methods.

Using Command-Line Flags

Pass -p (or --port) and -h (or --host) directly when starting the server:

json-server --port 4000 --host 0.0.0.0 db.json

According to the source code in src/bin.ts lines 25-28, the flag definitions specify:

• -p, --port <port> defaults to 3000
• -h, --host <host> defaults to localhost

Using Environment Variables

For containerized environments or CI pipelines, set PORT and HOST variables before invoking the command:

PORT=4000 HOST=0.0.0.0 json-server db.json

The CLI merges these values in src/bin.ts lines 48-52, checking for environment variables when flags are not provided.

Configuration Precedence and Defaults

JSON Server resolves port and host settings through a specific hierarchy:

1. CLI flags (--port, --host) — Highest priority
2. Environment variables (PORT, HOST) — Fallback when CLI flags absent
3. Hard-coded defaults (3000, localhost) — Applied when no other values exist

When the server starts, src/bin.ts constructs the display URL using the resolved host and port values (lines 152-176). Setting host to 0.0.0.0 binds the server to all network interfaces, making the mock API accessible from external machines and mobile devices on the same network.

Programmatic Configuration

When embedding JSON Server in a Node.js application rather than using the CLI, pass custom values directly to the listen method:

import { createApp } from './src/app.ts';
import { Low, JSONFile } from 'lowdb';

const adapter = new JSONFile('db.json');
const db = new Low(adapter);
await db.read();

const app = createApp(db, {});

const PORT = 8080;
const HOST = '0.0.0.0';

app.listen(PORT, HOST, () => {
  console.log(`JSON Server running at http://${HOST}:${PORT}`);
});

This approach bypasses the CLI argument parsing in src/bin.ts and allows dynamic configuration based on runtime conditions or external configuration files.

Summary

• CLI flags --port and --host provide the most explicit control over JSON Server networking configuration.
• Environment variables PORT and HOST offer flexibility for Docker containers and deployment pipelines.
• Default values of 3000 and localhost apply when no overrides are specified.
• Programmatic usage allows direct configuration when embedding the server in custom applications.

Frequently Asked Questions

What is the default port for JSON Server?

The default port is 3000, defined in src/bin.ts as the fallback value for the --port option. If port 3000 is already in use, the server will fail to start unless you specify an alternative via CLI flag or environment variable.

How do I expose JSON Server to external networks?

Set the host to 0.0.0.0 using either json-server --host 0.0.0.0 or the HOST environment variable. This binds the server to all available network interfaces, allowing other devices on your local network to access the mock API at your machine's IP address.

Can I use environment variables with Docker?

Yes, environment variables are ideal for Docker deployments. Pass -e PORT=4000 -e HOST=0.0.0.0 to your docker run command, or define them in a docker-compose.yml file. The JSON Server CLI automatically reads these variables when starting the container.

How do I set port and host in package.json scripts?

Add the flags to your npm scripts for consistent development environments:

{
  "scripts": {
    "api": "json-server --watch db.json --port 5000 --host 127.0.0.1",
    "api:public": "json-server --watch db.json --port 4000 --host 0.0.0.0"
  }
}

Run with npm run api or npm run api:public to start the server with your predefined network configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}