Add a programmatic API (fixes #86)

lib/api.js

@@ -0,0 +1,34 @@
+// Native
+const {spawn} = require('child_process')
+const path = require('path')
+
+// Packages
+const dargs = require('dargs')
+
+module.exports = (options = {}, directory = process.cwd()) => {
+  const scriptPath = path.join(__dirname, '..', 'bin', 'serve.js')
+  const aliases = {cors: 'o'}
+
+  options._ = [directory]  // Let dargs handle the directory argument
+
+  // The CLI only understands comma-separated values for ignored files
+  // So we join the string array with commas
+  if (options.ignore) {
+    options.ignore = options.ignore.join(',')
+  }
+
+  const args = [
+    scriptPath,
+    ...dargs(options, {aliases})
+  ]
+
+  const cli = spawn('node', args, {
+    stdio: 'inherit'
+  })
+
+  return {
+    stop() {
+      cli.kill()
+    }
+  }
+}

package.json

@@ -13,6 +13,7 @@
     "views"
   ],
   "repository": "zeit/serve",
+  "main": "./lib/api.js",
   "bin": {
     "serve": "./bin/serve.js"
   },
@@ -53,6 +54,7 @@
     "boxen": "1.0.0",
     "chalk": "1.1.3",
     "copy-paste": "1.3.0",
+    "dargs": "5.1.0",
     "detect-port": "1.1.0",
     "filesize": "3.5.4",
     "fs-promise": "2.0.0",

readme.md

@@ -36,6 +36,62 @@ serve help
 
 If you set the `--auth` flag, the package will look for a username and password in the `SERVE_USER` and `SERVE_PASSWORD` environment variables.
 
+## API
+
+Install it (needs at least Node LTS):
+
+```bash
+npm install serve
+```
+
+You can now use it in your code:
+
+```js
+const serve = require('serve')
+
+const options = {
+  port: 1337,
+  cache: 0
+}
+
+const server = serve(options)
+
+// ...
+
+server.stop()
+
+```
+
+### Options
+
+#### `port: number`
+
+Port to listen on
+
+#### `cache: number`
+
+Time in milliseconds for caching files in the browser
+
+#### `single: boolean`
+
+Serve single page apps with only one `index.html`
+
+#### `unzipped: boolean`
+
+Disable GZIP compression
+
+#### `ignore: string[]`
+
+Files and directories to ignore
+
+#### `auth: boolean`
+
+Serve behind basic auth
+
+#### `cors: boolean`
+
+Setup * CORS headers to allow requests from any origin
+
 ## Contributing
 
 1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device