{"id":10590,"library":"bragg","title":"Bragg: AWS Lambda Web Framework","description":"Bragg is a concise AWS Lambda web framework that provides a Koa.js-inspired middleware pattern for handling serverless HTTP requests. It simplifies the process of building API Gateway-backed Lambda functions by allowing developers to chain middleware functions that operate on a `ctx` (context) object. As of its current stable version, 1.4.0, Bragg maintains a focused scope, emphasizing a clear request-response cycle and robust error handling through its `app.onError()` mechanism, which supports asynchronous cleanup processes. Its release cadence appears stable rather than rapid, indicating a mature project. A key differentiator is its straightforward approach to promise resolution for `ctx.body`, automatically awaiting results before sending the Lambda response. It requires Node.js version 4 or higher.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/SamVerschueren/bragg","tags":["javascript","aws","lambda","web","framework","bragg"],"install":[{"cmd":"npm install bragg","lang":"bash","label":"npm"},{"cmd":"yarn add bragg","lang":"bash","label":"yarn"},{"cmd":"pnpm add bragg","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Bragg is primarily a CommonJS package, as indicated by its Node.js engine requirement of `>=4`. Use `require` for consistent behavior.","wrong":"import bragg from 'bragg';","symbol":"bragg","correct":"const bragg = require('bragg');"},{"note":"The `listen()` method returns the actual AWS Lambda handler function, not the `app` instance itself.","wrong":"exports.handler = app;","symbol":"app.listen()","correct":"exports.handler = app.listen();"},{"note":"Middleware functions can be synchronous or asynchronous (return Promises or use `async/await`) and receive a `ctx` object and optionally the result from the previous middleware.","symbol":"app.use()","correct":"app.use(async ctx => { /* ... */ });"}],"quickstart":{"code":"const bragg = require('bragg');\nconst app = bragg();\n\n// Add a simple middleware that sets the response body\napp.use(ctx => {\n\tctx.body = 'Hello, Lambda!';\n});\n\n// Add an error handler for unhandled exceptions within middlewares\napp.onError(err => {\n\tconsole.error('An error occurred:', err.message);\n\t// Perform async cleanup or custom error response\n\treturn { statusCode: 500, body: 'Internal Server Error' };\n});\n\n// Export the handler function for AWS Lambda\nexports.handler = app.listen();\n\n// To test locally, you can invoke the handler directly (for demonstration):\n// async function testLocal() {\n//   const event = {}; // Minimal event for basic test\n//   const context = {};\n//   const callback = (error, result) => {\n//     if (error) console.error('Local Test Error:', error);\n//     else console.log('Local Test Result:', result);\n//   };\n//   await exports.handler(event, context, callback);\n// }\n// testLocal();","lang":"javascript","description":"This example demonstrates how to initialize Bragg, add a basic middleware to set the response body, configure an error handler, and export the resulting function for AWS Lambda."},"warnings":[{"fix":"Review `onError` implementations when upgrading to v1.4.0+ to ensure desired error propagation behavior. If you want errors to be caught by Lambda's runtime, you can now simply `throw err;` within `onError`.","message":"In version 1.4.0, the `onError` function was updated to allow throwing errors directly, which will propagate them to Lambda's default error handling. In previous versions, custom error handling in `onError` might have suppressed these errors unless explicitly re-thrown or handled.","severity":"breaking","affected_versions":">=1.4.0"},{"fix":"Add the provided mapping template (or a similar one) to your API Gateway Integration Request settings, ensuring the Lambda function receives the correct event structure. Refer to the 'Mapping template' section in the Bragg README.","message":"For Bragg to receive path parameters, query strings, and body data from API Gateway, you must configure a 'Mapping Template' in the Integration Request section of your API Gateway method. Without this, `ctx.request.params`, `ctx.request.query`, and `ctx.request.body` will be undefined or empty.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `const bragg = require('bragg');` when integrating Bragg into your Node.js Lambda functions, unless you are specifically using a build process that handles CJS-ESM interop.","message":"Bragg relies on CommonJS `require()` syntax and is built for Node.js environments `>=4`. While modern Node.js supports ESM `import` statements, attempting to `import bragg from 'bragg'` directly in an ESM module context without proper transpilation or configuration can lead to runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `const bragg = require('bragg');` is present at the top of your file.","cause":"Attempting to use `bragg` without correctly requiring it, or using ESM `import` in a CommonJS context.","error":"ReferenceError: bragg is not defined"},{"fix":"Verify that your API Gateway Integration Request has a mapping template configured to pass parameters, query strings, and the body to your Lambda function's event payload, as described in the Bragg documentation.","cause":"The API Gateway mapping template is not configured or is incorrect, resulting in an empty or malformed `request` object within the Lambda event.","error":"TypeError: Cannot read properties of undefined (reading 'params')"},{"fix":"Ensure your Lambda function's entry point (`index.js` or similar) contains `exports.handler = app.listen();`.","cause":"The AWS Lambda handler is not correctly configured to export the function returned by `app.listen()`.","error":"Function.handler is not a function"},{"fix":"Ensure `const app = bragg();` is called before attempting to use `app.listen()`.","cause":"`app` variable was not correctly initialized by calling `bragg()` or was overwritten.","error":"TypeError: app.listen is not a function"}],"ecosystem":"npm"}