TypeScript icon, indicating that this package has built-in type declarations

1.0.3 • Public • Published


A very simple http static file server

Build & Install

Install via npm

npm i -D @ncap0cpl/goserve

Build yourself

Clone the repo

git clone https://github.com/ncpa0cpl/goserve

Build the binary

go build -o ./goserve

Install the program in your PATH Copy the binary to a bin directory (assuming ~/.local/bin is in your PATH)

cp ./goserve ~/.local/bin


Usage: goserve [options] [directory]

  --help              Print this help message.
  --loglevel <level>  The log level. Default: info
  --port <port>       The port to serve on. Default: 8080
  --redirect <url>    Redirect all unmatched routes to a specified url.
  --spa <filepath>    Specify a file to send for all unmatched routes.
  --chunk-size <KB>   The size of chunks when streaming. Default: 2048KB
  --no-streaming      Disables the server ability to process Range requests and sending partial content.
  --compress          Compress responses using the GZip algorithm.

Hot Module Reload
  --aw           Alias for '--watch --auto-reload'
  --watch        When enabled, server will send fs events when files are changed. To listen to these add event listeners to `window.HMR` on client side.
  --auto-reload  Automatically inject a script to html files that will reload the page on a 'watch' change event.

Cache Headers Options
  --maxage <seconds>   The max-age value to set in the Cache-Control header.
  --nocache            Require browsers to re-validate etag on each resource load.
  --noetag             Disable ETag generation.

Server Cache
  --cache:max <MB>     Maximum size of all files in the cache. Default: 100MB
  --cache:flimit <MB>  Maximum size of single file that can be put in cache. Default: 10MB

To serve files from the public directory of the current directory on port 8000:

goserve --port 8000 ./public

Node API

Goserve can also be imported in a Node script and spawned using a provided function.

import { serve } from '@ncap0cpl/goserve';

const childProcess = serve("path/to/directory", {
  port: 3000



When auto-reload is enabled, either via --auto-reload or --aw flag, a script tag will be injected to every ".html" file that will reload the page every time that file is changed. Note that the --auto-reload flag must be used alongside the --watch flag.

Watch mode

When watch mode is enabled, either via --watch or --aw flag, to every ".html" file a script tag will be injected enabling listening to file changes within the hosted directory.

Listening to these changes can be done by adding event listeners to window.HMR object:

HMR.onChange((event) => {
  console.log(`file ${event.file} has changed`);

HMR.onCreate((event) => {
  console.log(`file ${event.file} has been created`);

HMR.onDelete((event) => {
  console.log(`file ${event.file} has been deleted`);

HMR.onRename((event) => {
  console.log(`file ${event.oldFile} has been renamed to ${event.file}`);

HMR.onCurrentPageChange((event) => {
  console.log(`current page's file has changed`);

Package Sidebar


npm i @ncpa0cpl/goserve

Weekly Downloads






Unpacked Size

8.67 MB

Total Files


Last publish


  • ncpa0cpl