{"id":17099,"library":"flowstate","title":"Flowstate Per-Request State Management","description":"Flowstate is a Node.js middleware designed for managing and propagating per-request state across a sequence of HTTP requests within an Express or Connect application. It allows developers to implement 'flows' where state is maintained across multiple redirects and user interactions, culminating in a desired outcome. By default, it integrates with existing session middleware, isolating state for specific request sequences rather than global session state. State propagation relies on `return_to` and `state` query/body parameters, which the middleware automatically handles on redirects and exposes via `res.locals` for manual inclusion in views. The current and only stable version is 0.6.0, published in 2017. The package appears to be abandoned, with no releases or significant activity since that time, making it potentially incompatible with modern Node.js and Express versions.","status":"abandoned","version":"0.6.0","language":"javascript","source_language":"en","source_url":"git://github.com/jaredhanson/flowstate","tags":["javascript","express","connect","state"],"install":[{"cmd":"npm install flowstate","lang":"bash","label":"npm"},{"cmd":"yarn add flowstate","lang":"bash","label":"yarn"},{"cmd":"pnpm add flowstate","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is CommonJS-only and was last updated in 2017. It does not support ES Modules natively.","wrong":"import flowstate from 'flowstate';","symbol":"flowstate","correct":"const flowstate = require('flowstate');"},{"note":"The primary export is a function that returns the middleware; there are no other named exports for direct import.","symbol":"FlowstateMiddleware","correct":"const flowstate = require('flowstate');\n// flowstate() returns the middleware function"}],"quickstart":{"code":"const express = require('express');\nconst session = require('express-session');\nconst flowstate = require('flowstate');\n\nconst app = express();\n\n// Basic session middleware is required for flowstate to persist data.\n// In a real application, configure a robust session store.\napp.use(session({\n  secret: process.env.SESSION_SECRET || 'a-very-secret-key',\n  resave: false,\n  saveUninitialized: false,\n  cookie: { secure: false } // Set to true in production with HTTPS\n}));\n\n// Set up a simple view engine (e.g., EJS for demonstration)\napp.set('view engine', 'ejs');\napp.set('views', __dirname + '/views');\n\napp.get('/login', flowstate(), function(req, res, next) {\n  // Access current state via req.state\n  const messages = req.state.messages || [];\n  res.locals.messages = messages;\n  res.locals.hasMessages = !! messages.length;\n\n  // Propagate return_to and state via res.locals for view rendering\n  // if not already managed by flowstate itself (e.g., if a new state is created)\n  res.locals.returnTo = res.locals.returnTo || req.query.return_to;\n  res.locals.stateParam = res.locals.state || req.query.state;\n  \n  console.log('Current state handle:', res.locals.stateParam);\n  console.log('Return to:', res.locals.returnTo);\n\n  res.render('login', { \n    title: 'Login',\n    // Example: Pass state information to the view\n    flowstateHandle: res.locals.stateParam,\n    returnTo: res.locals.returnTo\n  });\n});\n\n// Dummy /views/login.ejs content for illustration:\n// <form action=\"/login\" method=\"POST\">\n//   <input type=\"hidden\" name=\"return_to\" value=\"<%= returnTo %>\">\n//   <input type=\"hidden\" name=\"state\" value=\"<%= flowstateHandle %>\">\n//   <button type=\"submit\">Login</button>\n// </form>\n\napp.listen(3000, () => {\n  console.log('Server running on http://localhost:3000');\n  console.log('Try visiting: http://localhost:3000/login?return_to=/dashboard');\n});","lang":"javascript","description":"This quickstart demonstrates how to integrate flowstate middleware into an Express application, requiring `express-session` for state persistence. It shows how to initialize the middleware on a route, access per-request state via `req.state`, and manually propagate `return_to` and `state` parameters to a view using `res.locals` for subsequent requests."},"warnings":[{"fix":"Consider using alternative state management libraries, building custom middleware, or relying on modern framework features. Thorough testing with your current environment is essential if you must use it.","message":"The `flowstate` package is abandoned and has not been updated since 2017 (version 0.6.0). It is highly likely to have compatibility issues with modern Node.js versions (e.g., Node.js 16+) and recent major versions of Express. Using it in new projects is strongly discouraged, and existing projects should consider migration.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Ensure you have a compatible session middleware (e.g., `npm install express-session`) and configure it globally or on relevant routes before initializing `flowstate` middleware. Example: `app.use(session({ /* ... */ })); app.use(flowstate());`","message":"Flowstate relies on a standard session middleware (e.g., `express-session`) to persist state across requests. If a session middleware is not configured and mounted *before* flowstate, the state will not be persisted correctly, leading to unexpected behavior.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"In your view templates, ensure that any links or forms meant to continue a flow include `return_to` and `state` query parameters or hidden inputs, populated from `res.locals`. For example: `<a href=\"/next?return_to=<%= returnTo %>&state=<%= stateParam %>\">Continue</a>`.","message":"When rendering views, `flowstate` requires manual propagation of `return_to` and `state` parameters in generated links or form hidden inputs. The middleware exposes these values on `res.locals.returnTo` and `res.locals.state` (or `res.locals.stateParam` in some examples if `res.locals.state` is used by other middleware) which must be explicitly used by your templating engine.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use CommonJS `require()` syntax: `const flowstate = require('flowstate');`. If integrating into an ESM project, consider dynamic import (`import('flowstate')`) or a transpilation step, though the abandoned status makes this generally unadvisable.","message":"This package is CommonJS-only and cannot be directly imported using ES module syntax (`import ... from 'pkg'`). Attempting to use ES module imports will result in errors in environments that enforce ESM.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `flowstate()` is called as a function `app.use(flowstate())`. Also verify that your Express version is compatible; given the package's age, very recent Express versions might have breaking changes.","cause":"The `flowstate` function was called without being initialized, or an incompatible version of Express is being used.","error":"TypeError: app.use() requires middleware functions but got a [object Undefined]"},{"fix":"Add a compatible session middleware, such as `express-session`, before `flowstate` in your middleware stack. Example: `app.use(require('express-session')({ secret: '...', resave: false, saveUninitialized: false })); app.use(flowstate());`","cause":"`flowstate` middleware was invoked without a session middleware being active or correctly configured upstream. Flowstate depends on `req.session` being available.","error":"Error: Failed to find session"},{"fix":"Inspect your rendered HTML to ensure that `return_to` and `state` query parameters (for links) or hidden form fields (for forms) are present and populated with the values from `res.locals.returnTo` and `res.locals.state` (or `res.locals.stateParam`). Also, double-check your `express-session` configuration for proper setup.","cause":"The `return_to` and `state` parameters are not being correctly propagated in your view templates (links, hidden form fields) or the session middleware is misconfigured.","error":"State does not persist across redirects or form submissions."}],"ecosystem":"npm","meta_description":null}