servexy

servexy

Your files. Now serving.

A tiny, zero-config static file server for previewing builds, testing SPA routes,
and sharing a folder with the devices on your network.

One command. One native binary. Nothing to configure.

Everything a file server should do

Contents

• Requirements
• Install
• Usage
• Recipes
• SPA routing
• Safe by default
• How responses are served
• What servexy is not
• Troubleshooting
• Build from source
• License

Requirements

• macOS, Linux or Windows, on x64 or ARM64.
• For the npm package: Node.js 18 or later, or Bun. The prebuilt binaries need nothing else.

Install

With Bun or npm

bun add --global servexy
# or
npm install --global servexy

Run the same commands again to update. To try it without installing:

bunx servexy ./dist --spa
# or
npx servexy ./dist --spa

The package ships a small launcher plus a native binary for every supported platform. The launcher picks the right one, so there is no download step during install and nothing runs at install time.

Or download the binary

1. Download the file for your system from the latest release:

   System	File
   macOS, Apple silicon	servexy-darwin-arm64
   macOS, Intel	servexy-darwin-amd64
   Linux, x64	servexy-linux-amd64
   Linux, ARM64	servexy-linux-arm64
   Windows, x64	servexy-windows-amd64.exe
   Windows, ARM64	servexy-windows-arm64.exe

2. Rename it to servexy (servexy.exe on Windows) and move it to a folder on your PATH. On macOS and Linux, make it executable too:

   chmod +x servexy
   sudo mv servexy /usr/local/bin/
   

3. On macOS, a binary downloaded with a browser is quarantined. Clear the flag once:

   xattr -d com.apple.quarantine /usr/local/bin/servexy
   

shasum -a 256 --check --ignore-missing SHA256SUMS   # macOS
sha256sum --check --ignore-missing SHA256SUMS       # Linux

Or install with Go

go install github.com/rahatsagor/servexy@latest

This needs Go 1.27 or later. Builds made this way report their version as dev.

Usage

servexy [OPTIONS] [DIRECTORY]

servexy                          # serve the current folder on http://localhost:8080
servexy ./public --port 3000     # another folder and port
servexy ./dist --spa             # a single-page app with client-side routing
servexy ./dist --spa --cache 1h  # also let browsers cache assets for an hour
servexy ./public --network       # reachable from other devices on your network

• Options can come before or after the folder, and values can be written as --port 3000 or --port=3000.
• -- ends the options, which lets you serve a folder whose name starts with a dash: servexy -- -drafts.
• The single-dash forms -port, -dir, -spa and -network from older versions still work.

Press Ctrl+C to stop. Requests that are still running get up to five seconds to finish; press Ctrl+C again to quit at once.

Recipes

Preview a production build

Vue Router's history mode, React Router's createBrowserRouter, and any other router that uses real URLs need --spa so a refresh on a deep link works. Hash routing (/#/settings) works without it.

To pin it to your project, add it as a dev dependency with bun add --dev servexy (or npm install --save-dev servexy) and use it in a script:

{
  "scripts": {
    "build": "vite build",
    "preview": "servexy ./dist --spa"
  }
}

Test on your phone

servexy ./dist --spa --network

Open the network: address servexy prints on any device on the same Wi-Fi. If nothing loads, check that your firewall allows incoming connections for servexy. Everyone on that network can reach the folder while it runs, so only share what you mean to.

Run end-to-end tests against the real build

Point Playwright at your build output, so tests exercise exactly what you ship:

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  webServer: {
    command: 'bunx servexy ./dist --spa --port 4173',
    url: 'http://127.0.0.1:4173',
    reuseExistingServer: !process.env.CI,
  },
  use: { baseURL: 'http://127.0.0.1:4173' },
});

Because missing assets and fetch() calls stay 404, a broken import or API path fails the test instead of hiding behind your index.html.

Cache hashed assets

servexy ./dist --spa --cache 24h

HTML keeps Cache-Control: no-cache, so a new deploy shows up on the next refresh. Everything else gets public, max-age=86400. Use this when your bundler puts a content hash in file names, like assets/index-3f9a1c.js. Without hashes, browsers may keep an old file until the cache runs out.

SPA routing

Most SPA servers send index.html for every path they can't find. That keeps refreshes working, but it also answers a missing app.js or a mistyped API call with 200 OK and a page of HTML, which turns a clear 404 into a confusing parse error. servexy only sends your app to requests that are actually page loads.

With --spa, each request is answered like this:

1. If the path is a file, or a folder with its own index.html, that is served.
2. Otherwise, if the request is a page navigation, the root index.html is served with 200 OK.
3. Anything else gets 404 Not Found.

Safe by default

Pass --dotfiles only when you really want hidden files served.

On Windows, path parts that look like 8.3 short names, such as GIT~1, are treated as hidden too, because NTFS can resolve them to .git or .env. As a result, a file whose name contains ~ followed by a digit isn't served on Windows unless you pass --dotfiles.

How responses are served

What servexy is not

• A dev server. It serves files that already exist. There's no bundling and no hot reload; keep using vite, next dev and friends while you write code, and use servexy to check the build.
• An HTTPS server. It speaks plain HTTP. For HTTPS, put it behind a reverse proxy such as Caddy, or use a tunnel.
• A full web server. There are no request logs, rewrites, headers config or virtual hosts. If you need those, nginx or Caddy are the right tools.

Troubleshooting

netsh interface ipv4 show excludedportrange protocol=tcp

Still stuck? Open an issue with your operating system, the command you ran and what servexy printed.

Build from source

You need Go 1.27.2 or later, Bun 1.4.2 or later, and Node.js 18 or later for the launcher tests.

git clone https://github.com/rahatsagor/servexy.git
cd servexy
go run . ./some-folder --spa   # run from source

Bug reports and ideas are welcome as issues.

License

Free and open source under the MIT License. © 2026 Rahat Sagor.

servexy.rsapplication.com