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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
flash
✓ import flash from 'connect-flash';
✗ const flash = require('connect-flash');
While originally designed for CommonJS (`require`), some users attempt ES Modules (`import`). The package itself does not officially support ESM, and direct `import` may lead to issues or require specific `type: module` configurations and transpilation. For most setups, stick to CommonJS.
req.flash()
✓ req.flash('success', 'Operation successful!');
const messages = req.flash('info');
The `flash` middleware adds the `flash()` method to the `req` object. It can be called with two arguments (key, value) to set a message, or with one argument (key) to retrieve and clear messages of that type. Calling with no arguments retrieves all messages.
This quickstart demonstrates setting up connect-flash with modern Express (4.x+), including `cookie-parser` and `express-session`, and then setting and retrieving flash messages which are made available to EJS templates via `res.locals`.
import express from 'express';
import session from 'express-session';
import cookieParser from 'cookie-parser';
import flash from 'connect-flash';
import path from 'path';
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const app = express();
const PORT = process.env.PORT || 3000;
// Session setup must come BEFORE connect-flash
app.use(cookieParser('keyboard cat')); // Use a strong secret in production
app.use(session({
secret: 'another secret string',
resave: false,
saveUninitialized: true,
cookie: { maxAge: 60000 * 10 } // 10 minutes
}));
// Initialize connect-flash
app.use(flash());
// Make flash messages available in res.locals for templates
app.use((req, res, next) => {
res.locals.success_msg = req.flash('success');
res.locals.error_msg = req.flash('error');
res.locals.info_msg = req.flash('info');
next();
});
app.set('views', path.join(__dirname, 'views'));
app.set('view engine', 'ejs'); // Example with EJS
app.get('/', (req, res) => {
res.render('index', { title: 'Home' });
});
app.get('/set-flash', (req, res) => {
req.flash('success', 'This is a success message!');
req.flash('info', 'Information to note.');
res.redirect('/show-flash');
});
app.get('/show-flash', (req, res) => {
// Messages are automatically available in res.locals due to middleware above
res.render('show', { title: 'Flash Messages' });
});
app.listen(PORT, () => {
console.log(`Server running on http://localhost:${PORT}`);
});
// You would also need 'views/index.ejs' and 'views/show.ejs' templates:
/* views/index.ejs */
// <h1><%= title %></h1>
// <a href="/set-flash">Set Flash Messages</a>
/* views/show.ejs */
// <h1><%= title %></h1>
// <% if (success_msg.length) { %>
// <div class="alert alert-success"><%= success_msg %></div>
// <% } %>
// <% if (info_msg.length) { %>
// <div class="alert alert-info"><%= info_msg %></div>
// <% } %>
// <% if (error_msg.length) { %>
// <div class="alert alert-danger"><%= error_msg %></div>
// <% } %>
// <a href="/">Go Home</a>
Debug
Known issues
breakingThe original usage examples with `app.configure`, `express.cookieParser`, and `express.session` are deprecated and removed in Express 4.x and later. These must be replaced with separate `cookie-parser` and `express-session` middleware.fixMigrate to `cookie-parser` and `express-session` npm packages. Install them (`npm install cookie-parser express-session`) and use them as separate middleware: `app.use(cookieParser('secret')); app.use(session({ ... }));` affects: <=0.1.1 (used with old Express versions)
gotchaconnect-flash does not officially support ES Modules (ESM). Attempting to use `import flash from 'connect-flash';` directly in an ESM project may lead to runtime errors or `req.flash` being undefined, especially if `type: "module"` is set in `package.json`.fixFor projects using ESM, it is generally safer to transpile connect-flash or ensure compatibility through tools like Babel. If possible, consider alternative, actively maintained flash message libraries with explicit ESM support or stick to CommonJS for connect-flash integration.
affects: All versions
gotchaFlash messages are stored in the session. If `express-session` middleware is not correctly configured or is placed *after* `connect-flash` middleware, `req.flash` will not be available, leading to runtime errors.fixEnsure `express-session` (and `cookie-parser` if used separately) is initialized and placed in the middleware chain *before* `connect-flash`. For example: `app.use(cookieParser(...)); app.use(session(...)); app.use(flash());`
affects: All versions
deprecatedThe `connect-flash` package is effectively abandoned, with its last update 13 years ago. While still functional, it receives no security updates or new features.fixFor new projects, consider using a more modern and actively maintained flash message solution or implementing a custom, simple session-based message system. For existing projects, be aware of potential vulnerabilities or compatibility issues with newer Node.js or Express versions.
affects: All versions
Errors
Common errors & fixes
TypeError: req.flash is not a function
`connect-flash` middleware has not been applied, or `express-session` middleware (which `connect-flash` depends on) was not initialized or was placed after `connect-flash` in the middleware chain.
fixEnsure `express-session` and `cookie-parser` (if used) are loaded before `connect-flash`. Example: `app.use(cookieParser('secret')); app.use(session({ secret: '...', resave: false, saveUninitialized: true })); app.use(flash());` Flash messages do not appear or are empty in the view.
Flash messages are cleared after being retrieved. If `req.flash()` is called multiple times for the same key, or if `res.locals` assignment is done incorrectly, messages might be consumed before the view can render them.
fixEnsure `req.flash()` is called exactly once to retrieve messages for display, typically in a middleware that populates `res.locals` before rendering. Verify that your template correctly accesses the `res.locals` variables. Also check if a redirect is happening before `res.locals` are set or if the session is correctly configured.
ReferenceError: app.configure is not defined
`app.configure` was deprecated in Express 3.x and completely removed in Express 4.x. `connect-flash` examples from its original README use this syntax.
fixRemove `app.configure` blocks. Apply middleware directly to the `app` object without conditional configuration blocks, as Express 4.x+ supports a unified middleware chain. E.g., replace `app.configure(function() { app.use(...) });` with `app.use(...);` Audit
Dependencies
express-sessionrequiredRequired for storing flash messages in the session. connect-flash relies entirely on an active session.
cookie-parserrequiredOften needed alongside express-session for parsing cookies, especially in older Express setups. Modern express-session can often handle this internally but explicit cookie-parser usage is common for compatibility or specific needs.