Micro — Asynchronous HTTP Microservices

Common errors

• Error: Cannot find module 'micro' or its corresponding type declarations.

  cause Incorrect import path or missing type definitions for TypeScript.
  fix Ensure `micro` is installed and update your `tsconfig.json` to include `node_modules/@types` or use the correct `import` statement. For CommonJS, use `require('micro')`.

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... micro/index.js from ... not supported.

  cause Attempting to `require()` an ES Module in a CommonJS context, often occurring after upgrading to `micro` v10 without fully migrating to ESM.
  fix If your project is CommonJS, stick to `module.exports` for your handler. If using `import` for helpers, ensure your `package.json` has `"type": "module"` and your files use `.mjs` or are transpiled correctly.

• Error: Port 3000 is already in use.

  cause Another process is already listening on the default Micro port (3000) or a port specified in your configuration.
  fix Either stop the conflicting process or specify a different port for Micro using `micro -l tcp://0.0.0.0:XXXX` where XXXX is an unused port.

• unknown option `--port`

  cause Using the deprecated `--port`, `--host`, or `--unix-socket` command-line arguments from `micro` versions prior to v10.
  fix Update your `start` scripts or CLI commands to use the `--listen (-l)` option, e.g., `"start": "micro -l tcp://0.0.0.0:3000"`.

Warnings

• breaking Version 10.0.0 drops support for Node.js versions older than 16.0.0. Projects using older Node.js runtimes will fail to start or install.
  Fix: Upgrade your Node.js environment to version 16.0.0 or higher.
• breaking The command-line arguments `--port (-p)`, `--host (-h)`, and `--unix-socket (-s)` were removed in v10.0.0. Use the `--listen (-l)` option for specifying endpoint URIs.
  Fix: Replace deprecated CLI arguments with `--listen <uri>`, e.g., `micro -l tcp://0.0.0.0:3000`.
• gotcha Micro is explicitly designed for use in containerized environments and is not recommended for serverless platforms like Vercel. Vercel's built-in Serverless Function helpers often provide superior or equivalent functionality without Micro's overhead.
  Fix: For serverless deployments, utilize platform-specific helpers instead of Micro. For example, on Vercel, use `req.body` and `res.send()` directly.
• gotcha For local development, it is strongly recommended to use `micro-dev` instead of `micro`. `micro-dev` provides features like file watching, automatic restarts, and better error reporting tailored for a development workflow.
  Fix: Install `micro-dev` (`npm install --save-dev micro-dev`) and configure your `package.json` `dev` script to use it (e.g., `"dev": "micro-dev"`).
• breaking Version 10.0.0 converted `micro` to TypeScript and added ES Modules support. This might affect how you import `micro` or its helpers, especially in mixed CJS/ESM projects or older tooling.
  Fix: Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`) if using `import` statements. Review import paths and named vs. default exports.

Install

• npm install micro npm
• yarn add micro yarn
• pnpm add micro pnpm

Imports

• micro
  wrong:

  import { micro } from 'micro';

  correct:

  import micro from 'micro';

  Since v10, the `micro` server factory is a default export, typically used for programmatic server setup. CommonJS `const micro = require('micro');` also works.
• send
  wrong:

  import micro, { send } from 'micro';

  correct:

  import { send } from 'micro';

  One of the core utility functions for sending responses. Available as a named export since v10, and also via `micro.send` in CommonJS contexts.
• json
  wrong:

  const json = micro.json;

  correct:

  import { json } from 'micro';

  Utility function for parsing incoming JSON request bodies. Named export since v10; `require('micro').json` for CommonJS.
• handler function
  wrong:

  module.exports = async function handler(req, res) { /* ... */ };

  correct:

  export default async (req: IncomingMessage, res: ServerResponse) => { /* ... */ };

  When using `micro` via its CLI, your entry point should export a function. ES Module default exports are preferred since v10, but CommonJS `module.exports` is still supported for compatibility.

Quickstart

Sets up a basic Micro service that responds to GET requests and parses JSON POST bodies.

import { IncomingMessage, ServerResponse } from 'http';
import { json, send } from 'micro';

interface MyRequestBody {
  name: string;
}

export default async (req: IncomingMessage, res: ServerResponse) => {
  if (req.method === 'POST') {
    const data = (await json(req)) as MyRequestBody;
    return send(res, 200, { message: `Hello, ${data.name}!` });
  } else {
    return 'Welcome to Micro! Send a POST request with JSON { "name": "YourName" }.';
  }
};