Registry / web-framework / bragg

bragg

JSON →
library0.0.0jsnpmunverified

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.

web-frameworkawshttp-networking
npm install bragg
github ↗package ↗
INSTALL
IMPORT
SIG · BRAGG
B
bragg
web-frameworkjavascriptv0.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

bragg
✓ const bragg = require('bragg');
✗ import bragg from 'bragg';
Bragg is primarily a CommonJS package, as indicated by its Node.js engine requirement of `>=4`. Use `require` for consistent behavior.
app.listen()
✓ exports.handler = app.listen();
✗ exports.handler = app;
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.

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();
Debug
Known issues
breakingIn 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`.
affects: >=1.4.0
gotchaFor 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.
affects: >=1.0.0
gotchaBragg 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.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: bragg is not defined
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')
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
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
`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()`.
Upgrade
Version history
0.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
12
Amazon
1
OpenAI (training)
1
Resources
githubhttps://github.com/SamVerschueren/bragg ↗
packagehttps://www.npmjs.com/package/bragg ↗
bragg — npm install bragg · libregistry