{"id":13108,"library":"egg-static","title":"Egg.js Static File Server Plugin","description":"`egg-static` is a core plugin for the Egg.js Node.js framework, providing robust static file serving capabilities. It is built upon `koa-static-cache`, inheriting its efficient caching and serving mechanisms. The plugin is usually enabled by default in Egg.js applications, simplifying the process of making static assets available. Currently, the `2.x` series is stable, with `v2.3.1` released in February 2023. A significant `v3.0.0` release in January 2025 introduced breaking changes, primarily dropping support for older Node.js versions (below 18.19.0). Its release cadence is generally tied to the Egg.js framework's development. Key differentiators include its seamless integration with the Egg.js ecosystem, intelligent default caching behaviors optimized for both development and production environments, and flexible configuration for handling multiple static directories with custom URL prefixes.","status":"active","version":"2.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/eggjs/egg-static","tags":["javascript","egg","egg-plugin","eggPlugin","static"],"install":[{"cmd":"npm install egg-static","lang":"bash","label":"npm"},{"cmd":"yarn add egg-static","lang":"bash","label":"yarn"},{"cmd":"pnpm add egg-static","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is an Egg.js plugin and requires an Egg.js application to function.","package":"egg","optional":false}],"imports":[{"note":"Egg.js plugins are enabled and managed via the `config/plugin.js` file, not through direct ES module `import` statements in application code.","wrong":"import 'egg-static';","symbol":"Static Plugin Enablement","correct":"// {app_root}/config/plugin.js\nexports.static = {\n  enable: true,\n  package: 'egg-static',\n};"},{"note":"Configuration for the static plugin is set within the `config.static` property in your Egg.js configuration files (e.g., `config/config.default.js`). The value must be an object.","wrong":"exports.static = 'some/path';","symbol":"Static Configuration","correct":"// {app_root}/config/config.default.js\nmodule.exports = appInfo => {\n  const config = {};\n  config.static = {\n    prefix: '/public/',\n    dir: path.join(appInfo.baseDir, 'app/public'),\n    maxAge: appInfo.env === 'prod' ? 31536000 : 0,\n  };\n  return config;\n};"},{"note":"To serve static files from multiple directories, the `dir` option should be an array of paths or objects, not a comma-separated string.","wrong":"exports.static = { dir: '/path1,/path2' };","symbol":"Multiple Static Directories","correct":"// {app_root}/config/config.default.js\nexports.static = {\n  dir: [\n    path.join(appInfo.baseDir, 'app/public'),\n    { prefix: '/assets', dir: path.join(appInfo.baseDir, 'client/dist') }\n  ],\n};"}],"quickstart":{"code":"const egg = require('egg');\nconst path = require('path');\nconst fs = require('fs');\n\n// Create a minimal Egg.js application structure for demonstration\nconst baseDir = path.join(__dirname, 'egg-app');\nconst configDir = path.join(baseDir, 'config');\nconst appPublicDir = path.join(baseDir, 'app/public');\n\nfs.mkdirSync(configDir, { recursive: true });\nfs.mkdirSync(appPublicDir, { recursive: true });\n\nfs.writeFileSync(path.join(baseDir, 'app.js'), `\nconst egg = require('egg');\nmodule.exports = egg;\n`);\n\nfs.writeFileSync(path.join(configDir, 'plugin.js'), `\n'use strict';\nexports.static = {\n  enable: true,\n  package: 'egg-static',\n};\n`);\n\nfs.writeFileSync(path.join(configDir, 'config.default.js'), `\n'use strict';\nconst path = require('path');\nmodule.exports = appInfo => {\n  const config = {};\n\n  config.keys = 'my_secret_key'; // Required for Egg.js\n\n  config.static = {\n    prefix: '/public/',\n    dir: path.join(appInfo.baseDir, 'app/public'),\n    dynamic: true,\n    preload: false,\n    maxAge: appInfo.env === 'prod' ? 31536000 : 0,\n    buffer: appInfo.env === 'prod' ? true : false,\n    maxFiles: 1000,\n  };\n  return config;\n};\n`);\n\nfs.writeFileSync(path.join(appPublicDir, 'hello.txt'), 'Hello from egg-static!');\n\nconsole.log('Created minimal Egg.js app structure.');\nconsole.log('To run, navigate to ' + baseDir + ' and run `npm init egg --type=simple` then `npm start`');\nconsole.log('Then visit http://127.0.0.1:7001/public/hello.txt in your browser.');\n\n// In a real app, you would just have these files in your Egg.js project.\n// To simplify, this example creates the necessary files.\n// const app = egg.startCluster({\n//   baseDir: baseDir,\n// //  port: 7001, // Default port\n// });\n\n// app.ready(() => {\n//   console.log('Egg application is ready on http://127.0.0.1:7001');\n//   console.log('Try visiting http://127.0.0.1:7001/public/hello.txt');\n// });\n","lang":"javascript","description":"This code demonstrates how to enable and configure `egg-static` in a minimal Egg.js application. It sets up a `/public/` prefix serving files from `app/public`, with different caching strategies for development and production."},"warnings":[{"fix":"Ensure your Node.js environment is at version `18.19.0` or higher before upgrading to `egg-static@3.0.0`. If you cannot upgrade Node.js, remain on `egg-static@2.x`.","message":"Version `3.0.0` of `egg-static` dropped support for Node.js versions older than `18.19.0`. Applications running on earlier Node.js versions will encounter errors or fail to start when upgrading to `egg-static@3.0.0` or higher.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"To see changes to static files in production, you must restart your Egg.js application. During development, `maxAge` is typically set to `0` (no cache) to allow immediate changes.","message":"In production environments, `egg-static` aggressively caches assets after they are first visited. This means that changes to static files will not be reflected until the Egg.js process is restarted.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always verify that the `prefix` in `config.static` matches the URL path you are requesting and that the `dir` correctly points to the actual location of your static files on the filesystem. Use an array for `dir` if serving from multiple locations or with different prefixes.","message":"The default prefix for static files is `/public/` and the default serving directory is `path.join(appInfo.baseDir, 'app/public')`. Misconfiguration of these paths or prefixes is a common reason for static assets not being served.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be mindful of the `maxAge` setting. If you need consistent caching behavior across environments or require different caching in production, explicitly set `config.static.maxAge` in `config/config.default.js` or environment-specific configuration files (e.g., `config/config.prod.js`).","message":"The `maxAge` configuration option defaults to `31536000` (one year) in production and `0` (no cache) in non-production environments. Developers often forget this distinction, leading to unexpected caching behavior in different environments.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js installation to version `18.19.0` or newer. Alternatively, downgrade `egg-static` to a `2.x` version (e.g., `npm install egg-static@2`) if a Node.js upgrade is not feasible.","cause":"Attempting to use `egg-static` version `3.0.0` or higher with a Node.js runtime earlier than 18.19.0.","error":"Error: The Node.js version is too low. Required Node.js >= 18.19.0"},{"fix":"Double-check the `config.static.dir` to ensure it points to the correct filesystem path where `my-file.js` resides. Also, confirm that `config.static.prefix` matches the `/public/` part of the URL. Ensure the file actually exists in the specified directory.","cause":"The requested static file either does not exist at the configured `dir` path or the URL `prefix` does not match the configuration.","error":"GET /public/my-file.js 404 Not Found"},{"fix":"After deploying new static assets to a production Egg.js application, ensure you restart the Node.js process (e.g., `npm stop` then `npm start` or via your PM2/Kubernetes deployment strategy) to clear the in-memory cache and serve the updated files.","cause":"In production mode, `egg-static` caches assets heavily (default `maxAge` is one year). The server serves cached versions until restarted.","error":"Changes to static files (e.g., images, CSS) are not reflecting on the deployed application."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}