![\"bro.js](\"https://brojs.yessindevs.me/bro.js.png\")
\r\n \r\n \r\n
\r\n The zero-boilerplate Node.js framework that actually has your back.\r\n
\r\n\r\n ![\"npm](\"https://img.shields.io/npm/v/bro-framework.svg?style=flat-square&color=e11d48\")
\r\n ![\"License:](\"https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square\"){kind=icon}
\r\n ![\"Node.js:](\"https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg?style=flat-square\"){kind=icon}
= 18\">\r\n ![\"Architecture:](\"https://img.shields.io/badge/Architecture-Pure%20ESM-orange.svg?style=flat-square\"){kind=icon}
\r\n ![\"Validation:](\"https://img.shields.io/badge/Validation-Zod-3068b7.svg?style=flat-square\"){kind=icon}
\r\n ![\"Realtime:](\"https://img.shields.io/badge/Realtime-Socket.io-black.svg?style=flat-square\"){kind=icon}
\r\n ![\"Engine:](\"https://img.shields.io/badge/Engine-Express-eeeeee.svg?style=flat-square\"){kind=icon}
\r\n
\r\n Documentation Website\r\n
\r\n\r\n\r\n---\r\n\r\n> Skip the boilerplate. bro.js gives you file-based routing, automatic Zod validation, JWT auth, and WebSockets right out of the box. Just write your business logic, return an object, and let the framework handle the rest.\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n- [Getting Started](#getting-started)\r\n- [Configuration](#configuration)\r\n- [The Core Experience](#the-core-experience)\r\n- [Deep-Dive Features](#deep-dive-features)\r\n- [Route Reference](#route-reference)\r\n- [Context Reference](#context-reference)\r\n- [Architecture & Request Lifecycle](#architecture--request-lifecycle)\r\n- [Tech Stack Breakdown](#tech-stack-breakdown)\r\n- [CLI Reference](#cli-reference)\r\n- [Next.js App Router Integration](#nextjs-app-router-integration)\r\n- [Author & License](#author--license)\r\n\r\n---\r\n\r\n## Getting Started\r\n\r\nBootstrapping a new `bro.js` project is incredibly simple. We recommend using our official scaffolding tool to set everything up instantly (with your choice of JavaScript or TypeScript):\r\n\r\n```bash\r\nnpx create-bro-framework@latest my-api\r\ncd my-api\r\nnpm run dev\r\n```\r\n\r\nThat's it! Your zero-boilerplate backend is now running with hot-reloading enabled.\r\n\r\n## Configuration\r\n\r\nConfiguration lives in `bro.config.js`:\r\n\r\n```javascript\r\nimport { defineConfig } from 'bro-framework';\r\n\r\nexport default defineConfig({\r\n server: { port: 5000, cors: true, helmet: true },\r\n auth: {\r\n jwtSecret: process.env.JWT_SECRET,\r\n expiresIn: '7d',\r\n apiKey: process.env.API_KEY\r\n },\r\n locale: { directory: './locale', defaultLocale: 'en' },\r\n rateLimit: { windowMs: 15 * 60 * 1000, max: 100 },\r\n docs: process.env.NODE_ENV !== 'production',\r\n redisUrl: process.env.REDIS_URL,\r\n db: async () => {\r\n // Initialize database connection here\r\n },\r\n sockets: async (io, db) => {\r\n // Setup Socket.IO event listeners here\r\n },\r\n onShutdown: async (db) => {\r\n // Close application-owned database resources here.\r\n }\r\n});\r\n```\r\n\r\n`cors: false` disables HTTP CORS middleware. Helmet is enabled by default and can be disabled with `helmet: false`. Redis is optional; when configured it powers distributed rate limiting, route caching, and Socket.IO scaling. In `NODE_ENV=test`, bro.js can inject `ioredis-mock`; install it in the consuming project's development dependencies.\r\n\r\n> **Production Security Note**: When deploying behind a reverse proxy (Nginx, AWS ALB, Vercel, Render), ensure your load balancer properly sets `X-Forwarded-For`. Rate limiting and trusted IP functionality relies on this proxy configuration.\r\n\r\n---\r\n\r\n## The Core Experience\r\n\r\nIn `bro.js`, everything you need is handed to you instantly. No setup, no middleware wrangling, no manual `req/res` handling. You define your route, set your validation, and return an object. \r\n\r\n`routes/posts/[id].post.js`:\r\n\r\n```javascript\r\nimport { defineRoute, z } from 'bro-framework';\r\n\r\nexport default defineRoute({\r\n auth: true,\r\n params: z.object({\r\n id: z.string().uuid()\r\n }),\r\n body: z.object({\r\n title: z.string().min(5),\r\n content: z.string()\r\n }),\r\n query: z.object({\r\n draft: z.coerce.boolean().default(false)\r\n }),\r\n response: z.object({\r\n success: z.boolean(),\r\n updated: z.number()\r\n }),\r\n handler: async ({ body, params, user, db, io }) => {\r\n // 1. Data is already validated. user is already authenticated.\r\n \r\n // 2. Perform database operation using the injected Mongoose context\r\n const post = await db.collection('posts').updateOne(\r\n { _id: params.id },\r\n { $set: { ...body, authorId: user.id } }\r\n );\r\n \r\n // 3. Broadcast to all clients instantly using injected Socket.io\r\n io.emit('post_updated', { postId: params.id, title: body.title });\r\n \r\n // 4. Return an object. bro.js handles the 200 JSON response.\r\n return {\r\n success: true,\r\n updated: post.modifiedCount\r\n };\r\n }\r\n});\r\n```\r\n\r\nValidation schemas are flat and must be declared directly as `body`, `params`, and `query`. The deprecated nested `schema: { body, params, query }` form is rejected during route loading. The optional `response` schema documents the successful JSON response in OpenAPI; it does not runtime-validate handler output.\r\n\r\n---\r\n\r\n## Deep-Dive Features\r\n\r\n### File-Based Routing\r\nCreate a `.js` file in the `routes/` directory, and it automatically becomes an endpoint. We use Next.js-style bracket syntax for dynamic parameters. A file named `routes/users/[id].get.js` translates natively to a `GET /users/:id` Express route under the hood.\r\n\r\n### Bouncer-Grade Validation\r\nPowered by Zod. Attach a schema to `body`, `query`, or `params` directly in your route definition. If the client sends malformed data, `bro.js` automatically rejects the request with a structured `400 Bad Request` JSON payload *before* your handler ever executes. You never have to manually validate inputs again. You can also define a `response` schema to strongly type your OpenAPI documentation (strictly opt-in; arbitrary 200s work out of the box).\r\n\r\n### Zero-Config Auth (JWTs, RBAC, API Keys)\r\nAdd `auth: true` to your route config. `bro.js` will intercept the request, extract the `Authorization: Bearer