1 | ![](https://assets.zeit.co/image/upload/v1527770721/repositories/serve/serve-repo-banner.png)
|
2 |
|
3 | [![Build Status](https://circleci.com/gh/zeit/serve.svg?&style=shield)](https://circleci.com/gh/zeit/serve)
|
4 | [![Install Size](https://packagephobia.now.sh/badge?p=serve)](https://packagephobia.now.sh/result?p=serve)
|
5 | [![Join the community on Spectrum](https://withspectrum.github.io/badge/badge.svg)](https://spectrum.chat/zeit)
|
6 |
|
7 | Assuming you would like to serve a static site, single page application or just a static file (no matter if on your device or on the local network), this package is just the right choice for you.
|
8 |
|
9 | Once it's time to push your site to production, we recommend using [ZEIT Now](https://zeit.co/now).
|
10 |
|
11 | In general, `serve` also provides a neat interface for listing the directory's contents:
|
12 |
|
13 | ![screenshot](https://user-images.githubusercontent.com/6170607/40541195-167ff460-601b-11e8-8f66-3b0c7ff96cbb.png)
|
14 |
|
15 | ## Usage
|
16 |
|
17 | The quickest way to get started is to just run `npx serve` in your project's directory.
|
18 |
|
19 | If you prefer, you can also install the package globally using [Yarn](https://yarnpkg.com/en/) (you'll need at least [Node.js LTS](https://nodejs.org/en/)):
|
20 |
|
21 | ```bash
|
22 | yarn global add serve
|
23 | ```
|
24 |
|
25 | Once that's done, you can run this command inside your project's directory...
|
26 |
|
27 | ```bash
|
28 | serve
|
29 | ```
|
30 |
|
31 | ...or specify which folder you want to serve:
|
32 |
|
33 | ```bash
|
34 | serve folder_name
|
35 | ```
|
36 |
|
37 | Finally, run this command to see a list of all available options:
|
38 |
|
39 | ```bash
|
40 | serve --help
|
41 | ```
|
42 |
|
43 | Now you understand how the package works! :tada:
|
44 |
|
45 | ## Configuration
|
46 |
|
47 | To customize `serve`'s behavior, create a `serve.json` file in the public folder and insert any of [these properties](https://github.com/zeit/serve-handler#options).
|
48 |
|
49 | ## API
|
50 |
|
51 | The core of `serve` is [serve-handler](https://github.com/zeit/serve-handler), which can be used as middleware in existing HTTP servers:
|
52 |
|
53 | ```js
|
54 | const handler = require('serve-handler');
|
55 | const http = require('http');
|
56 |
|
57 | const server = http.createServer((request, response) => {
|
58 | // You pass two more arguments for config and middleware
|
59 | // More details here: https://github.com/zeit/serve-handler#options
|
60 | return handler(request, response);
|
61 | })
|
62 |
|
63 | server.listen(3000, () => {
|
64 | console.log('Running at http://localhost:3000');
|
65 | });
|
66 | ```
|
67 |
|
68 | **NOTE:** You can also replace `http.createServer` with [micro](https://github.com/zeit/micro), if you want.
|
69 |
|
70 | ## Contributing
|
71 |
|
72 | 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
|
73 | 2. Uninstall `serve` if it's already installed: `npm uninstall -g serve`
|
74 | 3. Link it to the global module directory: `npm link`
|
75 |
|
76 | After that, you can use the `serve` command everywhere. [Here](https://github.com/zeit/serve/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+for+beginners%22)'s a list of issues that are great for beginners.
|
77 |
|
78 | ## Credits
|
79 |
|
80 | This project used to be called "list" and "micro-list". But thanks to [TJ Holowaychuk](https://github.com/tj) handing us the new name, it's now called "serve" (which is much more definite).
|
81 |
|
82 | ## Author
|
83 |
|
84 | Leo Lamprecht ([@notquiteleo](https://twitter.com/notquiteleo)) - [ZEIT](https://zeit.co)
|