Configuring 11ty With Portless

This is to log my process and problems while configuring 11ty dev server with portless.

This assumes that you have installed portless globally on your system using one of these commands:

npm i -g portless

# OR

pnpm i -g portless

# OR

bun i -g portless

# You get the idea.

This also assumes that you are past this problem:

> PORTLESS_HTTPS=1 portless designr-ty pnpm dev


portless

-- designr-ty.localhost (auto-resolves to 127.0.0.1)
Starting proxy...
Ensuring TLS certificates...
Adding CA to system trust store...
Could not add CA to system trust store.
Command failed: update-ca-certificates
/usr/sbin/update-ca-certificates: 101: cannot create /etc/ssl/certs/ca-certificates.crt.new: Permission denied  ←

Browsers will show certificate warnings. ←
To fix this later, run:
  portless trust
HTTPS/2 proxy started on port 1355
Proxy started in background
-- Using port 4547

  -> https://designr-ty.localhost:1355

Running: PORT=4547 HOST=127.0.0.1 PORTLESS_URL=https://designr-ty.localhost:1355 pnpm dev

Relevant: image

If you’re struggling with the above thing, well, one thing to note:

portless is a node script and running it with sudo won’t exactly work as you’d otherwise expect it to for a binary executable. (autor note: this section can have more useful info.)

A QUICK ASIDE — https with dev server

Now, eleventy does have an amazing dev server with many configuration options of its own. It supports https on local dev through a config option too.

To use the 11ty dev-server’s https setup, add the following to your 11ty config:

export default function(eleventyConfig) {
  // ... some your cool config

  eleventyConfig.setServerOptions({
    https: {
			key: "./path/to/localhost.key",
			cert: "./path/to/localhost.cert",
		},
  })

  // more of your cool config
  return {
    // something you return at the end
  }
}

You can create the localhost.key and localhost.cert using mkcert and store it in a .gitignore’d location like ./.certs/

Back to portless

OK, with that out of the way, suppose you don’t want to manage creating and storing those SSL certs in your local project dir (or worry about accidentally commiting those to your repo), portless does offer a clean alternative.

It does a lot behind the scenes, and it’s pretty neat.

Here’s how to prepare 11ty for working well with portless as it does not, by default, respect the following env variables:

• PORT
• HOST

But you can ask 11ty to respect those, and that’s all portless needs to work with 11ty. In your eleventy.config.mjs or the name you chose for your config file:

    eleventyConfig.setServerOptions({
      port: process.env.PORT || 8080,
      hostname: process.env.HOST || "localhost",
    });

• Don’t forget to add import "dotenv/config" at the top of this config file (EJS). Use appropriate require() alternative format if you use CJS syntax. Without the above dotenv import, process.env.* won’t work.

• Don’t forget to install dotenv if you haven’t already.

This gives me the 11ty site on https://designr-ty.localhost:1355