{"id":27896,"library":"koa-static-server","title":"koa-static-server","description":"Static file serving middleware for Koa with support for directory listing, URL rewriting, and custom index files. Current stable version is 1.5.2. This package provides a simple API for serving static assets in Koa applications, similar to koa-static but with built-in options for rootPath rewriting, notFoundFile fallback, gzip support, and index file customization. It is designed for Koa v1 and may not be compatible with Koa v2 without additional conversion middleware.","status":"maintenance","version":"1.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/pkoretic/koa-static-server","tags":["javascript","koa","middleware","file","static","sendfile","directory","server","folder"],"install":[{"cmd":"npm install koa-static-server","lang":"bash","label":"npm"},{"cmd":"yarn add koa-static-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-static-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; used as middleware in Koa applications","package":"koa","optional":false}],"imports":[{"note":"This package uses CommonJS exports; ESM import with named export is not supported.","wrong":"import { serve } from 'koa-static-server'","symbol":"serve","correct":"const serve = require('koa-static-server')"},{"note":"When using ESM, use default import; the module does not export .default.","wrong":"const serve = require('koa-static-server').default","symbol":"default","correct":"import serve from 'koa-static-server'"},{"note":"serve must be called with an options object to create middleware.","wrong":"app.use(serve) // missing options","symbol":"serve (as middleware)","correct":"app.use(serve({ rootDir: 'public' }))"}],"quickstart":{"code":"const Koa = require('koa');\nconst serve = require('koa-static-server');\nconst app = new Koa();\napp.use(serve({\n  rootDir: 'public',\n  rootPath: '/static',\n  index: 'index.html',\n  maxage: 3600000,\n  gzip: true,\n  hidden: false\n}));\napp.listen(3000, () => {\n  console.log('Server running on port 3000');\n});","lang":"javascript","description":"Sets up a Koa static server serving files from 'public' under '/static' with index file support, caching, and gzip."},"warnings":[{"fix":"If using Koa v2, use 'koa-convert' to wrap the middleware: app.use(convert(serve({...})))","message":"This package is designed for Koa v1. Using it with Koa v2 requires a converter like 'koa-convert' or 'koa-v1-middleware'. Direct use may cause errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set rootPath to the URL prefix you want, not the filesystem path.","message":"The 'rootPath' option rewrites the URL path. For example, serving rootDir 'web' with rootPath '/admin' means URLs under '/admin' map to files in 'web', not '/admin/web'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set 'notFoundFile' option to a fallback file, or ensure an index file exists in rootDir.","message":"If no 'index' file is found at the root, the middleware does not send a default response and may call through to downstream middleware. This can cause 404s if not handled.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Migrate to 'koa-static' (v5+) for Koa v2 support and active maintenance.","message":"The package has not been updated since 2016 and may have unpatched vulnerabilities. Use 'koa-static' or 'koa-send' instead for modern Koa applications.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use default import: import serve from 'koa-static-server'","cause":"Import error: using ESM named import instead of default import or require.","error":"TypeError: serve is not a function"},{"fix":"Install koa: npm install koa","cause":"Missing peer dependency 'koa'. This module requires 'koa' to be installed.","error":"Error: Cannot find module 'koa'"},{"fix":"Use app.use(serve({ rootDir: 'public' }))","cause":"Passing serve instead of serve() with options. serve is a factory function, not middleware.","error":"TypeError: app.use() requires a middleware function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}