Bragg: AWS Lambda Web Framework

Common errors

• ReferenceError: bragg is not defined

  cause Attempting to use `bragg` without correctly requiring it, or using ESM `import` in a CommonJS context.
  fix Ensure `const bragg = require('bragg');` is present at the top of your file.

• TypeError: Cannot read properties of undefined (reading 'params')

  cause The API Gateway mapping template is not configured or is incorrect, resulting in an empty or malformed `request` object within the Lambda event.
  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.

• Function.handler is not a function

  cause The AWS Lambda handler is not correctly configured to export the function returned by `app.listen()`.
  fix Ensure your Lambda function's entry point (`index.js` or similar) contains `exports.handler = app.listen();`.

• TypeError: app.listen is not a function

  cause `app` variable was not correctly initialized by calling `bragg()` or was overwritten.
  fix Ensure `const app = bragg();` is called before attempting to use `app.listen()`.

Warnings

• breaking 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.
  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`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install bragg npm
• yarn add bragg yarn
• pnpm add bragg pnpm

Imports

• bragg
  wrong:

  import bragg from 'bragg';

  correct:

  const bragg = require('bragg');

  Bragg is primarily a CommonJS package, as indicated by its Node.js engine requirement of `>=4`. Use `require` for consistent behavior.
• app.listen()
  wrong:

  exports.handler = app;

  correct:

  exports.handler = app.listen();

  The `listen()` method returns the actual AWS Lambda handler function, not the `app` instance itself.
• app.use()

  app.use(async ctx => { /* ... */ });

  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.

Quickstart

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.

const bragg = require('bragg');
const app = bragg();

// Add a simple middleware that sets the response body
app.use(ctx => {
	ctx.body = 'Hello, Lambda!';
});

// Add an error handler for unhandled exceptions within middlewares
app.onError(err => {
	console.error('An error occurred:', err.message);
	// Perform async cleanup or custom error response
	return { statusCode: 500, body: 'Internal Server Error' };
});

// Export the handler function for AWS Lambda
exports.handler = app.listen();

// To test locally, you can invoke the handler directly (for demonstration):
// async function testLocal() {
//   const event = {}; // Minimal event for basic test
//   const context = {};
//   const callback = (error, result) => {
//     if (error) console.error('Local Test Error:', error);
//     else console.log('Local Test Result:', result);
//   };
//   await exports.handler(event, context, callback);
// }
// testLocal();