Simple CORS Middleware for Micro

Common errors

• Cannot read property 'setHeader' of undefined

  cause This error can occur if the `micro-cors` middleware is not correctly applied to the `micro` handler, or if the `res` object is not correctly propagated or is somehow lost in the middleware chain. It can also happen if the `micro-cors` function is called without immediately invoking its result (e.g., `require('micro-cors')` instead of `require('micro-cors')()`).
  fix Ensure `module.exports = cors(handler)` is used and that `cors` is the result of `microCors()` or `microCors(options)`.

• TypeScript error: Cannot find module 'micro-cors' or its corresponding type declarations.

  cause The `micro-cors` package does not ship with its own TypeScript declaration files.
  fix Install the community-maintained type definitions: `npm install --save-dev @types/micro-cors` or `yarn add -D @types/micro-cors`.

• Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at [URL]. (Reason: CORS header 'Access-Control-Allow-Origin' missing).

  cause The server-side CORS configuration is either missing the `Access-Control-Allow-Origin` header, or its value does not match the origin of the requesting client. This can happen if the `origin` option in `micro-cors` is too restrictive or not set correctly.
  fix Verify the `origin` option in `micro-cors` is set to match the client's origin (e.g., `origin: 'http://localhost:3000'`) or `origin: '*'` for public APIs (but be mindful of security implications). For local development, `origin: '*'` is often used. Ensure preflight `OPTIONS` requests are handled correctly and send the necessary `Access-Control-Allow-Origin` header.

Warnings

• breaking The `micro` framework, which `micro-cors` is built upon, explicitly states it is 'not intended for use in serverless environments'. This means `micro-cors` may not be suitable for serverless functions, a common deployment target for `micro` historically.
  Fix: Consider using alternative CORS middleware solutions specifically designed for serverless platforms (e.g., AWS Lambda, Vercel Serverless Functions) if deploying to such environments. For containerized `micro` applications, ensure proper container networking and CORS configuration.
• gotcha The `0.x` stable branch has not been updated in approximately seven years, and the `1.0.0-alpha` releases from five years ago appear stalled, with open issues indicating they are not fully functional due to dependencies like Babel. This indicates the package is largely unmaintained.
  Fix: Evaluate the stability and long-term support risks before adopting. For new projects, consider more actively maintained CORS solutions or frameworks that offer built-in CORS handling.
• gotcha When `allowCredentials` is set to `true`, the `origin` option cannot be set to `'*'`. This is a standard CORS security restriction.
  Fix: If `allowCredentials` is `true`, `origin` must be set to a specific domain or a function that dynamically determines the allowed origin based on the request's `Origin` header.
• gotcha Incorrect handling of `OPTIONS` preflight requests can lead to unexpected CORS errors or unnecessary execution of your main handler. Prior to `v1` (which is in alpha), `micro-cors` only sets headers in the response and requires manual handling for preflight requests if you want to avoid triggering your main handler.
  Fix: Explicitly check `req.method === 'OPTIONS'` within your `micro` handler and send a 200 OK response with the appropriate CORS headers before proceeding to your main logic. The quickstart example demonstrates this.

Install

• npm install micro-cors npm
• yarn add micro-cors yarn
• pnpm add micro-cors pnpm

Imports

• microCors
  wrong:

  import { microCors } from 'micro-cors';

  correct:

  import microCors from 'micro-cors';
  const cors = microCors();

  The package primarily uses a default export, which is then typically invoked to create a middleware instance. CommonJS `require` is the most historically documented usage.
• cors
  wrong:

  const { cors } = require('micro-cors');

  correct:

  const cors = require('micro-cors')();

  For CommonJS, `require('micro-cors')` returns a function that should be immediately called (potentially with options) to get the middleware. Not calling it (e.g., `require('micro-cors')`) results in an uninitialized function, and trying to destructure 'cors' is incorrect.
• Options
  wrong:

  const cors = microCors({ methods: ['GET', 'POST'] });

  correct:

  const cors = microCors({ allowMethods: ['GET', 'POST'] });

  Configuration options like `allowMethods` and `allowHeaders` are passed as an object to the function returned by the default export. Refer to the GitHub README for a full list of options like `allowMethods`, `allowHeaders`, `allowCredentials`, `exposeHeaders`, `maxAge`, and `origin`.

Quickstart

Demonstrates setting up `micro-cors` with a basic `micro` handler, including options for allowed methods and explicit handling for CORS preflight requests.

import { send } from 'micro';
import microCors from 'micro-cors';

const cors = microCors({
  allowMethods: ['GET', 'POST', 'OPTIONS'],
  allowHeaders: ['X-Requested-With', 'Access-Control-Allow-Origin', 'X-HTTP-Method-Override', 'Content-Type', 'Authorization', 'Accept'],
  origin: '*'
});

const handler = async (req, res) => {
  if (req.method === 'OPTIONS') {
    // Handle preflight requests explicitly if needed
    return send(res, 200, 'ok!');
  }
  
  if (req.method === 'POST') {
    // Example POST request handling
    const data = await json(req);
    return send(res, 200, { message: 'Received POST data', data });
  }

  // Default GET response
  return send(res, 200, { message: 'Hello from micro-cors!' });
};

export default cors(handler);