1 | ![Serve Logo](https://raw.githubusercontent.com/vercel/serve/main/media/banner.png)
|
2 |
|
3 | <div align="center">
|
4 | <a aria-label="Vercel logo" href="https://vercel.com">
|
5 | <img src="https://img.shields.io/badge/made%20by-vercel-%23000000">
|
6 | </a>
|
7 | <br>
|
8 | <a aria-label="Install Size" href="https://packagephobia.com/result?p=serve">
|
9 | <img src="https://packagephobia.com/badge?p=serve">
|
10 | </a>
|
11 | <a aria-label="Stars" href="https://github.com/vercel/serve/stargazers">
|
12 | <img src="https://img.shields.io/github/stars/vercel/serve">
|
13 | </a>
|
14 | <a aria-label="Build Status" href="https://github.com/vercel/serve/actions/workflows/ci.yaml">
|
15 | <img src="https://github.com/vercel/serve/actions/workflows/ci.yaml/badge.svg">
|
16 | </a>
|
17 | </div>
|
18 |
|
19 | ---
|
20 |
|
21 | `serve` helps you serve a static site, single page application or just a static file (no matter if on your device or on the local network). It also provides a neat interface for listing the directory's contents:
|
22 |
|
23 | ![Listing UI](https://raw.githubusercontent.com/vercel/serve/main/media/listing-ui.png)
|
24 |
|
25 | > Once it's time to push your site to production, we recommend using [Vercel](https://vercel.com).
|
26 |
|
27 | ## Usage
|
28 |
|
29 | The quickest way to get started is to just run `npx serve` in your project's directory.
|
30 |
|
31 | If you prefer, you can also install the package globally (you'll need at least [Node LTS](https://github.com/nodejs/Release#release-schedule)):
|
32 |
|
33 | ```bash
|
34 | > npm install --global serve
|
35 | ```
|
36 |
|
37 | Once that's done, you can run this command inside your project's directory...
|
38 |
|
39 | ```bash
|
40 | > serve
|
41 | ```
|
42 |
|
43 | ...or specify which folder you want to serve:
|
44 |
|
45 | ```bash
|
46 | > serve folder-name/
|
47 | ```
|
48 |
|
49 | Finally, run this command to see a list of all available options:
|
50 |
|
51 | ```bash
|
52 | > serve --help
|
53 | ```
|
54 |
|
55 | Now you understand how the package works! :tada:
|
56 |
|
57 | ## Configuration
|
58 |
|
59 | To customize `serve`'s behavior, create a `serve.json` file in the public folder and insert any of [these properties](https://github.com/vercel/serve-handler#options).
|
60 |
|
61 | ## API
|
62 |
|
63 | The core of `serve` is [serve-handler](https://github.com/vercel/serve-handler), which can be used as middleware in existing HTTP servers:
|
64 |
|
65 | ```js
|
66 | const handler = require('serve-handler');
|
67 | const http = require('http');
|
68 |
|
69 | const server = http.createServer((request, response) => {
|
70 | // You pass two more arguments for config and middleware
|
71 | // More details here: https://github.com/vercel/serve-handler#options
|
72 | return handler(request, response);
|
73 | });
|
74 |
|
75 | server.listen(3000, () => {
|
76 | console.log('Running at http://localhost:3000');
|
77 | });
|
78 | ```
|
79 |
|
80 | > **Note**
|
81 | >
|
82 | > You can also replace `http.createServer` with [micro](https://github.com/vercel/micro).
|
83 |
|
84 | ## Issues and Contributing
|
85 |
|
86 | If you want a feature to be added, or wish to report a bug, please open an issue [here](https://github.com/vercel/serve/issues/new).
|
87 |
|
88 | If you wish to contribute to the project, please read the [contributing guide](contributing.md) first.
|
89 |
|
90 | ## Credits
|
91 |
|
92 | 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).
|
93 |
|
94 | ## Author
|
95 |
|
96 | Leo Lamprecht ([@notquiteleo](https://twitter.com/notquiteleo))
|