Serve up JSON files

  • jserve

Downloads in past


303.0.0a year ago7 years agoMinified + gzip package size for jserve in KB


Serve up JSON files.

Table of Contents

Requirements Usage
* [Serving JSON Files](#serving-json-files)
* [Command-Line Interface](#command-line-interface)
* [JavaScript Interface](#javascript-interface)
* [Configuration](#configuration)
Contributing License


This library requires the following to run:
Node.js 12+


Serving JSON Files

The JServe Index Page
Whether you're running JServe through the Command-Line or JavaScript interfaces, it will accept a directory of JSON (or JavaScript) files and serve them through a web server.
If you run JServe on port 3000, and you have the following JSON files:
├── foo.json
├── bar.json
└── baz.js

Then you will be able to visit http://localhost:3000/foo to see the contents of foo.json.
If you navigate to the index page of a running JServe application (e.g. http://localhost:3000/) you will see a HTML index page listing all of the available JSON files.
When using JavaScript files in place of JSON, you must use module.exports to decide what gets output:
module.exports = {
    foo: 'bar'

These JavaScript files are run in a limited Node.js sandbox to prevent them from crashing JServe.

Command-Line Interface

Install JServe globally with npm:
npm install -g jserve

This installs the jserve command-line tool:
Usage: jserve [options]


  -h, --help                         output usage information
  -V, --version                      output the version number
  -p, --port <port>                  the port to run on. Default: 3000
  -j, --json <path>                  the path to look for JSON files in. Default: ./json
  -c, --content-type <content-type>  the Content-Type header to send when serving JSON. Default: application/json
  -i, --indentation <level>          The number of spaces or tabs to use for JSON indentation. Default: 4
  -t, --templates <path>             The path to look for template files in
  -n, --name <name>                  The name of the server, used in template headings. Default: JServe

Run JServe on port 1234:
jserve --port 1234

Run JServe on a different directory of JSON files:
jserve --json ./my-folder-of-json

Run JServe, outputting JSON with a different content-type and tab-indentation:
jserve --content-type application/my-custom+json --indentation \t

JavaScript Interface

Install JServe with npmnpm or add to your package.json:
npm install jserve

Require JServe:
const jserve = require('jserve');

Create a JServe application, passing in options:
const app = jserve({
    // options

Start the JServe application:



String. The Content-Type header to send when serving JSON and JavaScript files. Default: application/json.
const app = jserve({
    contentType: 'application/my-custom+json'


String. The descriptive text which appears above the file list in the index page. Default: View JSON files by clicking the file names below:.
const app = jserve({
    description: 'Try one of these on for size:'


Number or String. The indentation level to use for output JSON. If set to a number, indentation will be set to that number of spaces. If set to a string, the given string will be used to indent. Default: 4.
const app = jserve({
    indentation: '\t'


Object. An object with the methods debug, error, and info which will be used to report errors and request information. Default: no op functions.
const app = jserve({
    log: {
        debug: console.log.bind(console),
        error: console.error.bind(console),
        info: console.log.bind(console)


Array. An array of Connect middleware which will be run before the index and JSON serving parts of JServe. Along with the template option, this allows you to extend JServe easily with functionality of your own. Default: [].
const app = jserve({
    middleware: [
        function (request, response, next) {
            if (request.path === '/hello') {
                return response.end('Hello World!');


String. The name of the server, which appears in page titles and the logs. Default: JServe.
const app = jserve({
    name: 'My JSON'


String. The path to look for JSON and JavaScript files in. It's best to set this to an absolute path. Default: ./json.
const app = jserve({
    path: `${__dirname}/my-folder-of-json`


Number. The port to bind the JServe application to. Default: The PORT environment variable or 3000.
const app = jserve({
    port: 1234


String. The path that JServe should look for HTML templates in. JServe expects to find at least two files in the given directory: error.html and index.html. These templates are written in Mustache. Default: <core>/template.


The contributing guide is available here. All contributors must follow this library's code of conduct.


Licensed under the MIT license.
Copyright © 2015, Rowan Manning