Introducing @small-tech/https, a batteries-included drop-in replacement for the Node.js https module

08 Nov 2019

Screenshot of @small-tech/https example app running in terminal with globally-trusted Let’s Encrypt certificates — @small-tech/https with globally-trusted Let’s Encrypt certificates

Today’s my birthday so I thought I’d give you a little present: @small-tech/https.

Plug-and-play https

This is essentially a drop-in, batteries-included version of the Node.js https module that:

Automatically provisions locally-trusted TLS certificates for localhost for development use (courtesy of mkcert seamlessly integrated via Nodecert).
Automatically provisions globally-trusted TLS certificates for your domain(s) for cross-browser testing, staging, and production courtesy of Let’s Encrypt.

Install

npm i @small-tech/https

Example

Here’s a basic HTTPS server that responds to every GET request with a simple “hello, world” page.

Set up

# Create the project folder and switch to it.
mkdir example && cd example

# Create a new npm module for the example.
npm init --yes

# Install dependencies.
npm i @small-tech/https

# Open up the main file in your default editor.
$EDITOR index.js

Code (index.js)

const https = require('@small-tech/https')

// Helpers
function html(message) {
  return `<!doctype html><html lang='en'><head><meta charset='utf-8'/><title>Hello, world!</title><style>body{background-color: white; font-family: sans-serif;}</style></head><body><h1>${message}</h1></body></html>`
}
const headers = {'Content-Type': 'text/html'}

let options = {}

// For globally-trusted Let’s Encrypt certificates uncomment options.
// To provision certificates, also remove “staging: true” property.

// options = {
//   domain: 'hostname',
//   staging: true
// }

// Default (no options): create HTTPS server at https://localhost
// with locally-trusted certificates.
const server = https.createServer(options, (request, response) => {
  // Respond to all routes with the same page.
  response.writeHead(200, headers)
  response.end(html('Hello, world!'))
})

server.listen(443, () => {
  console.log(' 🎉 Server running on port 443.')
})

Run
```
node index
```

Hit https://localhost and you should see your site served with locally-trusted TLS certificates.

Screenshot of @small-tech/https example app running in terminal with locally-trusted TLS certificates — @small-tech/https with locally-trusted certificates courtesy of mkcert

Let’s encrypt!

To provision globally-trusted Let’s Encrypt certificates instead, just uncomment the options object. Test it out with the staging flag set to true first and, once you verify that certificates are being properly generated, remove the flag to actually provision the certificates the first time your server is hit.

TL; DT

Too long, didn’t type?

You can find a version of this example in the /example folder. To download and run it:

# Clone this repository.
git clone https://source.ind.ie/site.js/lib/https.git

# Switch to the directory.
cd https

# Install dependencies.
npm i

# Run the example.
npm run example

Happy birthday to you!

I hope you enjoy my little birthday present and I hope that it makes your life easier.

Please let me know how you get on it with.

PS. I also got some lovely presents today ;)

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.