Skip to main content

​
Prerequisites

Before installing StatusFlow, ensure you have:
  • Node.js - Version 14 or higher
  • Express - Version 4 or 5 (peer dependency)
  • TypeScript (optional) - Version 4.5 or higher for TypeScript projects

​
Install StatusFlow

Install StatusFlow using your preferred package manager: 
npm install status-flow

​
Install Express (Peer Dependency)

If you don’t already have Express installed, you’ll need to add it: 
npm install express

​
TypeScript Setup

StatusFlow is written in TypeScript and includes type definitions out of the box. If you’re using TypeScript, follow these steps:
1

Install TypeScript and Express types

npm install --save-dev typescript @types/express
2

Configure tsconfig.json

Ensure your tsconfig.json has the following settings:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
The resolveJsonModule option is important because StatusFlow uses JSON data files for HTTP status information.
3

Import with full type safety

import { 
  StatusFlow, 
  StatusFlowCodes,
  statusFlowMiddleware,
  HttpException,
  NotFoundException 
} from 'status-flow';

// TypeScript will provide full autocomplete and type checking

​
JavaScript Setup

For JavaScript projects, no additional configuration is needed: 
const { 
  StatusFlow, 
  StatusFlowCodes,
  statusFlowMiddleware 
} = require('status-flow');

​
Verify Installation

Create a simple test file to verify StatusFlow is working correctly:
1

Create test file

Create a file called test-statusflow.js (or .ts for TypeScript):
import { StatusFlow, StatusFlowCodes } from 'status-flow';

const response = StatusFlow({ 
  code: StatusFlowCodes.OK, 
  lang: 'en' 
});

console.log(response);
2

Run the test

npx ts-node test-statusflow.ts
3

Verify output

You should see output similar to:
{
  success: true,
  message: 'HTTP 200 - OK',
  code: 200,
  info: {
    name: 'OK',
    category: 'Successful',
    description: 'Standard HTTP success code 200.',
    possibleCauses: [ 'General cause depending on context.' ]
  }
}
If you see this output, StatusFlow is installed and working correctly!

​
Package Exports

StatusFlow provides the following exports:
ExportTypeDescription
StatusFlowFunctionGenerate status responses with bilingual support
StatusFlowCodesObjectConstants for all HTTP status codes
statusFlowMiddlewareFunctionExpress middleware for StatusFlow error handling
httpErrorMiddlewareFunctionExpress middleware for exception-based error handling
HttpExceptionClassBase exception class
BadRequestExceptionClass400 Bad Request exception
UnauthorizedExceptionClass401 Unauthorized exception
ForbiddenExceptionClass403 Forbidden exception
NotFoundExceptionClass404 Not Found exception
ConflictExceptionClass409 Conflict exception
InternalServerErrorExceptionClass500 Internal Server Error exception
createHttpResponseFunctionCreate response from HttpException
createSuccessResponseFunctionCreate success response with data

​
Common Installation Issues

Module not found errorsIf you encounter module resolution errors, ensure:
  • You’re using Node.js 14 or higher
  • Express is installed as a peer dependency
  • Your node_modules folder is up to date (try rm -rf node_modules && npm install)
TypeScript compilation errorsIf you see TypeScript errors:
  • Ensure @types/express is installed
  • Check that resolveJsonModule is set to true in tsconfig.json
  • Verify esModuleInterop is enabled

​
Next Steps

Quick Start Guide

Learn how to build a complete Express API with StatusFlow

Build docs developers (and LLMs) love

Get started for freeTalk to us