Registry / web-framework / egg-static

egg-static

JSON →
library2.3.1jsnpmunverified

`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.

web-framework
npm install egg-static
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · EGG-STATIC
E
egg-static
web-frameworkjavascriptv2.3.1
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.

Static Plugin Enablement
✓ // {app_root}/config/plugin.js exports.static = { enable: true, package: 'egg-static', };
✗ import 'egg-static';
Egg.js plugins are enabled and managed via the `config/plugin.js` file, not through direct ES module `import` statements in application code.
Static Configuration
✓ // {app_root}/config/config.default.js module.exports = appInfo => { const config = {}; config.static = { prefix: '/public/', dir: path.join(appInfo.baseDir, 'app/public'), maxAge: appInfo.env === 'prod' ? 31536000 : 0, }; return config; };
✗ exports.static = 'some/path';
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.
Multiple Static Directories
✓ // {app_root}/config/config.default.js exports.static = { dir: [ path.join(appInfo.baseDir, 'app/public'), { prefix: '/assets', dir: path.join(appInfo.baseDir, 'client/dist') } ], };
✗ exports.static = { dir: '/path1,/path2' };
To serve static files from multiple directories, the `dir` option should be an array of paths or objects, not a comma-separated string.

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.

const egg = require('egg'); const path = require('path'); const fs = require('fs'); // Create a minimal Egg.js application structure for demonstration const baseDir = path.join(__dirname, 'egg-app'); const configDir = path.join(baseDir, 'config'); const appPublicDir = path.join(baseDir, 'app/public'); fs.mkdirSync(configDir, { recursive: true }); fs.mkdirSync(appPublicDir, { recursive: true }); fs.writeFileSync(path.join(baseDir, 'app.js'), ` const egg = require('egg'); module.exports = egg; `); fs.writeFileSync(path.join(configDir, 'plugin.js'), ` 'use strict'; exports.static = { enable: true, package: 'egg-static', }; `); fs.writeFileSync(path.join(configDir, 'config.default.js'), ` 'use strict'; const path = require('path'); module.exports = appInfo => { const config = {}; config.keys = 'my_secret_key'; // Required for Egg.js config.static = { prefix: '/public/', dir: path.join(appInfo.baseDir, 'app/public'), dynamic: true, preload: false, maxAge: appInfo.env === 'prod' ? 31536000 : 0, buffer: appInfo.env === 'prod' ? true : false, maxFiles: 1000, }; return config; }; `); fs.writeFileSync(path.join(appPublicDir, 'hello.txt'), 'Hello from egg-static!'); console.log('Created minimal Egg.js app structure.'); console.log('To run, navigate to ' + baseDir + ' and run `npm init egg --type=simple` then `npm start`'); console.log('Then visit http://127.0.0.1:7001/public/hello.txt in your browser.'); // In a real app, you would just have these files in your Egg.js project. // To simplify, this example creates the necessary files. // const app = egg.startCluster({ // baseDir: baseDir, // // port: 7001, // Default port // }); // app.ready(() => { // console.log('Egg application is ready on http://127.0.0.1:7001'); // console.log('Try visiting http://127.0.0.1:7001/public/hello.txt'); // });
Debug
Known issues
breakingVersion `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.
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`.
affects: >=3.0.0
gotchaIn 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.
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.
affects: >=1.0.0
gotchaThe 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.
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.
affects: >=1.0.0
gotchaThe `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.
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`).
affects: >=1.0.0
Errors
Common errors & fixes
Error: The Node.js version is too low. Required Node.js >= 18.19.0
Attempting to use `egg-static` version `3.0.0` or higher with a Node.js runtime earlier than 18.19.0.
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.
GET /public/my-file.js 404 Not Found
The requested static file either does not exist at the configured `dir` path or the URL `prefix` does not match the configuration.
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.
Changes to static files (e.g., images, CSS) are not reflecting on the deployed application.
In production mode, `egg-static` caches assets heavily (default `maxAge` is one year). The server serves cached versions until restarted.
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.
Upgrade
Version history
2.3.1latest on npm
Audit
Dependencies
eggrequiredThis package is an Egg.js plugin and requires an Egg.js application to function.
Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/eggjs/egg-static ↗
packagehttps://www.npmjs.com/package/egg-static ↗
homepagehttps://eggjs.org ↗
egg-static — npm install egg-static · libregistry