{"id":12851,"library":"auxsrv","title":"auxsrv: Static File Server & Bundler","description":"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.","status":"active","version":"0.3.17","language":"javascript","source_language":"en","source_url":"https://github.com/axtk/auxsrv","tags":["javascript","node","server","static server","bundler","typescript"],"install":[{"cmd":"npm install auxsrv","lang":"bash","label":"npm"},{"cmd":"yarn add auxsrv","lang":"bash","label":"yarn"},{"cmd":"pnpm add auxsrv","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"auxsrv is primarily an ESM package. Use named imports for core functions. CommonJS `require` is not supported for direct module import.","wrong":"const serve = require('auxsrv');","symbol":"serve","correct":"import { serve } from 'auxsrv';"},{"note":"Import the `Server` type for type-checking the object returned by `serve()`. Use `type` keyword for type-only imports to avoid runtime overhead.","symbol":"Server","correct":"import { type Server } from 'auxsrv';"},{"note":"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.","wrong":"node auxsrv","symbol":"CLI Usage","correct":"npx auxsrv <app_dir> [options]"}],"quickstart":{"code":"import { serve } from 'auxsrv';\nimport { fileURLToPath } from 'url';\nimport path from 'path';\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\nasync function startServer() {\n  const server = await serve({\n    host: 'localhost',\n    port: 3000,\n    // 'path' can be a string relative to cwd, or an absolute path, or import.meta.url\n    path: path.resolve(__dirname, 'playground'), // Assumes 'playground' directory exists next to this script\n    bundle: true, // Automatically bundles 'index.ts' or 'index.tsx' in 'playground' dir\n    spa: true,    // Enables SPA mode, routing unmatched paths to '/'\n    watch: true   // Rebuilds on source changes (default in CLI, needs explicit in code)\n  });\n\n  console.log(`auxsrv running at http://${server.host}:${server.port}`);\n  console.log('Press Ctrl+C to stop the server.');\n\n  // Example of stopping after some time, or based on a condition\n  // setTimeout(() => {\n  //   console.log('Stopping auxsrv...');\n  //   server.close();\n  // }, 10000);\n}\n\nstartServer().catch(console.error);","lang":"typescript","description":"Demonstrates how to programmatically start an auxsrv instance, serving files from a 'playground' directory, with bundling and SPA mode enabled."},"warnings":[{"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.","message":"As 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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"To disable SPA mode, use `--spa=off` in the CLI or set `spa: false` in the programmatic `serve` options.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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()`.","message":"When 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The specified port (default 3000) is already being used by another process on your system.","error":"Error: listen EADDRINUSE: address already in use :::3000"},{"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.","cause":"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`).","error":"Error: ENOENT: no such file or directory, stat '/path/to/app_dir/index.html'"},{"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`.","cause":"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).","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null}