done-serve/README.md

DoneJS development server

# done-serve

[![Join the chat at https://gitter.im/donejs/donejs](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/donejs/donejs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/donejs/done-serve/blob/master/LICENSE.md)
[![npm version](https://badge.fury.io/js/done-serve.svg)](http://badge.fury.io/js/done-serve)
[![Build Status](https://travis-ci.org/donejs/done-serve.svg?branch=master)](https://travis-ci.org/donejs/done-serve)
[![Greenkeeper badge](https://badges.greenkeeper.io/donejs/done-serve.svg)](https://greenkeeper.io/)

A simple development server for DoneJS projects.

- [Install](#install)
- [Usage](#usage)
- [Options](#options)
  - <code>[-p, --port](#-p---port)</code>
  - <code>[-r, --proxy](#-r---proxy)</code>
  - <code>[-t, --proxy-to](#-t---proxy-to)</code>
  - <code>[--proxy-no-cert-check](#--proxy-no-cert-check)</code>
  - <code>[-d, --develop](#-d---develop)</code>
  - <code>[-l, --no-live-reload](#-l---no-live-reload)</code>
  - <code>[--live-reload-port](#--live-reload-port)</code>
  - <code>[-s, --static](#-s--static)</code>
  - <code>[--error-page](#--error-page)</code>
  - <code>[--timeout](#--timeout)</code>
  - <code>[--debug](#--debug)</code>
  - <code>[--key](#--key)</code>
  - <code>[--cert](#--cert)</code>
  - <code>[--strategy](#--strategy)</code>

## Install

```
npm install done-serve
```

## Usage

```
node_modules/.bin/done-serve [path] [options]
```

`[path]` is the root directory. Defaults to the current working directory.

To start a full server that hosts your application from the `./dist` directory on port `3030` run:

```
node_modules/.bin/done-serve dist --port 3030
```

## Options

The following `[options]` can be specified from the command line:

### -p, --port

Specify the **port** the server should run on. If unspecified this port will be one of:

* the `PORT` environment variable
* `3030`

### -r, --proxy

Proxy a local path (default: `/api`) to the given URL (e.g. `http://api.myapp.com`).

### -t, --proxy-to

Set the proxy endpoint (default: `/api`).

### --proxy-no-cert-check

Turn off SSL certificate verification.

### -d, --develop

Start a [live-reload](http://stealjs.com/docs/steal.live-reload.html) server so any code changes will be reflected immediately.

### -l, --no-live-reload

Disable [live-reload](http://stealjs.com/docs/steal.live-reload.html) when used with the `--develop` option.

### --live-reload-port

Specify the port (a `Number`) to use for live-reload. The default port is specified in the [LiveReloadOptions](https://stealjs.com/docs/steal.live-reload.options.html) documentation.

### -s, --static

Only serve static files, do not perform server-side rendering. Notably this is useful when debugging an issue in the app.

### --error-page <filename>

With the `--static` flag set, set an HTML page that should be sent instead of the normal error page. This is useful when you want to use Pushstate without server side rendering.

### --auth-cookie

Specifies the name of a cookie that [done-ssr](https://github.com/donejs/done-ssr#options) will use to enable JavaScript Web Token (JWT) auth.

### --auth-domains

A comma-separated string of domain names that are authorized to receive the JWT token.  Required if `--auth-cookie` is used.

### --timeout

Specify a timeout for server rendering. If the timeout is exceeded the server will return whatever has been rendered up until that point. (default: `5000`)

### --debug

Enable debug information in case of a timeout. The debug information will be appended to the document as a modal window and provides stack traces. Only use this flag during development.

### --key, --cert

Provide SSL key and certificate files. When providing these options both HTTP and HTTP2 servers will be set up, with automatic forwarding.

```shell
done-serve --static --key ~/.localhost-ssl/private.pem --cert ~/.localhost-ssl/cert.pem
```

### --strategy

Provides which rendering strategy to use. By default done-ssr waits for all asynchronous tasks to complete before serializing HTML and returning that to the browser. The options are:

* **safe**: The default strategy as described above.
* **incremental**: This rendering strategy prioritizes returning HTML to the browser sooner. Along with the HTML a shim is sent that communicates with the server to receive rendering instructions. This allows a faster rendering experience in browsers that support HTTP2. This strategy will silently fall back to the **safe** strategy if HTTP2 is not supported. Using this option requires also providing **--key** and **--cert** flags, as HTTP2 requires SSL.

## Usage in Node

You can also use the server, with the same options, from JavaScript:

```js
var server = require("done-serve");

server({
path: "path/to/dir"
});
```

## Changelog

See the [latest releases on GitHub](https://github.com/donejs/done-serve/releases).

## Contributing

The [DoneJS contribution guide](https://donejs.com/contributing.html) has information on getting help, reporting bugs, developing locally, and more.

## License

[MIT](https://github.com/donejs/done-serve/blob/master/LICENSE.md)