Dolphin Server Modules

Common errors

• ERR_MODULE_NOT_FOUND: Cannot find package 'dolphin-server-modules/server' imported from ...

  cause Attempting to use CommonJS `require()` or running an ESM file without proper Node.js ESM configuration.
  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"`.

• TypeError: app.get is not a function

  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.
  fix Verify that `import { createDolphinServer } from 'dolphin-server-modules/server';` is used, and that the `app` variable is correctly assigned the result of `createDolphinServer()`.

• Error: Middleware must be a function with (ctx, next) signature.

  cause Providing a middleware function that does not match Dolphin's expected `(ctx, next)` signature, possibly from an Express.js-centric background.
  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.

• ReferenceError: dolphin is not defined

  cause Attempting to use the `dolphin` client-side global object without including the server-served client library in the HTML.
  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.

Warnings

• breaking 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.
  Fix: Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import` statements for all Dolphin modules.
• gotcha 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.
  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.
• gotcha 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.
  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()`).
• gotcha 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.
  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`.
• gotcha 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.
  Fix: Consult community resources or translate the guide as needed. The code examples within the guide are self-explanatory for most developers.

Install

• npm install dolphin-server-modules npm
• yarn add dolphin-server-modules yarn
• pnpm add dolphin-server-modules pnpm

Imports

• createDolphinServer
  wrong:

  const { createDolphinServer } = require('dolphin-server-modules/server');

  correct:

  import { createDolphinServer } from 'dolphin-server-modules/server';

  The primary entry point for creating a Dolphin HTTP server. Dolphin is ESM-first.
• DolphinAuth
  wrong:

  import DolphinAuth from 'dolphin-server-modules/auth';

  correct:

  import { DolphinAuth } from 'dolphin-server-modules/auth';

  Named export for the authentication utilities. Avoid default imports.
• DolphinCRUD
  wrong:

  require('dolphin-server-modules/crud');

  correct:

  import { DolphinCRUD } from 'dolphin-server-modules/crud';

  Named export for CRUD operations, often used with ORMs like Mongoose. Ensure you're importing from the correct subpath.
• ctx
  wrong:

  (req, res) => { /* ... */ }

  correct:

  (ctx) => { /* ... */ }

  Dolphin uses a unified `ctx` (context) object for handlers, similar to Koa. While it supports Express-style middleware, direct route handlers primarily use `ctx`.

Quickstart

This quickstart demonstrates setting up a basic Dolphin web server with GET and POST routes, showcasing JSON serialization and context object usage.

import { createDolphinServer } from 'dolphin-server-modules/server';

const app = createDolphinServer();

app.get('/ping', (ctx) => {
  return { message: 'pong', version: '1.5.6' };
});

app.get('/hello/:name', (ctx) => {
  const name = ctx.params.name;
  return { greeting: `Hello, ${name}!` };
});

app.post('/data', async (ctx) => {
  const body = await ctx.req.json(); // Access raw request body
  console.log('Received data:', body);
  return { status: 'received', data: body };
});

app.listen(3000, () => console.log('🐬 Dolphin swimming on port 3000'));