Skip to content

Commit 607efc4

Browse files
committed
docs: improve README
1 parent 7ed932f commit 607efc4

1 file changed

Lines changed: 31 additions & 12 deletions

File tree

‎README.md‎

Lines changed: 31 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,22 @@
11
# HTTPS server running on localhost
22

3-
Run a server on localhost with a locally-trusted SSL certificate. Serve static files, proxies an existing server, or you can import as module in your project.
3+
Run a server on localhost with a locally-trusted SSL certificate. Serve static files, define your own routes, or import it as a module in your project.
44

5-
The certificate is provided by [mkcert](https://github.com/FiloSottile/mkcert). It automatically creates and installs a local CA in the system and browsers root store, and use it to generate certificates that your machine trust. **This are not valid certificates, are for development only, and will only work in your machine.**
5+
The certificate is provided by [mkcert](https://github.com/FiloSottile/mkcert). It automatically creates and installs a local CA in the system and browser root stores, and uses it to generate certificates that your machine trusts. **These are not valid certificates, they are for development only, and will only work in your machine.**
66

77
Certificates support macOS, Linux and Windows. [The full list of supported root stores is available in the original repo](https://github.com/FiloSottile/mkcert/blob/v1.4.4/README.md#supported-root-stores).
88

99
## Install and use standalone
1010

1111
```sh
1212
# install
13-
npm i -g --only=prod https-localhost
13+
npm i -g https-localhost
1414

1515
# run
1616
serve ~/myproj
1717
```
1818

19-
How it works:
19+
Usage notes:
2020

2121
- `sudo` may be necessary.
2222
- If a static path is not provided the current directory content will be served.
@@ -27,6 +27,8 @@ How it works:
2727
- `--reinstall`: force certificate re-generation (`REINSTALL=true`)
2828
- Specifying a port number prevents HTTP to HTTPS redirect.
2929

30+
### Standalone binaries
31+
3032
If you don't have Node.js installed just use a packaged version! Download it from the [release page](https://github.com/daquinoaldo/https-localhost/releases).
3133

3234
## Use as module
@@ -40,22 +42,39 @@ npm i -D https-localhost
4042
Then put in your `index.js` file:
4143

4244
```js
43-
const app = require("https-localhost")()
45+
import { createServer } from "https-localhost"
46+
// or, in CommonJS:
47+
// const { createServer } = require("https-localhost")
48+
49+
const app = createServer()
50+
app.listen() // optionally, specify a port
51+
app.redirect() // enable http to https
52+
app.serve(path) // serve static files
53+
54+
// optionally, define your own routes (GET only)
55+
app.get("/api/hello", (req, res) => res.end("Hello, world!"))
56+
```
4457

45-
app.listen()
46-
app.redirect()
47-
app.serve(path)
58+
Alternatively, you can use the certificates in your own server:
59+
60+
```js
61+
import https from "node:https"
62+
import { getCerts } from "https-localhost/certs"
63+
// or, in CommonJS:
64+
// const { getCerts } = require("https-localhost/certs")
4865

49-
// or get the certificates and use them in your own server
50-
const { getCerts } = require("https-localhost/certs")
5166
const certs = await getCerts()
67+
68+
https.createServer(certs, (_, res) => res.end("Hello, world!")).listen(443)
5269
```
5370

71+
Uninstalling the npm package removes the generated certificates automatically.
72+
5473
## Troubleshooting
5574

5675
### root required
5776

58-
- **At first run** this tool generate a trusted certificate. The sudo password may be required. If you cannot provide the sudo password generate a `localhost.key` and `localhost.crt` and specify its path with `CERT_PATH=/diractory/containing/certificates/ serve ~/myproj`.
77+
- **At first run** this tool generates a trusted certificate. The sudo password may be required. If you cannot provide the sudo password generate a `localhost.key` and `localhost.crt` and specify its path with `CERT_PATH=/directory/containing/certificates/ serve ~/myproj`.
5978
- **At each run** the password may be required to run the server on port 443 and 80. To avoid the script ask for password specify a different port number: `PORT=4433 serve ~/myproj`.
6079

6180
### EACCES
@@ -72,4 +91,4 @@ And in general all the cases when the script runs but the connection is marked a
7291

7392
Force a reinstall of the certificate with `REINSTALL=true serve`. `sudo` may be required on linux and MacOS.
7493

75-
If the problem is solved you should be able to use https-localhost also as module.
94+
If the problem is solved you should be able to use https-localhost as a module too.

0 commit comments

Comments
 (0)