@devbie/newbie

A batteries-included backend application framework runtime built on top of NestJS 11, Prisma 7 and Express 5. Newbie gives you a production-ready bootstrap in a single call — security middleware, validation, cursor pagination pipes, a layered exception-filter chain, extended Prisma access and optional self-reporting — without forcing you to wire it all together.

Features

• One-call bootstrap — NewbieFactory.create() configures CORS, cookie parsing, body parsers, the global ValidationPipe, Helmet (production) and Swagger (development), then starts the HTTP server.
• Global framework module — FrameworkModule.forRoot() installs config loading, rate limiting, HttpModule, a unified response interceptor and a five-layer exception-filter chain.
• Extended Prisma integration — supply your generated PrismaClient and get a global PrismaService that supports client extensions registered after module initialization.
• Query parameter pipes — cursor pagination, cursor slug, ordering and select/include/where parsing for Prisma-driven list endpoints.
• Shared DTOs and utilities — pagination request/response DTOs plus crypto, datetime, array and other common helpers.
• Observability built in — graceful shutdown with bounded request draining, watch-mode port-race recovery, and env-gated backend monitor probe (BACKEND_MONITOR_ENDPOINT + BACKEND_MONITOR_TOKEN) and module-hub reporter (MODULE_HUB_ENDPOINT + MODULE_HUB_TOKEN).

Requirements

@devbie/newbie is a runtime library; NestJS, Prisma and related packages are declared as peer dependencies so your project controls their versions:

Installation

npm install @devbie/newbie

Quick start

Register FrameworkModule.forRoot() in your root module and pass your generated PrismaClient constructor:

// src/application/application.module.ts
import { Module } from "@nestjs/common";
import { FrameworkModule } from "@devbie/newbie";
import { PrismaClient } from "@generated/prisma/client";
import { ApplicationController } from "./application.controller";

@Module({
  imports: [FrameworkModule.forRoot({ prisma: { PrismaClient } })],
  controllers: [ApplicationController],
})
export class ApplicationModule {}

Then bootstrap with NewbieFactory:

// src/main.ts
import { NewbieFactory } from "@devbie/newbie";
import { ApplicationModule } from "./application/application.module";

async function bootstrap(): Promise<void> {
  await NewbieFactory.create(ApplicationModule, {
    swagger: { title: "My API" },
  });
}

void bootstrap();

The fastest way to get this structure is to scaffold a project with the companion CLI:

npx @devbie/newbie-cli create my-app

NewbieFactory options

NewbieFactory.create(rootModule, options) accepts the following options (every field is optional):

What the framework wires for you

• cookie-parser, JSON/URL-encoded body parsers, and always-on text/plain parsing (monitor SDKs report via navigator.sendBeacon).
• CORS with credentials, plus the v4 (extended) Express query parser. Routes decorated with @AllowAnyOrigin() answer Access-Control-Allow-Origin: * (preflight included) while every other route keeps the origin whitelist.
• A global ValidationPipe with transform and whitelist enabled.
• Helmet in production; Swagger UI (cookie + bearer auth) in development.
• A global throttler guard (10000 requests / second per endpoint by default).
• A response-shaping HttpResponseInterceptor.
• Exception filters in priority order: throttler → Prisma → newbie → HTTP → catch-all, so every failure gets a consistent error envelope.
• Env-gated reporters after listen: heartbeat (HEARTBEAT_*), module-hub (MODULE_HUB_*) and dependency health (HEALTH_*; checks always run, the POST is skipped when the endpoint is unset).

List endpoints and query pipes

Newbie ships pipes that translate query parameters into Prisma arguments:

• WherePipe — parse a where query parameter into a Prisma filter.
• OrderByPipe — parse ordering parameters.
• SelectIncludePipe — parse select / include parameters.
• CursorPipe / CursorSlugPipe — keyset (cursor) pagination parameters.

Shared DTOs (CommonListRequestDto, CommonListResponseDto, CommonGetByStringIdRequestDto, CommonGetByNumberIdRequestDto) keep list endpoints consistent across modules. The @Cookies() parameter decorator provides typed access to request cookies.

Environment variables

When both MODULE_HUB_ENDPOINT and MODULE_HUB_TOKEN are present, the framework automatically sends a full snapshot on boot and a ping every 60 seconds. Reporting is fire-and-forget and never blocks application startup.

Related packages

• @devbie/newbie-cli — scaffold projects and install modules from the newbie-modules registry.
• @devbie/heartbeat-sdk — framework-agnostic installation liveness reporting.
• @devbie/web-monitor-sdk — browser-side PV, AJAX, resource and JS error reporting.

License

MIT