|
| 1 | +# NodeBoot Vercel Server |
| 2 | + |
| 3 | +Vercel Serverless Functions server package for NodeBoot framework. Provides seamless integration with Vercel's |
| 4 | +Node.js runtime while maintaining all NodeBoot features including dependency injection, middleware, routing, and |
| 5 | +error handling. |
| 6 | + |
| 7 | +## Features |
| 8 | + |
| 9 | +- **Multi-route Serverless Functions**: Handle multiple HTTP routes in a single Vercel Serverless Function |
| 10 | +- **Full NodeBoot Integration**: Complete support for controllers, services, middleware, and dependency injection |
| 11 | +- **Native Node.js Runtime**: Works directly with Vercel's Node.js `VercelRequest`/`VercelResponse` objects |
| 12 | +- **Request/Response Handling**: Automatic parsing of JSON bodies, query parameters, headers, and cookies |
| 13 | +- **Error Handling**: Integrated error handling with proper HTTP status codes |
| 14 | +- **Authorization**: Built-in authorization support using NodeBoot's authorization system |
| 15 | + |
| 16 | +## Installation |
| 17 | + |
| 18 | +```bash |
| 19 | +npm install @nodeboot/vercel-server |
| 20 | +``` |
| 21 | + |
| 22 | +## Basic Usage |
| 23 | + |
| 24 | +### 1. Create your Vercel application |
| 25 | + |
| 26 | +```typescript |
| 27 | +import {VercelServer} from "@nodeboot/vercel-server"; |
| 28 | +import {NodeBootApplication} from "@nodeboot/core"; |
| 29 | + |
| 30 | +@EnableDI(Container) |
| 31 | +@EnableValidations() |
| 32 | +@EnableComponentScan() |
| 33 | +@NodeBootApplication() |
| 34 | +export class VercelSampleApp implements NodeBootApp { |
| 35 | + start(): Promise<NodeBootAppView> { |
| 36 | + return NodeBoot.run(VercelServer); |
| 37 | + } |
| 38 | +} |
| 39 | +``` |
| 40 | + |
| 41 | +### 2. Create the Serverless Function entry point |
| 42 | + |
| 43 | +Vercel automatically maps files under the `api/` directory to routes. Use a catch-all route so that a single |
| 44 | +Serverless Function can handle every path processed by NodeBoot's internal router: |
| 45 | + |
| 46 | +```typescript |
| 47 | +// api/[...path].ts |
| 48 | +import {VercelHandler, VercelServer} from "@nodeboot/vercel-server"; |
| 49 | +import {VercelSampleApp} from "../src/app"; |
| 50 | + |
| 51 | +// Reused across warm invocations of the same execution environment. |
| 52 | +// Only re-initialized when Vercel spins up a brand-new instance (cold start). |
| 53 | +let vercelHandler: VercelHandler | null = null; |
| 54 | + |
| 55 | +export default async function handler(req: VercelRequest, res: VercelResponse) { |
| 56 | + if (!vercelHandler) { |
| 57 | + const app = await new VercelSampleApp().start(); |
| 58 | + const vercelServer = app.server as VercelServer; |
| 59 | + vercelHandler = vercelServer.getHandler(); |
| 60 | + } |
| 61 | + |
| 62 | + return vercelHandler(req, res); |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +### 3. Create Controllers |
| 67 | + |
| 68 | +```typescript |
| 69 | +import {Controller, Get, Post, Param, Body} from "@nodeboot/core"; |
| 70 | + |
| 71 | +@Controller("/api") |
| 72 | +export class UserController { |
| 73 | + @Get("/users/:id") |
| 74 | + getUser(@Param("id") id: string) { |
| 75 | + return {id, name: `User ${id}`}; |
| 76 | + } |
| 77 | + |
| 78 | + @Post("/users") |
| 79 | + createUser(@Body() userData: any) { |
| 80 | + return {success: true, user: userData}; |
| 81 | + } |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +### 4. Deploy to Vercel |
| 86 | + |
| 87 | +The exported `handler` function can be deployed directly as a Vercel Node.js Serverless Function - no additional |
| 88 | +configuration is required beyond routing every request to the catch-all `api/[...path].ts` entry point. |
| 89 | + |
| 90 | +## Middleware Support |
| 91 | + |
| 92 | +All NodeBoot middleware is supported: |
| 93 | + |
| 94 | +```typescript |
| 95 | +import {Middleware, MiddlewareInterface, Action} from "@nodeboot/core"; |
| 96 | + |
| 97 | +@Middleware({type: "before"}) |
| 98 | +export class LoggingMiddleware implements MiddlewareInterface { |
| 99 | + @Inject() |
| 100 | + private logger: Logger; |
| 101 | + |
| 102 | + use(action: Action, payload: any): void { |
| 103 | + this.logger.info(`${action.request.method} ${action.request.url}`); |
| 104 | + } |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +## Error Handling |
| 109 | + |
| 110 | +Custom error handlers work seamlessly: |
| 111 | + |
| 112 | +```typescript |
| 113 | +import {ErrorHandler, ErrorHandlerInterface} from "@nodeboot/core"; |
| 114 | + |
| 115 | +@ErrorHandler() |
| 116 | +export class CustomErrorHandler implements ErrorHandlerInterface { |
| 117 | + onError(error: any, action: Action): void { |
| 118 | + // Custom error handling logic |
| 119 | + } |
| 120 | +} |
| 121 | +``` |
| 122 | + |
| 123 | +## Authorization |
| 124 | + |
| 125 | +NodeBoot's authorization system is fully supported. Use decorators like `@Authorize()` in your controllers to protect |
| 126 | +routes. |
| 127 | + |
| 128 | +```typescript |
| 129 | +import {Authorize, Controller, Get} from "@nodeboot/core"; |
| 130 | + |
| 131 | +@Controller("/secure") |
| 132 | +export class SecureController { |
| 133 | + @Get("/data") |
| 134 | + @Authorize("admin") |
| 135 | + getSecureData() { |
| 136 | + return {secret: "This is secure data"}; |
| 137 | + } |
| 138 | +} |
| 139 | +``` |
| 140 | + |
| 141 | +## Conclusion |
| 142 | + |
| 143 | +The NodeBoot Vercel Server package provides a powerful way to build serverless applications using the familiar |
| 144 | +NodeBoot framework. With full support for routing, middleware, error handling, and authorization, you can create |
| 145 | +robust APIs that run on Vercel's Node.js Serverless Functions with ease. |
| 146 | + |
| 147 | +## License |
| 148 | + |
| 149 | +This project is licensed under the MIT License. |
0 commit comments