0.0.15 • Public • Published

X Server

A website server that supports serving many websites using subdomain-based routing.


Install it by the following command:

npm install -g @xieyuheng/x-server

The command line program is called x-server.

  help [name]             Display help for a command
  serve:website [path]    Serve a website
  serve:subdomain [path]  Serve many websites using subdomain-based routing


Serve one website

Use the x-server serve:website command to serve one website:

x-server serve:website <directory>

When serving a single-page application (SPA), we need to redirect all requests to index.html.

Example command for serving a SPA:

x-server serve:website <directory> \
  --cors \
  --redirect-not-found-to index.html \
  --cache-control-pattern 'assets/**: max-age=31536000'

To serve a website using HTTPS, we need to provide TLS certificate.

Example command for serving a SPA using HTTPS:

x-server serve:website <directory> \
  --cors \
  --port 443 \
  --redirect-not-found-to index.html \
  --cache-control-pattern 'assets/**: max-age=31536000' \
  --tls-cert <certificate-file> \
  --tls-key <private-key-file>

It is unhandy to issue long command, thus we also support using a website.json config file:

x-server serve:website <directory>/website.json

Where <directory>/website.json is:

  "server": {
    "port": 443,
    "tls": {
      "cert": "<certificate-file>",
      "key": "<private-key-file>"
  "cors": true,
  "redirectNotFoundTo": "index.html",
  "cacheControlPatterns": {
    "assets/**": "max-age=31536000"

Serve many websites

The main use case of x-server is to serve many websites in one directory, using subdomain-based routing.

For example, I have a VPS machine, where I put all my websites in the /websites directory.


I bought a domain for my server -- say fidb.app, and configured my DNS to resolve fidb.app and *.fidb.app to my server.

I also created certificate files for my domain using certbot.

I can use x-server serve:subdomain command to serve all of the websites in /websites directory.

x-server serve:subdomain /websites \
  --hostname fidb.app \
  --port 443 \
  --tls-cert /etc/letsencrypt/live/fidb.app/fullchain.pem \
  --tls-key /etc/letsencrypt/live/fidb.app/privkey.pem

Then I can visit all my websites via subdomain of fidb.app.


If no subdomain is given in a request, www/ will be used as the default subdomain directory (while no redirect will be done).

Thus the following websites have the same contents:


Instead of issuing long command, we can also use a root website.json config file.

x-server serve:subdomain /websites/website.json

Where /websites/website.json is:

  "server": {
    "hostname": "fidb.app",
    "port": 443,
    "tls": {
      "cert": "/etc/letsencrypt/live/fidb.app/fullchain.pem",
      "key": "/etc/letsencrypt/live/fidb.app/privkey.pem"
  • When using x-server serve:subdomain, the server.hostname option is required.

  • And each website in /websites might have it's own website.json config file.

Config logger

We can config logger in /websites/website.json:

  "logger": {
    "name": "pretty-line",
    "disableRequestLogging": true

The type of logger options are:

export type LoggerOptions = {
  name: "json" | "silent" | "pretty" | "pretty-line"
  disableRequestLogging?: boolean

The default logger options are:

  "name": "pretty-line",
  "disableRequestLogging": false

Use custom domain

When doing subdomain-based routing, we can also support custom domain for a subdomain, by adding a file in .domain-map/ directory.


Where the content of the file is the subdomain, for examples:

/websites/.domain-map/readonly.link/subdomain -- (content: readonlylink)
/websites/.domain-map/inet.run/subdomain -- (content: inet)

Then I can the following DNS ALIAS records to my custom domains:

  • You can also use A record and IP addresses.
Domain Type Value
readonly.link ALIAS readonlylink.fidb.app.
inet.run ALIAS inet.fidb.app.

Custom domain is only supported when TLS is enabled. To provide TLS certificate for a custom domain, add the following files:


For example, the listing of .domain-map/ is the following:


Get free certificate

You can use certbot to get free certificate for your domains.

After install certbot, I prefer creating certificate via DNS TXT record, using the following command:

sudo certbot certonly --manual --preferred-challenges dns

Then you can follow the prompt of certbot to create the certificate files, during which you will need to add TXT record to the DNS record of your domain to accomplish the challenge given by certbot.

After created the certificate files, I use the follow command to copy them to my .domain-map:

sudo cat /etc/letsencrypt/live/<custom-domain>/fullchain.pem > /websites/.domain-map/<custom-domain>/cert
sudo cat /etc/letsencrypt/live/<custom-domain>/privkey.pem > /websites/.domain-map/<custom-domain>/key

Use systemd to start service

On a Linux server, we can use systemd to start a service, or enable a service to start whenever the server is booted.

Example service file fidb-app-x-server.service:

Description=fidb.app x-server

ExecStart=/usr/local/bin/x-server serve:subdomain /websites/website.json


Install service:

sudo cp <name>.service /etc/systemd/system/

Using service:

sudo systemctl start <name>.service
sudo systemctl enable <name>.service
sudo systemctl status <name>.service

To view log:

journalctl -f -u <name>.service

Reload systemd config files:

sudo systemctl daemon-reload


npm install           # Install dependencies
npm run build         # Compile `src/` to `lib/`
npm run build:watch   # Watch the compilation
npm run format        # Format the code
npm run test          # Run test
npm run test:watch    # Watch the testing


To make a contribution, fork this project and create a pull request.

Please read the STYLE-GUIDE.md before you change the code.

Remember to add yourself to AUTHORS. Your line belongs to you, you can write a little introduction to yourself but not too long.






Package Sidebar


npm i @xieyuheng/x-server

Weekly Downloads






Unpacked Size

244 kB

Total Files


Last publish


  • xieyuheng