{"id":16719,"library":"dolphin-server-modules","title":"Dolphin Server Modules","description":"Dolphin Server Modules is the core utility package for the Dolphin Framework, an ultra-lightweight and modular backend ecosystem built on native Node.js. It provides fundamental functionalities for building Web, Microservices, and Industrial IoT applications, focusing on Auth, CRUD, Models, and Controllers. The current stable version is 2.2.4, with a recent feature release cadence indicated by updates like v2.2.1 and v2.2 bringing CLI usage and dynamic API proxies. Key differentiators include its zero-dependency core built on native `http` and `events`, universal compatibility with tools like Mongoose and Zod, support for Express-compatible multi-handler middleware, and native IIoT support via binary plugins for protocols like HL7 and Modbus. It also offers a unique server-served client library, eliminating the need for client-side NPM installations.","status":"active","version":"2.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/Phuyalshankar/dolphin-server-modules#readme","tags":["javascript","dolphin","server","auth","crud","controller","realtime","iot","2fa","typescript"],"install":[{"cmd":"npm install dolphin-server-modules","lang":"bash","label":"npm"},{"cmd":"yarn add dolphin-server-modules","lang":"bash","label":"yarn"},{"cmd":"pnpm add dolphin-server-modules","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary entry point for creating a Dolphin HTTP server. Dolphin is ESM-first.","wrong":"const { createDolphinServer } = require('dolphin-server-modules/server');","symbol":"createDolphinServer","correct":"import { createDolphinServer } from 'dolphin-server-modules/server';"},{"note":"Named export for the authentication utilities. Avoid default imports.","wrong":"import DolphinAuth from 'dolphin-server-modules/auth';","symbol":"DolphinAuth","correct":"import { DolphinAuth } from 'dolphin-server-modules/auth';"},{"note":"Named export for CRUD operations, often used with ORMs like Mongoose. Ensure you're importing from the correct subpath.","wrong":"require('dolphin-server-modules/crud');","symbol":"DolphinCRUD","correct":"import { DolphinCRUD } from 'dolphin-server-modules/crud';"},{"note":"Dolphin uses a unified `ctx` (context) object for handlers, similar to Koa. While it supports Express-style middleware, direct route handlers primarily use `ctx`.","wrong":"(req, res) => { /* ... */ }","symbol":"ctx","correct":"(ctx) => { /* ... */ }"}],"quickstart":{"code":"import { createDolphinServer } from 'dolphin-server-modules/server';\n\nconst app = createDolphinServer();\n\napp.get('/ping', (ctx) => {\n  return { message: 'pong', version: '1.5.6' };\n});\n\napp.get('/hello/:name', (ctx) => {\n  const name = ctx.params.name;\n  return { greeting: `Hello, ${name}!` };\n});\n\napp.post('/data', async (ctx) => {\n  const body = await ctx.req.json(); // Access raw request body\n  console.log('Received data:', body);\n  return { status: 'received', data: body };\n});\n\napp.listen(3000, () => console.log('🐬 Dolphin swimming on port 3000'));\n","lang":"typescript","description":"This quickstart demonstrates setting up a basic Dolphin web server with GET and POST routes, showcasing JSON serialization and context object usage."},"warnings":[{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) and use `import` statements for all Dolphin modules.","message":"Dolphin Framework is ESM-first since early v2.x versions. Using CommonJS `require()` statements for module imports will likely fail or lead to unexpected behavior.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Include `<script src=\"/dolphin-client.js\"></script>` in your HTML file to load the client library. It's automatically exposed by the Dolphin server.","message":"The Dolphin client-side library (`dolphin-client.js`) is served directly by the Dolphin server. Do not attempt to install it via npm or other package managers, as it is not distributed that way.","severity":"gotcha","affected_versions":">=2.2.0"},{"fix":"When writing middleware or handlers, use the `(ctx, next)` function signature. Access request details (like body or query params) via the `ctx` object properties (e.g., `ctx.query`, `ctx.params`, `ctx.req.json()`).","message":"The framework primarily uses a unified `ctx` (context) object in route handlers for consistency. While it supports Express-compatible middleware, custom middleware or legacy Express middleware might require adaptation to the `(ctx, next)` signature.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade `dolphin-server-modules` to v2.2.1 or newer to use the CLI. For older versions, you must create a dedicated server file and run it with `node`.","message":"The `npx dolphin-server` CLI tool for instantly running a Dolphin server was introduced in v2.2.1. Older versions will not have this command available.","severity":"gotcha","affected_versions":"<2.2.1"},{"fix":"Consult community resources or translate the guide as needed. The code examples within the guide are self-explanatory for most developers.","message":"The primary official master guide for Dolphin Framework is currently available in Nepali. While code examples are universal, detailed textual explanations are in Nepali, which might be a barrier for non-Nepali speaking developers.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure your `package.json` contains `\"type\": \"module\"` and all imports use `import ... from '...'`. If using TypeScript, check `tsconfig.json` for `\"module\": \"NodeNext\"` or `\"ESNext\"` and `\"moduleResolution\": \"NodeNext\"`.","cause":"Attempting to use CommonJS `require()` or running an ESM file without proper Node.js ESM configuration.","error":"ERR_MODULE_NOT_FOUND: Cannot find package 'dolphin-server-modules/server' imported from ..."},{"fix":"Verify that `import { createDolphinServer } from 'dolphin-server-modules/server';` is used, and that the `app` variable is correctly assigned the result of `createDolphinServer()`.","cause":"Incorrectly importing or initializing the server. This could also happen if `createDolphinServer` is not a named export or if an older version is used.","error":"TypeError: app.get is not a function"},{"fix":"Refactor your middleware to accept `ctx` as the first argument and `next` as the second. Use `await next()` to pass control to the next middleware or handler in the chain.","cause":"Providing a middleware function that does not match Dolphin's expected `(ctx, next)` signature, possibly from an Express.js-centric background.","error":"Error: Middleware must be a function with (ctx, next) signature."},{"fix":"Ensure your HTML includes `<script src=\"/dolphin-client.js\"></script>` before any script that attempts to use the `dolphin` global object. The Dolphin server must also be running to serve this file.","cause":"Attempting to use the `dolphin` client-side global object without including the server-served client library in the HTML.","error":"ReferenceError: dolphin is not defined"}],"ecosystem":"npm"}