auxsrv

library0.3.17jsnpmunverified

auxsrv is a lightweight static file server and bundler designed primarily for local development, demo applications, and automated testing environments. It offers both a command-line interface (CLI) and a programmatic API. Currently at version 0.3.17, it's in a pre-1.0 state, meaning API changes may occur more frequently without strict adherence to semantic versioning. Key features include a built-in bundler for TypeScript/JavaScript, CSS, and HTML assets, a SPA (Single Page Application) mode for simplified routing, and integration capabilities for testing frameworks like Playwright. It differentiates itself by providing a minimal setup for serving and bundling, making it suitable for quick prototypes or test suites where a full-fledged build system might be overkill.

web-framework testing devops

npm install auxsrv

github ↗package ↗

INSTALL

IMPORT

SIG · AUXSRV

auxsrv

web-frameworkjavascriptv0.3.17

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

serve

✓ import { serve } from 'auxsrv';

✗ const serve = require('auxsrv');

auxsrv is primarily an ESM package. Use named imports for core functions. CommonJS `require` is not supported for direct module import.

Server

✓ import { type Server } from 'auxsrv';

Import the `Server` type for type-checking the object returned by `serve()`. Use `type` keyword for type-only imports to avoid runtime overhead.

CLI Usage

✓ npx auxsrv <app_dir> [options]

✗ node auxsrv

The CLI is designed to be executed via `npx` or directly from `package.json` scripts. Direct `node` execution of internal files is not the intended or stable interface.

Demonstrates how to programmatically start an auxsrv instance, serving files from a 'playground' directory, with bundling and SPA mode enabled.

import { serve } from 'auxsrv'; import { fileURLToPath } from 'url'; import path from 'path'; const __dirname = path.dirname(fileURLToPath(import.meta.url)); async function startServer() { const server = await serve({ host: 'localhost', port: 3000, // 'path' can be a string relative to cwd, or an absolute path, or import.meta.url path: path.resolve(__dirname, 'playground'), // Assumes 'playground' directory exists next to this script bundle: true, // Automatically bundles 'index.ts' or 'index.tsx' in 'playground' dir spa: true, // Enables SPA mode, routing unmatched paths to '/' watch: true // Rebuilds on source changes (default in CLI, needs explicit in code) }); console.log(`auxsrv running at http://${server.host}:${server.port}`); console.log('Press Ctrl+C to stop the server.'); // Example of stopping after some time, or based on a condition // setTimeout(() => { // console.log('Stopping auxsrv...'); // server.close(); // }, 10000); } startServer().catch(console.error);

auxsrv --version

Debug

Known issues

breakingAs a pre-1.0 package (current version 0.3.17), auxsrv does not strictly adhere to semantic versioning. Minor versions (e.g., 0.x.y to 0.x.z) may introduce breaking API changes. Always review release notes when updating.

fix

Always pin to specific patch versions (e.g., `^0.3.17` instead of `^0.3.0`) or review changelogs thoroughly before updating to a new minor version.

affects: <1.0.0

gotchaThe SPA (Single Page Application) mode is enabled by default for both CLI (`--spa`) and programmatic (`spa: true`) usage. This means all unmatched paths will be routed to the root file (e.g., `index.html`), which might not be desired for traditional static site serving.

fix

To disable SPA mode, use `--spa=off` in the CLI or set `spa: false` in the programmatic `serve` options.

affects: >=0.1.0

gotchaThe bundler is enabled by default, attempting to bundle `index.ts`, `index.tsx`, `src/index.ts`, or `src/index.tsx` into `dist/index.js` relative to the app directory. If these files don't exist or you don't intend to use bundling, it might lead to unexpected behavior or unnecessary processing.

fix

To disable bundling, set `bundle: false` in the programmatic options or omit the `--bundle` flag in the CLI if it's implicitly triggered. You can also specify a custom input/output for bundling.

affects: >=0.1.0

gotchaWhen using `path` option in `serve()` with `import.meta.url` in an ESM module, ensure correct resolution to a directory. `import.meta.url` points to the *file*, so `path.dirname(fileURLToPath(import.meta.url))` is often needed to get the current script's directory.

fix

Use `path: path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'your_app_dir')` to correctly specify the base directory relative to your script. Alternatively, provide a simple string path relative to `process.cwd()`.

affects: >=0.1.0

Errors

Common errors & fixes

Error: listen EADDRINUSE: address already in use :::3000

The specified port (default 3000) is already being used by another process on your system.

fix

Change the port using the `--url <host>:<port>` flag in the CLI (e.g., `--url 3001`) or the `port` option in the programmatic `serve` call (e.g., `{ port: 3001 }`). You can also find and terminate the process currently using the port.

Error: ENOENT: no such file or directory, stat '/path/to/app_dir/index.html'

The `path` option or `<app_dir>` in the CLI points to a directory that does not exist or does not contain expected files (like `index.html`).

fix

Verify that the specified path or app directory exists and contains the files you expect to serve. Ensure the path is correct relative to where you run the command or script.

SyntaxError: Cannot use import statement outside a module

You are trying to use `import` syntax (ESM) in a CommonJS module context (e.g., a `.js` file without `"type": "module"` in `package.json`, or a `.cjs` file).

fix

Ensure your project is configured for ESM by adding `"type": "module"` to your `package.json`, or rename your file to `.mjs`. If using TypeScript, ensure your `tsconfig.json` `module` option is set to `ESNext` or `NodeNext`.

Upgrade

Version history

0.3.17latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/axtk/auxsrv ↗

packagehttps://www.npmjs.com/package/auxsrv ↗