Dicoy

Easily create a mock server based on your filesytem dir structure.

Installation

NPM

npm install dicoy

PNPM

pnpm add dicoy

Yarn

yarn add dicoy

Quick start (In a project)

Create a project with following structure

mock-server
├── dicoy.config.json
├── package.json
└── src
    ├── server-1
    │   ├── me
    │   │   └── GET.json
    │   └── send
    │       └── POST.json
    └── server-2
        └── users
            ├── :userId
            │   └── GET.json
            └── GET.JSON

Install dependency

npm install dicoy
# pnpm install dicoy
# yarn add dicoy

Define content of files

dicoy.config.json

{
  "$schema": "node_modules/dicoy/$schema.config.json",
  "servers": [
    {
      "name": "server-1",
      "src": "src/server-1",
      "port": 9001,
      "basePath": "/api"
    },
    {
      "name": "server-2",
      "src": "src/server-2",
      "port": 9002,
      "basePath": "/"
    }
  ]
}

src/server-1/me/GET.json

{
  "data": {
    "name": "Jon Doe",
    "email": "[email protected]",
    "org": "Dunder Mifflin"
  }
}

src/server-1/send/POST.json

{
  "inputValidator": {
    "title": "string",
    "email": "string.email",
    "body?": "string"
  },
  "data": {
    "message": "Successfully created"
  }
}

src/server-2/users/GET.json

{
  "data": [
    {
      "id": 1,
      "name": "Jon Doe",
      "email": "[email protected]",
      "org": "Dunder Mifflin"
    },
    {
      "id": 2,
      "name": "Peter Parker",
      "email": "[email protected]",
      "org": "Dunder Mifflin"
    }
  ]
}

src/server-2/users/:userId/GET.json

{
  "data": {
    "title": "Example of dynamic route"
  }
}

Add dev script to your package.json

{
  "scripts": {
    "dev": "dicoy serve"
  }
}

Run the mock server

npm run dev
# pnpm run dev
# yarn dev

🎉 Your mock server is now running

Try CURL some end points

curl localhost:9001/api/me
## `/api` is prefixed because it is defined in `dicoy.config.json` as `basePath`
# {
#   "name": "Jon Doe",
#   "email": "[email protected]",
#   "org": "Dunder Mifflin"
# }

curl localhost:9001/api/send --data '{"title": "Hello", "email": "bad-email"}' -v
## Bad input response because validation failed for email
# * Host localhost:9001 was resolved.
# * IPv6: ::1
# * IPv4: 127.0.0.1
# *   Trying [::1]:9001...
# * Connected to localhost (::1) port 9001
# > POST /api/send HTTP/1.1
# > Host: localhost:9001
# > User-Agent: curl/8.7.1
# > Accept: */*
# > Content-Length: 40
# > Content-Type: application/x-www-form-urlencoded
# >
# * upload completely sent off: 40 bytes
# < HTTP/1.1 400 Bad Request
# < Content-Type: application/json
# < Date: Fri, 10 Oct 2025 12:53:42 GMT
# < Connection: keep-alive
# < Keep-Alive: timeout=5
# < Transfer-Encoding: chunked
# <
# * Connection #0 to host localhost left intact
# [{"message":"an email address","path":["email"]}]%

curl localhost:9001/api/send --data '{"title": "Hello", "email": "[email protected]"}'
# {"message":"Successfully created"}

curl localhost:9002/users/2
## Matching /users/:userId/GET.json in `server-2` directory
# {"title":"Example of dynamic route"}

Quick start (CLI)

Globally install the package

npm install --global dicoy
# pnpm install --global dicoy
# yarn global add dicoy

Run server command

dicoy serve

Options

| Option | Default value | Description | | ---------- | ------------- | --------------------------------------------------- | | --name | | Name for your server. This name is prefixed in logs | | --src | . | Source directory of your file base mock server | | --port | 8080 | Port for your server | | --basePath | | Path prefix for your api routes |

Config file schema

Typescript equivalent type of dicoy.config.json is defined by the type DicoyServerConfig below.

type ServerEntry = {
  name?: string
  src?: string
  port?: string
  basePath?: string
}

type DicoyServerConfig = {
  servers: ServerEntry[]
}

Response file

Response file is defined as <http method in upper case>.json.

File content

{
  "data": "..content..."
}

data

Data can be string, json object or json array. The Content-type header is inferred as text/plain if data is string and application/json otherwise, unless an explicit Content-Type header is declared.

headers

A map of headers to be sent back.

inputValidator

This can be defined any non-GET requests. For validation Arktype is used. The value can be anything that is understood by Arktype in json format.