A single, portable Node.js utility to display an environment warning banner (e.g., "DEVELOPMENT", "STAGING") across any Connect/Express-style web framework. One source of truth, one-line usage per app.
This is the official Node.js port of the original env-banner-python utility, providing consistent behavior across your entire technology stack.
This library is designed to be:
- Portable: A single NPM package that works in any Node.js web project.
- Bulletproof: Uses reliable server-side detection and sane defaults. It fails safe by showing a banner if the environment is unknown.
- Thoughtless: Requires only a one-line integration for most major frameworks.
- Framework-Agnostic: Works with Express, Connect, and any other middleware-compatible Node.js framework.
- Maintainable: All banner logic, colors, and rules are in one place.
env-banner-node/
├── lib/
│ ├── core.js # Banner generation and styling logic
│ └── middleware.js # Express/Connect middleware
├── test/ # Test files (not published to npm)
│ ├── express-app.js
│ ├── test-diagonal.html
│ └── README.md
├── LICENSE
├── package.json
└── README.md
Note: The test/ directory is excluded from npm packages via the files field in package.json.
Install the package from NPM (once published) or directly from the Git repository:
npm install git+[https://github.com/sagearbor/env-banner-node.git](https://github.com/sagearbor/env-banner-node.git)The utility provides a standard middleware function.
- Environment Classification: It determines the current environment by checking the
APP_ENVenvironment variable first, then falling back to reliable server-side request details (host, path). It defaults todevif uncertain. - Middleware Injection: The middleware intercepts HTML responses. It buffers the response body, injects the banner HTML just before the closing
</body>tag, updates theContent-Lengthheader, and sends the modified response to the user. Non-HTML responses are ignored.
The banner's behavior is controlled primarily by a single environment variable:
APP_ENV (or ENVBANNER_ENV)
Set this variable in your deployment environment (Docker, Kubernetes, etc.).
prodorproduction: No banner is shown.staging,val,preprod: A yellow banner is shown.dev,test,local: A red banner is shown.- If unset: A red banner is shown by default.
Require the library and add it as middleware to your application.
const express = require('express');
const envBanner = require('env-banner-node'); // or require('./path/to/lib/middleware');
const app = express();
app.use(envBanner()); // <-- Add this line
app.get('/', (req, res) => {
res.send('<html><head></head><body><h1>Hello World!</h1></body></html>');
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});The envBanner() middleware accepts an optional configuration object with the following properties:
| Option | Type | Default | Description |
|---|---|---|---|
text |
string |
Auto-detected (e.g., "DEV", "STAGING") | Custom text to display in the banner |
background |
string |
Auto-detected (red for dev, amber for staging) | Custom background color (hex code) |
color |
string |
Auto-detected (white for dev, dark gray for staging) | Custom text color (hex code) |
position |
string |
'bottom' |
Banner position: 'top', 'bottom', 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'diagonal' (or 'diagonal-bltr'), 'diagonal-tlbr' |
showHost |
boolean |
true |
Whether to display the hostname and port (e.g., " • localhost:3000") |
opacity |
number |
1.0 (bars/ribbons), 0.5 (diagonal) |
Banner opacity from 0.0 (transparent) to 1.0 (fully opaque) |
envVarName |
string |
'APP_ENV' |
Primary environment variable name to check |
app.use(envBanner({
text: "DON'T USE REAL DATA",
showHost: false
}));
// Result: "DON'T USE REAL DATA" (no hostname/port shown)app.use(envBanner({
text: "QA Environment - Test Data Only",
background: "#9333ea", // purple
color: "#ffffff", // white
position: "bottom"
}));
// Result: "QA Environment - Test Data Only • localhost:3000" at bottomCorner positions display the banner as a diagonal ribbon in the specified corner:
// Top-right corner ribbon (default ribbon style)
app.use(envBanner({
position: 'top-right',
text: "STAGING"
}));
// Top-left corner ribbon
app.use(envBanner({
position: 'top-left'
}));
// Bottom-right corner ribbon
app.use(envBanner({
position: 'bottom-right'
}));
// Bottom-left corner ribbon
app.use(envBanner({
position: 'bottom-left'
}));Full-width bar positions span the entire width of the page:
// Bottom bar (default)
app.use(envBanner());
// or explicitly:
app.use(envBanner({
position: 'bottom'
}));
// Top bar
app.use(envBanner({
position: 'top'
}));The diagonal position creates a thin diagonal stripe across the viewport, perfect for highly visible warnings without blocking content. The banner is click-through enabled (pointer-events: none).
Two diagonal directions are available:
// Default diagonal: bottom-left to top-right (/)
app.use(envBanner({
position: 'diagonal',
text: "DON'T USE REAL DATA"
}));
// or explicitly:
app.use(envBanner({
position: 'diagonal-bltr', // BLTR = Bottom-Left To Right
text: "DON'T USE REAL DATA"
}));
// Alternative direction: top-left to bottom-right (\)
app.use(envBanner({
position: 'diagonal-tlbr', // TLBR = Top-Left To Bottom-Right
text: "STAGING ENVIRONMENT"
}));
// Custom opacity diagonal
app.use(envBanner({
position: 'diagonal',
opacity: 0.3, // 30% opaque (very subtle)
text: "DEVELOPMENT ENVIRONMENT"
}));
// More visible diagonal
app.use(envBanner({
position: 'diagonal',
opacity: 0.7, // 70% opaque
background: '#ef4444',
color: '#ffffff',
text: "STAGING - TEST DATA ONLY",
showHost: false
}));Diagonal Positions:
'diagonal'or'diagonal-bltr': Bottom-left to top-right (/) - default diagonal direction'diagonal-tlbr': Top-left to bottom-right ()
The opacity option works with all position styles:
// Semi-transparent top bar
app.use(envBanner({
position: 'top',
opacity: 0.8,
text: "DEV ENVIRONMENT"
}));
// Semi-transparent corner ribbon
app.use(envBanner({
position: 'top-right',
opacity: 0.6,
text: "STAGING"
}));