A lightweight, zero-dependency static file server built with Node.js. Perfect for serving static websites locally during development or for GitHub Pages preview.

npm install -g gh-serve

Or use directly with npx:

npx gh-serve

Serve files from the current directory:

gh-serve

Serve files from a specific directory:

gh-serve ./public

Simulate GitHub Pages subpath deployment (e.g., username.github.io/repo-name):

gh-serve ./dist --base /my-repo

or using the short flag:

gh-serve ./dist -b /my-repo

Your site will be available at http://localhost:3000/my-repo

Use the PORT environment variable:

PORT=8080 gh-serve

• Directory path: First positional argument (default: ./demos)
• --base, -b <path>: Set a base URL path for serving files

# Serve current directory on port 3000
gh-serve .

# Serve dist folder with base URL
gh-serve ./dist --base /my-project

# Serve on custom port
PORT=8080 gh-serve ./public

# Preview GitHub Pages locally
gh-serve ./docs -b /repository-name

• Node.js 16 or higher
• pnpm (recommended) or npm

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build
pnpm build

gh-serve/
├── src/
│   └── serve.ts      # Main server implementation
├── dist/             # Built output (after running pnpm build)
├── package.json
└── tsconfig.json

Contributions are welcome! Please follow the commit conventions when submitting changes.

MIT