![\"npm\"](\"https://img.shields.io/npm/v/next-api-middleware.svg?style=for-the-badge&labelColor=000000\")
\n \n \n ![\"license\"](\"https://img.shields.io/github/license/htunnicliff/next-api-middleware.svg?style=for-the-badge&labelColor=000000\")
\n \n \n ![\"tests\"](\"https://img.shields.io/github/workflow/status/htunnicliff/next-api-middleware/Test?style=for-the-badge&labelColor=000000&label=Tests\")
\n \n \n ![\"Codecov\"](\"https://img.shields.io/codecov/c/github/htunnicliff/next-api-middleware?style=for-the-badge&labelColor=000000&token=XI7G8L08TY\")
\n \n\n \n \n \n \n \n \n \n
\n\n## Introduction\n\n[Next.js API routes](https://nextjs.org/docs/api-routes/introduction) are a ridiculously fun and simple way to add backend functionality to a React app. However, when it comes time to add middleware, there is no easy way to implement it.\n\nThe official Next.js docs recommend writing functions [inside your API route handler](https://nextjs.org/docs/api-routes/api-middlewares) :thumbsdown:. This is a huge step backward compared to the clean APIs provided by Express.js or Koa.js.\n\nThis library attempts to provide minimal, clean, composable middleware patterns that are both productive and pleasant to use. :tada:\n\n## Quick Start\n\n```js\nimport { use } from \"next-api-middleware\";\n\nconst middleware = use(\n async (req, res, next) => {\n console.log(\"Do work before the request\");\n await next();\n console.log(\"Clean up\");\n },\n\n async (req, res, next) => {\n console.log(\"Do more work\");\n await next();\n console.log(\"Clean up more\");\n },\n\n (req, res, next) => {\n console.log(\"Store user in request\");\n req.locals = {\n user: {\n name: \"Alice\",\n email: \"alice@example.com\",\n },\n };\n\n return next();\n }\n);\n\nconst apiRouteHandler = async (req, res) => {\n const { name } = req.locals.user;\n\n res.status(200);\n res.send(`Hello, ${name}!`);\n};\n\nexport default middleware(apiRouteHandler);\n\n/**\n * Console output:\n *\n * Do work before the request\n * Do more work\n * Store user in request\n * Clean up more\n * Clean up\n */\n```\n\n## Usage\n\n### :one: Create Middleware Functions\n\n```ts\nimport type { Middleware } from \"next-api-middleware\";\n\nexport const addRequestUUID: Middleware = (req, res, next) => {\n res.setHeader(\"X-Response-ID\", uuid());\n return next();\n};\n\nexport const addRequestTiming: Middleware = async (req, res, next) => {\n res.setHeader(\"X-Timing-Start\", new Date().getTime());\n await next();\n res.setHeader(\"X-Timing-End\", new Date().getTime());\n};\n\nexport const logErrorsWithACME: Middleware = async (req, res, next) => {\n try {\n await next();\n } catch (error) {\n Acme.captureException(error);\n res.status(500);\n res.json({ error: error.message });\n }\n};\n```\n\n### :two: Compose Reusable Groups\n\n```js\nimport { use } from \"next-api-middleware\";\nimport {\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n} from \"../helpers\";\nimport { connectDatabase, loadUsers } from \"../users\";\n\nexport const authMiddleware = use(\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n connectDatabase,\n loadUsers\n);\n\nexport const guestMiddleware = use(\n isProduction ? [addRequestTiming, logErrorsWithACME] : [],\n addRequestUUID\n);\n\nexport const otherMiddleware = use(\n [addRequestUUID, connectDatabase, loadUsers],\n [addRequestTiming, logErrorsWithACME]\n);\n```\n\nThe `use` method creates a higher order function that applies middleware to an API route. `use` accepts a list of values that evaluate to middleware functions. It also accepts arrays of middleware functions, which are flattened at runtime (order is preserved).\n\nAnother available method for grouping middleware is `label`. Here's how it works:\n\n```ts\nimport { label } from \"next-api-middleware\";\nimport {\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n} from \"../helpers\";\n\nconst middleware = label(\n timing: addRequestTiming,\n logErrors: logErrorsWithACME,\n uuids: addRequestUUID,\n all: [addRequestTiming, logErrorsWithACME, addRequestUUID]\n);\n\nconst apiRouteHandler = async (req, res) => {\n const { name } = req.locals.user;\n\n res.status(200);\n res.send(`Hello, ${name}!`);\n};\n\n// Invokes `addRequestTiming` and `logErrorsWithACME`\nexport default middleware([\"timing\", \"logErrors\"])(apiRouteHandler);\n```\n\nUsing `label` creates a middleware group that, by default, doesn't invoke any middleware. Instead, it allows choosing specific middleware by supplying labels as arguments in the API route.\n\n### :three: Apply Middleware to API Routes\n\nTo apply a middleware group to an API route, just import it and provide the API route handler as an argument:\n\n```js\nimport { withGuestMiddleware } from \"../../middleware/groups\";\n\nconst apiHandler = async (req, res) => {\n res.status(200);\n res.send(\"Hello, world!\");\n};\n\nexport default withGuestMiddleware(apiHandler);\n```\n\n## Advanced\n\n### Middleware Factories\n\nSince `use` accepts values that evaluate to middleware functions, this provides the opportunity to create custom middleware factories.\n\nHere's an example of a factory that generates a middleware function to only allow requests with a given HTTP method:\n\n```ts\nimport { use, Middleware } from \"next-api-middleware\";\n\nconst httpMethod = (\n allowedHttpMethod: \"GET\" | \"POST\" | \"PATCH\"\n): Middleware => {\n return async function (req, res, next) {\n if (req.method === allowedHttpMethod || req.method == \"OPTIONS\") {\n await next();\n } else {\n res.status(404);\n res.end();\n }\n };\n};\n\nexport const withAuthMiddleware = use(\n httpMethod(\"POST\"),\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID\n);\n```\n","readmeFilename":"README.md","gitHead":"f89921ccef6f9869cf76454bcfa4530f30d1c587","bugs":{"url":"https://github.com/htunnicliff/next-api-middleware/issues"},"homepage":"https://github.com/htunnicliff/next-api-middleware#readme","_id":"next-api-middleware@0.7.0-canary.0","_nodeVersion":"15.2.1","_npmVersion":"7.0.8","dist":{"integrity":"sha512-MF+D5gOnubSuE7wjv/MgpyUL7kHCHa2cYzdNnxEgHt0+AtQ0u/76tFhbObU+/o8kApOgRyjcaZGk+UMqm3DYcw==","shasum":"4fee6e7edebbe3f048ed41fe5ae47172d5e7e42f","tarball":"https://registry.npmjs.org/next-api-middleware/-/next-api-middleware-0.7.0-canary.0.tgz","fileCount":5,"unpackedSize":12735,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJgJtjuCRA9TVsSAnZWagAA7a0P/0qCNJk24K66Jfe1kVSP\nP8St0zZZl9ZZWMEZ9z89YEGBcjIq45rJ+BNw4o8oYEUYhGBbwxJqdOKE5NXJ\nnGr8ggLtFOs5Qhp5gAG4bGwrzJooxXbYJmwuaXHAO+1MxMkfB6j9OhYrvYGW\nR+3X+sRlg30hQFi0/yI1VH6YRPGPW+LArzkliVyc4MYEQ0Gc9ip5oE5oRBcV\n/FFa4Cxtr98G4oL4Fr38Ripn7/3m1VtkzdqwBAZ/lsjlZZzlfazksE7XGriX\nmj2WgoYmfxK0gytQ9nBURB5BQj+BMycw1IGnruwXYtvYEr9O70hSFKFi4y5K\nedGKSvWSJiQOUl1VWQZZQvHGDHjrrYmv5uBo5TFKDu9om0ARR3lHnizMcSID\nw0EykNP1wIn7R2Rn2mep7t9YKr21iQAfLRGosVZICz46GE6z+yN8O9v8Ok+c\nbw5YNsr1HkNDZohR7lMvUXX/SGmT55aIjwma9u8tzXtHDrjuMWP1ApRTzX+6\neeZ8+X0cEc7Wefv+/H0l5OqiGecIkPb2tgM2yJ8wrQp6y64E9TAyS/xWPkh4\nN6e34BE8c0Dl3wRnU01YHphGAsbIH3AXWyxBVUlFT6FoEfcohyn5wOpqqw3W\n9YY5lZuTJ6T4EFX6o1UfZJS8Ab1eR2MPxa3ZHG713sSccYsRhNcgce9LIS0r\nhZb0\r\n=rE7w\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIGxhHtadnFvJjfkrK597O9w05pVONX5YArxktA5ragkmAiEAjyO5TzFHRBvdSweTB+h8FzbIP38MOOqiQWi5lptEZug="}]},"_npmUser":{"name":"htunnicliff","email":"me@huntertunnicliff.com"},"directories":{},"maintainers":[{"name":"htunnicliff","email":"me@huntertunnicliff.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/next-api-middleware_0.7.0-canary.0_1613158637957_0.8807572127750061"},"_hasShrinkwrap":false},"0.7.0-canary.1":{"name":"next-api-middleware","version":"0.7.0-canary.1","description":"Middleware solution for Next.js API routes","repository":{"type":"git","url":"git+ssh://git@github.com/htunnicliff/next-api-middleware.git"},"author":{"name":"Hunter Tunnicliff","email":"htunnicliff@hey.com"},"license":"MIT","main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">= 12.20"},"keywords":["next","next.js","middleware","API routes","express"],"scripts":{"build":"tsc","test":"jest","preversion":"npm test","version":"rm -rf dist && npm run build"},"devDependencies":{"@babel/core":"^7.12.9","@babel/preset-env":"^7.12.7","@babel/preset-typescript":"^7.12.7","@types/cors":"^2.8.10","@types/jest":"^26.0.15","@types/node":"^14.14.10","@types/react":"^17.0.0","@types/react-dom":"^17.0.0","babel-jest":"^26.6.3","cors":"^2.8.5","jest":"^26.6.3","next":"^10.0.3","ts-node":"^9.0.0","typescript":"^4.1.2"},"gitHead":"c2e85593f86e1c8187988954cb6c95cf5f5a6e0d","bugs":{"url":"https://github.com/htunnicliff/next-api-middleware/issues"},"homepage":"https://github.com/htunnicliff/next-api-middleware#readme","_id":"next-api-middleware@0.7.0-canary.1","_nodeVersion":"15.2.1","_npmVersion":"7.0.8","dist":{"integrity":"sha512-xrDAHiRG5NZfj9gLUE0Fi8iCJMPNdGT2QT3GSAvYs0SbWI145Vno6eUAp0sP6jxfqXUAlv9pdvioBCQ+6u8MoA==","shasum":"83c3b4509df200a59221a8e83b7a98ae3192f4ad","tarball":"https://registry.npmjs.org/next-api-middleware/-/next-api-middleware-0.7.0-canary.1.tgz","fileCount":6,"unpackedSize":15203,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJgMAMkCRA9TVsSAnZWagAA848P/RmvBBbsKToYxW0u3+fb\nYYzBiymkzPOZEj2B79G+fPd3d9Nx4UnrS2A7CqyRsKd6+hjS2oKx67kkYkr2\nane4jSslNZUvDaY83tk/cmOB67pGDrtcwpgVbx9gpbPdStJ83OHWqOu+BkcN\nSDZiJbej+Oa3R1Ynby7Cn1e0wkgTXegg9/5c0nyP932Dn1Ahs38wQgOzwmFv\nREXp6Xb5uiZLYNJZlhG4m8ewHZ1cm5/rugp5rVWEK/nf1w4FeXNNNaGKnF5Q\nDdWn5bV6iPg1alw0cYxZ12al23yb3cs9ZFxzJF6kleLPkQtowQA9qTT7XBU5\nyTVFfuuvPQyAfwrcp2T6wiZbjpVUd5qSaCj00KJZdp9ourXR5mc2YrpHlKD0\nc1nn9QXpCwd7EBpX+qqgZILdPRONOU8NwhtebGy13Pw/bUyhp0viUn+BSeid\nCGnHvUMRUp7mchLygLjIxF2kR6aL2IGI8JHrzJrupaPYRKAdlac0dNJjjQQc\n+F1xlccc3vtJ1NKNhp/A1Onp6ANE/vRoiEYSDyCh9TgWi1jkxkYaLRzGRkpT\nfDTvrrRbi+Cnves7DrLq55qMmty0cQIAb4iJfmQq+x1mmtffGQcHuTOnjJ7A\nIq9A4XE7jZ7DHr2EFRwBwtgUTieXj4Ql/rGIA35v46loqklOzcEKTdfVXmK1\n+cy8\r\n=p0dg\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCiQltAeJY53pWLxOS350NAkrZeFHrxnKmm7d5o4XNz9AIhAMlV9V+rIspruWT9F7h3/ge+w7ziL/wXWiQyVQ0lkBVH"}]},"_npmUser":{"name":"htunnicliff","email":"me@huntertunnicliff.com"},"directories":{},"maintainers":[{"name":"htunnicliff","email":"me@huntertunnicliff.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/next-api-middleware_0.7.0-canary.1_1613759267609_0.7968019666837376"},"_hasShrinkwrap":false},"0.6.1":{"name":"next-api-middleware","version":"0.6.1","description":"Middleware solution for Next.js API routes","repository":{"type":"git","url":"git+ssh://git@github.com/htunnicliff/next-api-middleware.git"},"author":{"name":"Hunter Tunnicliff","email":"htunnicliff@hey.com"},"license":"MIT","main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">= 12.x"},"keywords":["next","next.js","middleware","API routes","koa"],"scripts":{"build":"tsc","test":"jest","prepare":"rm -rf dist && npm run build"},"devDependencies":{"@babel/core":"^7.12.9","@babel/preset-env":"^7.12.7","@babel/preset-typescript":"^7.12.7","@types/jest":"^26.0.15","@types/node":"^14.14.10","@types/react":"^17.0.0","@types/react-dom":"^17.0.0","babel-jest":"^26.6.3","jest":"^26.6.3","next":"^10.0.3","ts-node":"^9.0.0","typescript":"^4.1.2"},"gitHead":"54c108e49b0d97b667083bed7c440956ca9b1868","bugs":{"url":"https://github.com/htunnicliff/next-api-middleware/issues"},"homepage":"https://github.com/htunnicliff/next-api-middleware#readme","_id":"next-api-middleware@0.6.1","_nodeVersion":"15.2.1","_npmVersion":"7.0.8","dist":{"integrity":"sha512-iwsHjyTinZSkUFhEXq6TSJmOs8xNI/EiRXWFbwAwRv7XacmL1BN3Z/Xd1JXSSxvqxoAjA9hTEP6rGb5n3/veZQ==","shasum":"20dabb1d00522da76fbcc5a568034ac838794743","tarball":"https://registry.npmjs.org/next-api-middleware/-/next-api-middleware-0.6.1.tgz","fileCount":5,"unpackedSize":12155,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJgMAPQCRA9TVsSAnZWagAAee0P+wZv/vo+0yHx7YLIBB5Y\n6NLIR7J6pv81YtbMIjRlSjVw3MKZ5M6pcWcRJaFGgbZdjeJDzNz4aicg7HQL\n4iRHKxOpeJG5T11GIuXZWpQmsDgyBSt/amXRLr4dluxq2+62fsGjKGKzl+iK\nTUtSVuYJkSSuQC0JzTmt6whs39ifm7C+Ch1GeoeO/GQJgDJhB78XCcIouyoM\nURg8yHrONULkB6fWPOs/EAm/Uc1xxMaOMpiZcC/Eh0lNLAsyS8DL4fUqtYbC\nXY28jA0mhvSBn4iz479NWOyZ1ftKVp6ZniipdY8unMM7oDChlAhilYd7ifoC\nt+3i1Plm8FFStgyfLs7Nx30Idpqm0vNdlTgl2+OepuKuobaDQLPAB5DFsm7Q\n9eEPNDzQkv5eyEEu9bzy4SA1woiFoLmbCOmO62hnJAzbvhpxb3p7C3CDAqqu\n79xNx3eEq0LyyBOic7fcVSx6LhJj5th8f/Urg6lh7zsbokYpmN4mfmQg8etV\nIAFnFpbXqDtLyJZ3a43dO9MeR1TxHVctDxC6LBOUkv/LAw7C5TdEX8VSpV1P\nb1oGALogjk+eZseDqTu7YgNG36h0Qsk/8Vpy/BQPee8GwS4pwONeJLwvB8Hv\n4g16xW2afYvh4TbltsmOiyzXV7GLTTrpD6mF42cd+0/u5TX3xDyhEfe6U23x\nzTKW\r\n=eGAs\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIBO0KFn3JmW4/cc4bx4Wu5Hnok+kgIKyZZzlxxy+eJZQAiEAgxQeSZJdAmapvrdn5tRMdMtKJX4D40Pv+Pq2yFX94Rs="}]},"_npmUser":{"name":"htunnicliff","email":"me@huntertunnicliff.com"},"directories":{},"maintainers":[{"name":"htunnicliff","email":"me@huntertunnicliff.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/next-api-middleware_0.6.1_1613759440193_0.7180650945963094"},"_hasShrinkwrap":false},"0.7.0":{"name":"next-api-middleware","version":"0.7.0","description":"Middleware solution for Next.js API routes","repository":{"type":"git","url":"git+ssh://git@github.com/htunnicliff/next-api-middleware.git"},"author":{"name":"Hunter Tunnicliff","email":"htunnicliff@hey.com"},"license":"MIT","main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">= 12.20"},"keywords":["next","next.js","middleware","API routes","express"],"scripts":{"build":"tsc","test":"jest","preversion":"npm test","version":"rm -rf dist && npm run build"},"devDependencies":{"@babel/core":"^7.12.9","@babel/preset-env":"^7.12.7","@babel/preset-typescript":"^7.12.7","@types/cors":"^2.8.10","@types/jest":"^26.0.15","@types/node":"^14.14.10","@types/react":"^17.0.0","@types/react-dom":"^17.0.0","babel-jest":"^26.6.3","cors":"^2.8.5","jest":"^26.6.3","next":"^10.0.3","ts-node":"^9.0.0","typescript":"^4.1.2"},"gitHead":"2636ba7cbfa4e392bf3911ef99a909de79494e9b","bugs":{"url":"https://github.com/htunnicliff/next-api-middleware/issues"},"homepage":"https://github.com/htunnicliff/next-api-middleware#readme","_id":"next-api-middleware@0.7.0","_nodeVersion":"15.2.1","_npmVersion":"7.0.8","dist":{"integrity":"sha512-3DmnBwSl85AFtzvgZJUu2oTKOVzh8D8S84LwH8xxpnuBrkHfIFvsZ1CtOnSKDEUTyTVvs05641lOzlesP82bvQ==","shasum":"bb183f95906ac9a9cd7f9c1b3e600582602a72b9","tarball":"https://registry.npmjs.org/next-api-middleware/-/next-api-middleware-0.7.0.tgz","fileCount":6,"unpackedSize":17291,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJgNtuKCRA9TVsSAnZWagAA13EP/iBTiHQcopHe/b6outHu\nDn3siVgg5J+l7x1qEgk7VBc9U5z4B5K4zczLHcuOYOrsecOHB+QIN8jXb6yK\nxkrLdu+53TciDuMJJBkGG4KL5ubmKoDYjXxgMdAMPd0yML3xL1Z+lxaaih9x\nnfnYEmwjcShPEudHwZ0D4W0YI9nyUgDS0MFJVXgctbpvsl2eQIhpP19HEYeP\njvg9K9VZ7syt4Ve35DlTszgzqmbFGXQMwGQOlKIj0dUSFu7/Vtix3AlPduUc\nSMA2mYbrTpYNNoMP1B3uaganA/h3GX29w5M3RJvUfF19kmHdtBSMqHSxzBx5\ndz6VdXbqEHKDxj+oqpGo1eZI9XXGuvRFd5tw9IRmBInM7UzOdoh5tR7u/2PM\nyjnh8mM9ylWhTNeIXOCo37eVvbA75i0mZGf6yDIJIZeYm5Du5sVOYCkjPZiW\nWJxowOqtJMZG4mapq4AuJNfbLT1utohgWZ+edUsehAbMgFoufb8xkOTsnz6a\nEIjLkI5dw8H3Tx0KB0P8bJNV6WQWCaKsDE1+9armZTlCpP5MDUZtSwksU17Y\nxy8F9PopG1DwXcn8hB3IiIO6h0gbOU8/Yr/NO4p65gRYBb67UPzmtq4nsFZD\n8BSaou0liSa0frrY72qMATNvE2mCVHsTmVJFYER5EnsXAXOWwof3ZiuZF4UQ\nkJhB\r\n=njVk\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCvGLFs/K4SLhf20SKHohbdmvaNOAeBOv3K5ECu/vwE3gIhAM/PlviGy6me39O6J0ToZlAKhxV3SavzCUBx9tShCOw1"}]},"_npmUser":{"name":"htunnicliff","email":"me@huntertunnicliff.com"},"directories":{},"maintainers":[{"name":"htunnicliff","email":"me@huntertunnicliff.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/next-api-middleware_0.7.0_1614207881630_0.5513378191345468"},"_hasShrinkwrap":false},"0.7.1":{"name":"next-api-middleware","version":"0.7.1","description":"Middleware solution for Next.js API routes","repository":{"type":"git","url":"git+ssh://git@github.com/htunnicliff/next-api-middleware.git"},"author":{"name":"Hunter Tunnicliff","email":"htunnicliff@hey.com"},"license":"MIT","main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">= 12.20"},"keywords":["next","next.js","middleware","API routes","express"],"scripts":{"build":"tsc","test":"jest","preversion":"npm test","version":"rm -rf dist && npm run build"},"devDependencies":{"@babel/core":"^7.13.15","@babel/preset-env":"^7.13.15","@babel/preset-typescript":"^7.13.0","@types/cors":"^2.8.10","@types/jest":"^26.0.22","@types/node":"^14.14.37","@types/react":"^17.0.3","@types/react-dom":"^17.0.3","babel-jest":"^26.6.3","cors":"^2.8.5","jest":"^26.6.3","next":"^10.1.3","ts-node":"^9.1.1","typescript":"^4.2.4"},"gitHead":"1b9cc645c161386864a04d5e33b8787f81df03ef","bugs":{"url":"https://github.com/htunnicliff/next-api-middleware/issues"},"homepage":"https://github.com/htunnicliff/next-api-middleware#readme","_id":"next-api-middleware@0.7.1","_nodeVersion":"15.2.1","_npmVersion":"7.0.8","dist":{"integrity":"sha512-HdAFPgOJcunHV8t+zQoGoXgpPGQkxXq+R7yFCvzt4kRSay5Y0/UVaCNRb0VWQcIMd30mp1CbWOjM/6Z0eFNuAw==","shasum":"cdf887f8f1cc216401799eeeba768286bd049788","tarball":"https://registry.npmjs.org/next-api-middleware/-/next-api-middleware-0.7.1.tgz","fileCount":6,"unpackedSize":17293,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJgdNFmCRA9TVsSAnZWagAAvyUQAIP6P0Te0cVElCfqdo/g\nizblCAIsGFJ+ocH1Y6lEikmlHnT7VgUE8MeyBjlnEtgwIJupaC7WDyKVPdKE\nXuEPIsuBO7+T3NR4qpKJaUL7J6qd2+uTA3C6eSHMtJZgdRO6JjT4pA1P/++2\nViK/QCCDLAulOtE+I+hg2QY28zmCdhTjycYgdWhrVjPMwgGHlFhHbCfbSAhz\nXLrxoiSdFr4vuaSz2as+JLkv64FNHMfatexYi9SoRU1xX6GvX28jybCkmoR3\n3XBLfdpIYWzB7u6IoFV9KwreihznzgrL5CoQSXzo7qhFyg4zxJlBRafp7V/v\neuaf4jF3SAapp/Fq6sRz6d+EgP+Q/uh1K0tZ/A7v0X43HmiKjCjCSqOqGKC/\nTDKmuGwa1cxde5LQt9GkV57KeY1KU64ydYViB+Cscou6M55cqHza+yOdAQq8\nEwWFMfxY4UxH1C6FWMwJ57TdshsURYMDQYhi8f5sJhLX3uO7ygfDYgouShl4\nSFdG62AHfoNHdJjbTmbC4UzdPFUYTqc7PtUBHNdqNsDKmbG3XSHsRLDTYCMn\nfNuaS7xuKkBMYdVLr/IYYl0BoTeIap13xf9TuKRuwqKhN2SrU2zX1E4vu+ks\ndeelzQYlK6143WOpvhOqE7HgjkD3piWRuRJVuxG4RaPC8uZzl2UAdTGTWA5r\nCk1R\r\n=jGO9\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCICQaLBl2B8kILzVIVye1KkgXLtD1HvyP9xgOCnc4+MPZAiBF/VVBN4LOUu9UiMudcY4a/rAAD1OvX+/qf0/67Rl/WA=="}]},"_npmUser":{"name":"htunnicliff","email":"me@huntertunnicliff.com"},"directories":{},"maintainers":[{"name":"htunnicliff","email":"me@huntertunnicliff.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/next-api-middleware_0.7.1_1618268517551_0.7448854666857891"},"_hasShrinkwrap":false},"1.0.0-canary.0":{"name":"next-api-middleware","version":"1.0.0-canary.0","description":"Middleware solution for Next.js API routes","repository":{"type":"git","url":"git@github.com:htunnicliff/next-api-middleware.git"},"author":{"name":"Hunter Tunnicliff","email":"htunnicliff@hey.com"},"license":"MIT","main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">= 12.20"},"keywords":["next","next.js","middleware","API routes","express"],"scripts":{"build":"tsc","test":"jest","preversion":"npm test","version":"rm -rf dist && npm run build"},"devDependencies":{"@babel/core":"^7.13.15","@babel/preset-env":"^7.13.15","@babel/preset-typescript":"^7.13.0","@types/cors":"^2.8.10","@types/jest":"^26.0.24","@types/node":"^15.0.1","@types/react":"^17.0.3","@types/react-dom":"^17.0.3","babel-jest":"^27.0.2","cors":"^2.8.5","jest":"^27.0.4","jest-extended":"^0.11.5","next":"^10.1.3","ts-node":"^10.0.0","typescript":"^4.2.4"},"dependencies":{},"readmeFilename":"README.md","readme":"# Next.js API Middleware\n\n
\n \n \n \n \n \n \n \n
\n\n## Introduction\n\n[Next.js API routes](https://nextjs.org/docs/api-routes/introduction) are a ridiculously fun and simple way to add backend functionality to a React app. However, when it comes time to add middleware, there is no easy way to implement it.\n\nThe official Next.js docs recommend writing functions [inside your API route handler](https://nextjs.org/docs/api-routes/api-middlewares) :thumbsdown:. This is a huge step backward compared to the clean APIs provided by Express.js or Koa.js.\n\nThis library attempts to provide minimal, clean, composable middleware patterns that are both productive and pleasant to use. :tada:\n\n## Quick Start\n\n```js\nimport { use } from \"next-api-middleware\";\nimport cors from \"cors\";\n\n// Create a wrapper function that executes middleware\n// before and after an API route request\nconst withMiddleware = use(\n async (req, res, next) => {\n console.log(\"Do work before the request\");\n await next();\n console.log(\"Clean up\");\n },\n async (req, res, next) => {\n console.log(\"Do more work\");\n await next();\n console.log(\"Clean up more\");\n },\n cors(), // <---- Invoke Express/Connect middleware like any other middleware\n async (req, res, next) => {\n console.log(\"Store user in request\");\n req.locals = {\n user: {\n name: \"Alice\",\n email: \"alice@example.com\",\n },\n };\n\n await next();\n }\n);\n\n// Create a normal Next.js API route handler\nconst apiRouteHandler = async (req, res) => {\n const { name } = req.locals.user;\n\n res.status(200);\n res.send(`Hello, ${name}!`);\n};\n\n// Export the route handler wrapped inside the middleware function\nexport default withMiddleware(apiRouteHandler);\n\n/**\n * Console output:\n *\n * Do work before the request\n * Do more work\n * cors\n * Store user in request\n * Clean up more\n * Clean up\n */\n```\n\n## Usage\n\n### Writing Async Middleware\n\n```ts\nimport type { NextMiddleware } from \"next-api-middleware\";\n\n// Middleware that does work before a request\nexport const addRequestUUID: NextMiddleware = async (req, res, next) => {\n // Set a custom header\n res.setHeader(\"X-Response-ID\", uuid());\n\n // Execute the remaining middleware\n await next();\n};\n\n// Middleware that does work before *and* after a request\nexport const addRequestTiming: NextMiddleware = async (req, res, next) => {\n // Set a custom header before other middleware and the route handler\n res.setHeader(\"X-Timing-Start\", new Date().getTime());\n\n // Execute the remaining middleware\n await next();\n\n // Set a custom header\n res.setHeader(\"X-Timing-End\", new Date().getTime());\n};\n\n// Middleware that catches errors that occur in remaining middleware\n// and the request\nexport const logErrorsWithACME: NextMiddleware = async (req, res, next) => {\n try {\n // Catch any errors that are thrown in remaining\n // middleware and the API route handler\n await next();\n } catch (error) {\n Acme.captureException(error);\n res.status(500);\n res.json({ error: error.message });\n }\n};\n```\n\n### Composing Middleware Groups\n\n```js\nimport { use } from \"next-api-middleware\";\nimport {\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n} from \"../helpers\";\nimport { connectDatabase, loadUsers } from \"../users\";\n\n// Create a middleware wrapper to be used on API routes\n// that need authentication\nexport const withAuthMiddleware = use(\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n connectDatabase,\n loadUsers\n);\n\n// Create a middleware wrapper to be used on API routes\n// that are only used by guests\nexport const withGuestMiddleware = use(\n isProduction ? [addRequestTiming, logErrorsWithACME] : [],\n addRequestUUID\n);\n\n// Create a middleware wrapper using arrays of middleware\n// functions; these are flattened and executed in the order\n// in which they are provided\nexport const withXYZMiddleware = use(\n [addRequestUUID, connectDatabase, loadUsers],\n [addRequestTiming, logErrorsWithACME]\n);\n```\n\nThe `use` method creates a higher order function that applies middleware to an API route. `use` accepts a list of values that evaluate to middleware functions. It also accepts arrays of middleware functions, which are flattened at runtime (order is preserved).\n\nAnother available method for grouping middleware is `label`. Here's how it works:\n\n```ts\nimport { label } from \"next-api-middleware\";\nimport {\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n} from \"../helpers\";\n\n// Create a middleware wrapper that imports middleware and\n// assigns friendly labels\nconst withMiddleware = label({\n timing: addRequestTiming,\n logErrors: logErrorsWithACME,\n uuids: addRequestUUID,\n all: [addRequestTiming, logErrorsWithACME, addRequestUUID],\n});\n\nconst apiRouteHandler = async (req, res) => {\n const { name } = req.locals.user;\n\n res.status(200);\n res.send(`Hello, ${name}!`);\n};\n\n// Only invoke `addRequestTiming` and `logErrorsWithACME`, using their\n// friendly labels\nexport default withMiddleware(\"timing\", \"logErrors\")(apiRouteHandler);\n```\n\nUsing `label` creates a middleware group that, by default, doesn't invoke any middleware. Instead, it allows choosing specific middleware by supplying labels as arguments in the API route.\n\n## Advanced\n\n### Middleware Factories\n\nSince `use` accepts values that evaluate to middleware functions, this provides the opportunity to create custom middleware factories.\n\nHere's an example of a factory that generates a middleware function to only allow requests with a given HTTP method:\n\n```ts\nimport { use, NextMiddleware } from \"next-api-middleware\";\n\nconst httpMethod = (\n allowedHttpMethod: \"GET\" | \"POST\" | \"PATCH\"\n): NextMiddleware => {\n return async function (req, res, next) {\n if (req.method === allowedHttpMethod || req.method == \"OPTIONS\") {\n await next();\n } else {\n res.status(404);\n res.end();\n }\n };\n};\n\nexport const withAuthMiddleware = use(\n httpMethod(\"POST\"),\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID\n);\n```\n\n### Middleware Types\n\n`next-api-middleware` supports two middleware signatures, `NextMiddleware` and `ExpressMiddleware`.\n\n#### `NextMiddleware` (preferred)\n\n`NextMiddleware` is inspired by the asyncronous middleware style popularized by Koa.js. Prefer this style when writing your own middleware.\n\n```ts\ninterface NextMiddleware {\n (\n req: NextApiRequest,\n res: NextApiResponse,\n next: () => Promise \n \n \n\n## Introduction\n\n[Next.js API routes](https://nextjs.org/docs/api-routes/introduction) are a ridiculously fun and simple way to add backend functionality to a React app. However, when it comes time to add middleware, there is no easy way to implement it.\n\nThe official Next.js docs recommend writing functions [inside your API route handler](https://nextjs.org/docs/api-routes/api-middlewares) :thumbsdown:. This is a huge step backward compared to the clean APIs provided by Express.js or Koa.js.\n\nThis library attempts to provide minimal, clean, composable middleware patterns that are both productive and pleasant to use. :tada:\n\n## Quick Start\n\n```js\nimport { use } from \"next-api-middleware\";\nimport cors from \"cors\";\n\n// Create a wrapper function that executes middleware\n// before and after an API route request\nconst withMiddleware = use(\n async (req, res, next) => {\n console.log(\"Do work before the request\");\n await next();\n console.log(\"Clean up\");\n },\n async (req, res, next) => {\n console.log(\"Do more work\");\n await next();\n console.log(\"Clean up more\");\n },\n cors(), // <---- Invoke Express/Connect middleware like any other middleware\n async (req, res, next) => {\n console.log(\"Store user in request\");\n req.locals = {\n user: {\n name: \"Alice\",\n email: \"alice@example.com\",\n },\n };\n\n await next();\n }\n);\n\n// Create a normal Next.js API route handler\nconst apiRouteHandler = async (req, res) => {\n const { name } = req.locals.user;\n\n res.status(200);\n res.send(`Hello, ${name}!`);\n};\n\n// Export the route handler wrapped inside the middleware function\nexport default withMiddleware(apiRouteHandler);\n\n/**\n * Console output:\n *\n * Do work before the request\n * Do more work\n * cors\n * Store user in request\n * Clean up more\n * Clean up\n */\n```\n\n## Usage\n\n### Writing Async Middleware\n\n```ts\nimport type { NextMiddleware } from \"next-api-middleware\";\n\n// Middleware that does work before a request\nexport const addRequestUUID: NextMiddleware = async (req, res, next) => {\n // Set a custom header\n res.setHeader(\"X-Response-ID\", uuid());\n\n // Execute the remaining middleware\n await next();\n};\n\n// Middleware that does work before *and* after a request\nexport const addRequestTiming: NextMiddleware = async (req, res, next) => {\n // Set a custom header before other middleware and the route handler\n res.setHeader(\"X-Timing-Start\", new Date().getTime());\n\n // Execute the remaining middleware\n await next();\n\n // Set a custom header\n res.setHeader(\"X-Timing-End\", new Date().getTime());\n};\n\n// Middleware that catches errors that occur in remaining middleware\n// and the request\nexport const logErrorsWithACME: NextMiddleware = async (req, res, next) => {\n try {\n // Catch any errors that are thrown in remaining\n // middleware and the API route handler\n await next();\n } catch (error) {\n Acme.captureException(error);\n res.status(500);\n res.json({ error: error.message });\n }\n};\n```\n\n### Composing Middleware Groups\n\n```js\nimport { use } from \"next-api-middleware\";\nimport {\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n} from \"../helpers\";\nimport { connectDatabase, loadUsers } from \"../users\";\n\n// Create a middleware wrapper to be used on API routes\n// that need authentication\nexport const withAuthMiddleware = use(\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n connectDatabase,\n loadUsers\n);\n\n// Create a middleware wrapper to be used on API routes\n// that are only used by guests\nexport const withGuestMiddleware = use(\n isProduction ? [addRequestTiming, logErrorsWithACME] : [],\n addRequestUUID\n);\n\n// Create a middleware wrapper using arrays of middleware\n// functions; these are flattened and executed in the order\n// in which they are provided\nexport const withXYZMiddleware = use(\n [addRequestUUID, connectDatabase, loadUsers],\n [addRequestTiming, logErrorsWithACME]\n);\n```\n\nThe `use` method creates a higher order function that applies middleware to an API route. `use` accepts a list of values that evaluate to middleware functions. It also accepts arrays of middleware functions, which are flattened at runtime (order is preserved).\n\nAnother available method for grouping middleware is `label`. Here's how it works:\n\n```ts\nimport { label } from \"next-api-middleware\";\nimport {\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n} from \"../helpers\";\n\n// Create a middleware wrapper that imports middleware and\n// assigns friendly labels\nconst withMiddleware = label({\n timing: addRequestTiming,\n logErrors: logErrorsWithACME,\n uuids: addRequestUUID,\n all: [addRequestTiming, logErrorsWithACME, addRequestUUID],\n});\n\nconst apiRouteHandler = async (req, res) => {\n const { name } = req.locals.user;\n\n res.status(200);\n res.send(`Hello, ${name}!`);\n};\n\n// Only invoke `addRequestTiming` and `logErrorsWithACME`, using their\n// friendly labels\nexport default withMiddleware(\"timing\", \"logErrors\")(apiRouteHandler);\n```\n\nUsing `label` creates a middleware group that, by default, doesn't invoke any middleware. Instead, it allows choosing specific middleware by supplying labels as arguments in the API route.\n\n## Advanced\n\n### Middleware Factories\n\nSince `use` accepts values that evaluate to middleware functions, this provides the opportunity to create custom middleware factories.\n\nHere's an example of a factory that generates a middleware function to only allow requests with a given HTTP method:\n\n```ts\nimport { use, NextMiddleware } from \"next-api-middleware\";\n\nconst httpMethod = (\n allowedHttpMethod: \"GET\" | \"POST\" | \"PATCH\"\n): NextMiddleware => {\n return async function (req, res, next) {\n if (req.method === allowedHttpMethod || req.method == \"OPTIONS\") {\n await next();\n } else {\n res.status(404);\n res.end();\n }\n };\n};\n\nexport const withAuthMiddleware = use(\n httpMethod(\"POST\"),\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID\n);\n```\n\n### Middleware Types\n\n`next-api-middleware` supports two middleware signatures, `NextMiddleware` and `ExpressMiddleware`.\n\n#### `NextMiddleware` (preferred)\n\n`NextMiddleware` is inspired by the asyncronous middleware style popularized by Koa.js. Prefer this style when writing your own middleware.\n\n```ts\ninterface NextMiddleware {\n (\n req: NextApiRequest,\n res: NextApiResponse,\n next: () => Promise \n \n\n## Introduction\n\n[Next.js API routes](https://nextjs.org/docs/api-routes/introduction) are a ridiculously fun and simple way to add backend functionality to a React app. However, when it comes time to add middleware, there is no easy way to implement it.\n\nThe official Next.js docs recommend writing functions [inside your API route handler](https://nextjs.org/docs/api-routes/api-middlewares) :thumbsdown:. This is a huge step backward compared to the clean APIs provided by Express.js or Koa.js.\n\nThis library attempts to provide minimal, clean, composable middleware patterns that are both productive and pleasant to use. :tada:\n\n## Quick Start\n\n```js\nimport { use } from \"next-api-middleware\";\nimport cors from \"cors\";\n\n// Create a wrapper function that executes middleware\n// before and after an API route request\nconst withMiddleware = use(\n async (req, res, next) => {\n console.log(\"Do work before the request\");\n await next();\n console.log(\"Clean up\");\n },\n async (req, res, next) => {\n console.log(\"Do more work\");\n await next();\n console.log(\"Clean up more\");\n },\n cors(), // <---- Invoke Express/Connect middleware like any other middleware\n async (req, res, next) => {\n console.log(\"Store user in request\");\n req.locals = {\n user: {\n name: \"Alice\",\n email: \"alice@example.com\",\n },\n };\n\n await next();\n }\n);\n\n// Create a normal Next.js API route handler\nconst apiRouteHandler = async (req, res) => {\n const { name } = req.locals.user;\n\n res.status(200);\n res.send(`Hello, ${name}!`);\n};\n\n// Export the route handler wrapped inside the middleware function\nexport default withMiddleware(apiRouteHandler);\n\n/**\n * Console output:\n *\n * Do work before the request\n * Do more work\n * cors\n * Store user in request\n * Clean up more\n * Clean up\n */\n```\n\n## Usage\n\n### Writing Async Middleware\n\n```ts\nimport type { NextMiddleware } from \"next-api-middleware\";\n\n// Middleware that does work before a request\nexport const addRequestUUID: NextMiddleware = async (req, res, next) => {\n // Set a custom header\n res.setHeader(\"X-Response-ID\", uuid());\n\n // Execute the remaining middleware\n await next();\n};\n\n// Middleware that does work before *and* after a request\nexport const addRequestTiming: NextMiddleware = async (req, res, next) => {\n // Set a custom header before other middleware and the route handler\n res.setHeader(\"X-Timing-Start\", new Date().getTime());\n\n // Execute the remaining middleware\n await next();\n\n // Set a custom header\n res.setHeader(\"X-Timing-End\", new Date().getTime());\n};\n\n// Middleware that catches errors that occur in remaining middleware\n// and the request\nexport const logErrorsWithACME: NextMiddleware = async (req, res, next) => {\n try {\n // Catch any errors that are thrown in remaining\n // middleware and the API route handler\n await next();\n } catch (error) {\n Acme.captureException(error);\n res.status(500);\n res.json({ error: error.message });\n }\n};\n```\n\n### Composing Middleware Groups\n\n```js\nimport { use } from \"next-api-middleware\";\nimport {\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n} from \"../helpers\";\nimport { connectDatabase, loadUsers } from \"../users\";\n\n// Create a middleware wrapper to be used on API routes\n// that need authentication\nexport const withAuthMiddleware = use(\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n connectDatabase,\n loadUsers\n);\n\n// Create a middleware wrapper to be used on API routes\n// that are only used by guests\nexport const withGuestMiddleware = use(\n isProduction ? [addRequestTiming, logErrorsWithACME] : [],\n addRequestUUID\n);\n\n// Create a middleware wrapper using arrays of middleware\n// functions; these are flattened and executed in the order\n// in which they are provided\nexport const withXYZMiddleware = use(\n [addRequestUUID, connectDatabase, loadUsers],\n [addRequestTiming, logErrorsWithACME]\n);\n```\n\nThe `use` method creates a higher order function that applies middleware to an API route. `use` accepts a list of values that evaluate to middleware functions. It also accepts arrays of middleware functions, which are flattened at runtime (order is preserved).\n\nAnother available method for grouping middleware is `label`. Here's how it works:\n\n```ts\nimport { label } from \"next-api-middleware\";\nimport {\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID,\n} from \"../helpers\";\n\n// Create a middleware wrapper that imports middleware and\n// assigns friendly labels\nconst withMiddleware = label({\n timing: addRequestTiming,\n logErrors: logErrorsWithACME,\n uuids: addRequestUUID,\n all: [addRequestTiming, logErrorsWithACME, addRequestUUID],\n});\n\nconst apiRouteHandler = async (req, res) => {\n const { name } = req.locals.user;\n\n res.status(200);\n res.send(`Hello, ${name}!`);\n};\n\n// Only invoke `addRequestTiming` and `logErrorsWithACME`, using their\n// friendly labels\nexport default withMiddleware(\"timing\", \"logErrors\")(apiRouteHandler);\n```\n\nUsing `label` creates a middleware group that, by default, doesn't invoke any middleware. Instead, it allows choosing specific middleware by supplying labels as arguments in the API route.\n\n## Advanced\n\n### Middleware Factories\n\nSince `use` accepts values that evaluate to middleware functions, this provides the opportunity to create custom middleware factories.\n\nHere's an example of a factory that generates a middleware function to only allow requests with a given HTTP method:\n\n```ts\nimport { use, NextMiddleware } from \"next-api-middleware\";\n\nconst httpMethod = (\n allowedHttpMethod: \"GET\" | \"POST\" | \"PATCH\"\n): NextMiddleware => {\n return async function (req, res, next) {\n if (req.method === allowedHttpMethod || req.method == \"OPTIONS\") {\n await next();\n } else {\n res.status(404);\n res.end();\n }\n };\n};\n\nexport const withAuthMiddleware = use(\n httpMethod(\"POST\"),\n addRequestTiming,\n logErrorsWithACME,\n addRequestUUID\n);\n```\n\n### Middleware Types\n\n`next-api-middleware` supports two middleware signatures, `NextMiddleware` and `ExpressMiddleware`.\n\n#### `NextMiddleware` (preferred)\n\n`NextMiddleware` is inspired by the asyncronous middleware style popularized by Koa.js. Prefer this style when writing your own middleware.\n\n```ts\ninterface NextMiddleware {\n (\n req: NextApiRequest,\n res: NextApiResponse,\n next: () => Promise \n \n\n## Introduction\n\n[Next.js API routes](https://nextjs.org/docs/api-routes/introduction) are a ridiculously fun and simple way to add backend functionality to a React app. However, when it comes time to add middleware, there is no easy way to implement it.\n\nThe official Next.js docs recommend writing functions [inside your API route handler](https://nextjs.org/docs/api-routes/api-middlewares) :thumbsdown:. This is a huge step backward compared to the clean APIs provided by Express.js or Koa.js.\n\nThis library attempts to provide minimal, clean, composable middleware patterns that are both productive and pleasant to use. :tada:\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [How It Works](#quick-start)\n- [APIs](#apis)\n - [`label`](#label)\n - [`use`](#use)\n- [Usage Guide](#usage-guide)\n- [Advanced](#advanced)\n - [Debugging](#debugging)\n - [Middleware Factories](#middleware-factories)\n - [Middleware Types](#middleware-types)\n - [`NextMiddleware`](#nextmiddleware-preferred)\n - [`ExpressMiddleware`](#expressmiddleware-compatibility)\n\n## Quick Start\n\n```ts\nimport { label, NextMiddleware } from \"next-api-middleware\";\nimport * as Sentry from \"@sentry/nextjs\";\nimport nanoid from \"nanoid\";\n\n// 1 – Create middleware functions\n\nconst captureErrors: NextMiddleware = async (req, res, next) => {\n try {\n // Catch any errors that are thrown in remaining\n // middleware and the API route handler\n await next();\n } catch (err) {\n const eventId = Sentry.captureException(err);\n\n res.status(500);\n res.json({ error: err });\n }\n};\n\nconst addRequestId: NextMiddleware = async (req, res, next) => {\n // Let remaining middleware and API route execute\n await next();\n\n // Apply header\n res.setHeader(\"X-Response-ID\", nanoid());\n};\n\n// 2 – Use `label` to assemble all middleware\n\nconst withMiddleware = label(\n {\n addRequestId,\n sentry: captureErrors, // <-- Optionally alias middleware\n },\n [\"sentry\"] // <-- Provide a list of middleware to call automatically\n);\n\n// 3 – Define your API route handler\n\nconst apiRouteHandler = async (req, res) => {\n res.status(200);\n res.send(\"Hello world!\");\n};\n\n// 4 – Choose middleware to invoke for this API route\n\nexport default withMiddleware(\"addRequestId\")(apiRouteHandler);\n```\n\n## How It Works\n\nMy mental model for how this library handles middleware functions is that of a \"winding and unwinding stack.\"\n\nLet's imagine you've used `label` to add two middleware functions to an API route.\n\nWhen a request comes in, this is a rough impression of how that request makes its way through all middleware functions, the API route handler itself, and then back up through the middleware.\n\n```\n |-----------------|-----------------|--------------------|\n | Middleware #1 | Middleware #2 | API Route Handler |\n |-----------------|-----------------|--------------------|\n | | | |\nRequest ------|----> Setup -----|----> Setup -----|-->------| |\n | | | | |\n |-----------------|-----------------| V |\n | | | |\n | await next() | await next() | API stuff |\n | | | |\n |-----------------|-----------------| | |\n | | | | |\nResponse <----|--- Teardown <---|--- Teardown <---|---------| |\n | | | |\n |-----------------|-----------------|--------------------|\n```\n\nWhile this is a crummy ASCII diagram, I think it gives the right impression. The request winds its way though each middleware function in succession, hits the API route handler, and then proceeds to \"unwind\" its way through the stack.\n\nEvery middleware function has the opportunity to go through three phases:\n\n1. Setup\n2. Waiting\n3. Teardown\n\nThe \"Setup\" phase covers everything that happens before `await next()`. The \"Waiting\" phase is really just `await next()`. The \"Teardown\" phase is the remaining code within a middleware function after `await next()`.\n\nIt is worth noting that although these phases are available to all middleware functions, you don't need to take advantage of them all.\n\nFor example, in error catching middleware you might simply wrap `await next()` in a `try / catch` block. On the other hand, you might have request timing middleware that captures a start time during the setup phase, waits, and then captures a finish time in the teardown phase.\n\n## APIs\n\n### `label`\n\nThis is the primary utility for creating reusuable collections of middleware for use throughout many Next.js API routes.\n\n```ts\nconst withMiddleware = label(middleware, defaults);\n```\n\n#### Parameters\n\n- `middleware`: an object containing middleware functions or arrays of middleware\n- `defaults`: (optional) an array of `middleware` keys that will be invoked automatically\n\n#### Return Value\n\n`label` returns a function (conventionally referred to as `withMiddleware`) that uses currying to accept a list of middleware names to be invoked, followed by a Next.js API handler function.\n\nTypically, `withMiddleware` will be imported in API route files and used at the default export statement:\n\n```ts\nimport { withMiddleware } from \"../helpers/my-middleware\";\n\nconst apiRouteHandler = async (req, res) => {\n ...\n}\n\nexport default withMiddleware(\"foo\", \"bar\", \"baz\")(apiRouteHandler);\n```\n\nThough `label` could contain many middleware functions, the actual middleware invoked by an API route is determined by the names passed in to `withMiddleware`.\n\n#### Examples\n\n##### Basic Use\n\n```ts\nconst logErrors = async (req, res, next) => {\n try {\n await next();\n } catch (error) {\n console.error(error);\n res.status(500);\n res.json({ error });\n }\n};\n\nconst withMiddleware = label({\n logErrors,\n});\n\n// export default withMiddleware(\"logErrors\")(apiRouteHandler);\n```\n\n##### Aliases\n\n```ts\nconst withMiddleware = label({\n error: logErrors,\n});\n\n// export default withMiddleware(\"error\")(apiRouteHandler);\n```\n\n##### Groups\n\n```ts\nimport { foo, bar, baz } from \"./my-middleware\";\n\nconst withMiddleware = label({\n error: logErrors,\n myGroup: [foo, bar, baz],\n});\n\n// export default withMiddleware(\"error\", \"myGroup\")(apiRouteHandler);\n```\n\n##### Defaults\n\n```ts\nconst withMiddleware = label(\n {\n error: logErrors,\n myGroup: [foo, bar, baz],\n },\n [\"error\"]\n);\n\n// export default withMiddleware(\"myGroup\")(apiRouteHandler);\n```\n\n### `use`\n\nThis utility accepts middleware functions directly and executes them all in order. It is a simpler alternative to `label` that can be useful for handling one-off middleware functions.\n\n```ts\nconst withInlineMiddleware = use(...middleware);\n```\n\n#### Parameters\n\n- `middleware`: a list of middleware functions and/or arrays of middleware functions\n\n#### Return Value\n\n`use` returns a function that accepts a Next.js API route handler.\n\n#### Examples\n\n##### CORS\n\n```ts\nimport { use } from \"next-api-middleware\";\nimport cors from \"cors\";\n\nconst apiRouteThatOnlyNeedsCORS = async (req, res) => {\n ...\n}\n\nexport default use(cors())(apiRouteThatOnlyNeedsCORS);\n```\n\n## Usage Guide\n\nSee [EXAMPLES.md](./EXAMPLES.md) for more detailed examples of `label` and `use`.\n\n## Advanced\n\n### Debugging\n\n`next-api-middleware` uses [`debug`](https://npmjs.com/package/debug) to provide different levels of debug logging.\n\nLogs for this library are available under the `middleware` namespace.\n\n> These example commands assume the presence of a script called `dev` in your project's `package.json` that runs `next dev`.\n\n```sh\n# Show all logs\nDEBUG=middleware:* npm run dev\n\n# Show all logs for the `/api/foo` route\nDEBUG=middleware:/api/foo npm run dev\n\n# Show all logs for the 3rd middleware function in `/api/foo`\nDEBUG=middleware:/api/foo:fn-3 npm run dev\n```\n\nYou can also wrap the value of `DEBUG` in quotes if desired:\n\n```sh\nDEBUG='middleware:/api/foo' npm run dev\n```\n\n### Middleware Factories\n\nSince `use` and `label` accept values that evaluate to middleware functions, this provides the opportunity to create custom middleware factories.\n\nHere's an example of a factory that generates a middleware function to only allow requests with a given HTTP method:\n\n```ts\nimport { NextMiddleware } from \"next-api-middleware\";\n\nconst httpMethod = (\n allowedHttpMethod: \"GET\" | \"POST\" | \"PATCH\"\n): NextMiddleware => {\n return async function (req, res, next) {\n if (req.method === allowedHttpMethod || req.method == \"OPTIONS\") {\n await next();\n } else {\n res.status(404);\n res.end();\n }\n };\n};\n\nexport const postRequestsOnlyMiddleware = httpMethod(\"POST\");\n```\n\n### Middleware Types\n\n`next-api-middleware` supports two middleware signatures, `NextMiddleware` and `ExpressMiddleware`.\n\n#### `NextMiddleware`\n\n`NextMiddleware` is inspired by the asyncronous middleware style popularized by Koa.js. Prefer this style when writing your own middleware.\n\n```ts\ninterface NextMiddleware {\n (\n req: NextApiRequest,\n res: NextApiResponse,\n next: () => Promise \n \n\n## Introduction\n\n[Next.js API routes](https://nextjs.org/docs/api-routes/introduction) are a ridiculously fun and simple way to add backend functionality to a React app. However, when it comes time to add middleware, there is no easy way to implement it.\n\nThe official Next.js docs recommend writing functions [inside your API route handler](https://nextjs.org/docs/api-routes/api-middlewares) :thumbsdown:. This is a huge step backward compared to the clean APIs provided by Express.js or Koa.js.\n\nThis library attempts to provide minimal, clean, composable middleware patterns that are both productive and pleasant to use. :tada:\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [How It Works](#quick-start)\n- [APIs](#apis)\n - [`label`](#label)\n - [`use`](#use)\n- [Usage Guide](#usage-guide)\n- [Advanced](#advanced)\n - [Debugging](#debugging)\n - [Middleware Factories](#middleware-factories)\n - [Middleware Types](#middleware-types)\n - [`NextMiddleware`](#nextmiddleware-preferred)\n - [`ExpressMiddleware`](#expressmiddleware-compatibility)\n\n## Quick Start\n\n```ts\nimport { label, NextMiddleware } from \"next-api-middleware\";\nimport * as Sentry from \"@sentry/nextjs\";\nimport nanoid from \"nanoid\";\n\n// 1 – Create middleware functions\n\nconst captureErrors: NextMiddleware = async (req, res, next) => {\n try {\n // Catch any errors that are thrown in remaining\n // middleware and the API route handler\n await next();\n } catch (err) {\n const eventId = Sentry.captureException(err);\n\n res.status(500);\n res.json({ error: err });\n }\n};\n\nconst addRequestId: NextMiddleware = async (req, res, next) => {\n // Let remaining middleware and API route execute\n await next();\n\n // Apply header\n res.setHeader(\"X-Response-ID\", nanoid());\n};\n\n// 2 – Use `label` to assemble all middleware\n\nconst withMiddleware = label(\n {\n addRequestId,\n sentry: captureErrors, // <-- Optionally alias middleware\n },\n [\"sentry\"] // <-- Provide a list of middleware to call automatically\n);\n\n// 3 – Define your API route handler\n\nconst apiRouteHandler = async (req, res) => {\n res.status(200);\n res.send(\"Hello world!\");\n};\n\n// 4 – Choose middleware to invoke for this API route\n\nexport default withMiddleware(\"addRequestId\")(apiRouteHandler);\n```\n\n## How It Works\n\nMy mental model for how this library handles middleware functions is that of a \"winding and unwinding stack.\"\n\nLet's imagine you've used `label` to add two middleware functions to an API route.\n\nWhen a request comes in, this is a rough impression of how that request makes its way through all middleware functions, the API route handler itself, and then back up through the middleware.\n\n```\n |-----------------|-----------------|--------------------|\n | Middleware #1 | Middleware #2 | API Route Handler |\n |-----------------|-----------------|--------------------|\n | | | |\nRequest ------|----> Setup -----|----> Setup -----|-->------| |\n | | | | |\n |-----------------|-----------------| V |\n | | | |\n | await next() | await next() | API stuff |\n | | | |\n |-----------------|-----------------| | |\n | | | | |\nResponse <----|--- Teardown <---|--- Teardown <---|---------| |\n | | | |\n |-----------------|-----------------|--------------------|\n```\n\nWhile this is a crummy ASCII diagram, I think it gives the right impression. The request winds its way though each middleware function in succession, hits the API route handler, and then proceeds to \"unwind\" its way through the stack.\n\nEvery middleware function has the opportunity to go through three phases:\n\n1. Setup\n2. Waiting\n3. Teardown\n\nThe \"Setup\" phase covers everything that happens before `await next()`. The \"Waiting\" phase is really just `await next()`. The \"Teardown\" phase is the remaining code within a middleware function after `await next()`.\n\nIt is worth noting that although these phases are available to all middleware functions, you don't need to take advantage of them all.\n\nFor example, in error catching middleware you might simply wrap `await next()` in a `try / catch` block. On the other hand, you might have request timing middleware that captures a start time during the setup phase, waits, and then captures a finish time in the teardown phase.\n\n## APIs\n\n### `label`\n\nThis is the primary utility for creating reusuable collections of middleware for use throughout many Next.js API routes.\n\n```ts\nconst withMiddleware = label(middleware, defaults);\n```\n\n#### Parameters\n\n- `middleware`: an object containing middleware functions or arrays of middleware\n- `defaults`: (optional) an array of `middleware` keys that will be invoked automatically\n\n#### Return Value\n\n`label` returns a function (conventionally referred to as `withMiddleware`) that uses currying to accept a list of middleware names to be invoked, followed by a Next.js API handler function.\n\nTypically, `withMiddleware` will be imported in API route files and used at the default export statement:\n\n```ts\nimport { withMiddleware } from \"../helpers/my-middleware\";\n\nconst apiRouteHandler = async (req, res) => {\n ...\n}\n\nexport default withMiddleware(\"foo\", \"bar\", \"baz\")(apiRouteHandler);\n```\n\nThough `label` could contain many middleware functions, the actual middleware invoked by an API route is determined by the names passed in to `withMiddleware`.\n\n#### Examples\n\n##### Basic Use\n\n```ts\nconst logErrors = async (req, res, next) => {\n try {\n await next();\n } catch (error) {\n console.error(error);\n res.status(500);\n res.json({ error });\n }\n};\n\nconst withMiddleware = label({\n logErrors,\n});\n\n// export default withMiddleware(\"logErrors\")(apiRouteHandler);\n```\n\n##### Aliases\n\n```ts\nconst withMiddleware = label({\n error: logErrors,\n});\n\n// export default withMiddleware(\"error\")(apiRouteHandler);\n```\n\n##### Groups\n\n```ts\nimport { foo, bar, baz } from \"./my-middleware\";\n\nconst withMiddleware = label({\n error: logErrors,\n myGroup: [foo, bar, baz],\n});\n\n// export default withMiddleware(\"error\", \"myGroup\")(apiRouteHandler);\n```\n\n##### Defaults\n\n```ts\nconst withMiddleware = label(\n {\n error: logErrors,\n myGroup: [foo, bar, baz],\n },\n [\"error\"]\n);\n\n// export default withMiddleware(\"myGroup\")(apiRouteHandler);\n```\n\n### `use`\n\nThis utility accepts middleware functions directly and executes them all in order. It is a simpler alternative to `label` that can be useful for handling one-off middleware functions.\n\n```ts\nconst withInlineMiddleware = use(...middleware);\n```\n\n#### Parameters\n\n- `middleware`: a list of middleware functions and/or arrays of middleware functions\n\n#### Return Value\n\n`use` returns a function that accepts a Next.js API route handler.\n\n#### Examples\n\n##### CORS\n\n```ts\nimport { use } from \"next-api-middleware\";\nimport cors from \"cors\";\n\nconst apiRouteThatOnlyNeedsCORS = async (req, res) => {\n ...\n}\n\nexport default use(cors())(apiRouteThatOnlyNeedsCORS);\n```\n\n## Usage Guide\n\nSee [EXAMPLES.md](./EXAMPLES.md) for more detailed examples of `label` and `use`.\n\n## Advanced\n\n### Debugging\n\n`next-api-middleware` uses [`debug`](https://npmjs.com/package/debug) to provide different levels of debug logging.\n\nLogs for this library are available under the `middleware` namespace.\n\n> These example commands assume the presence of a script called `dev` in your project's `package.json` that runs `next dev`.\n\n```sh\n# Show all logs\nDEBUG=middleware:* npm run dev\n\n# Show all logs for the `/api/foo` route\nDEBUG=middleware:/api/foo npm run dev\n\n# Show all logs for the 3rd middleware function in `/api/foo`\nDEBUG=middleware:/api/foo:fn-3 npm run dev\n```\n\nYou can also wrap the value of `DEBUG` in quotes if desired:\n\n```sh\nDEBUG='middleware:/api/foo' npm run dev\n```\n\n### Middleware Factories\n\nSince `use` and `label` accept values that evaluate to middleware functions, this provides the opportunity to create custom middleware factories.\n\nHere's an example of a factory that generates a middleware function to only allow requests with a given HTTP method:\n\n```ts\nimport { NextMiddleware } from \"next-api-middleware\";\n\nconst httpMethod = (\n allowedHttpMethod: \"GET\" | \"POST\" | \"PATCH\"\n): NextMiddleware => {\n return async function (req, res, next) {\n if (req.method === allowedHttpMethod || req.method == \"OPTIONS\") {\n await next();\n } else {\n res.status(404);\n res.end();\n }\n };\n};\n\nexport const postRequestsOnlyMiddleware = httpMethod(\"POST\");\n```\n\n### Middleware Types\n\n`next-api-middleware` supports two middleware signatures, `NextMiddleware` and `ExpressMiddleware`.\n\n#### `NextMiddleware`\n\n`NextMiddleware` is inspired by the asyncronous middleware style popularized by Koa.js. Prefer this style when writing your own middleware.\n\n```ts\ninterface NextMiddleware {\n (\n req: NextApiRequest,\n res: NextApiResponse,\n next: () => Promise \n \n \n \n \n \n \n \n \n \n Next.js API Middleware
\nNext.js API Middleware
\nNext.js API Middleware
\nNext.js API Middleware
\n\n \n \n \n \n \n Next.js API Middleware
\n
\n \n \n \n \n \n \n \n
\n
\n \n ![\"npm\"](\"https://img.shields.io/npm/v/next-api-middleware.svg\")
\n \n \n ![\"npm\"](\"https://img.shields.io/npm/dm/next-api-middleware\")
![\"license\"](\"https://img.shields.io/github/license/htunnicliff/next-api-middleware.svg\")
\n \n \n ![\"GitHub](\"https://img.shields.io/github/actions/workflow/status/htunnicliff/next-api-middleware/main.yaml?label=Tests\")
![\"Codecov\"](\"https://img.shields.io/codecov/c/github/htunnicliff/next-api-middleware?&&token=XI7G8L08TY\")
![\"npm@latest\"](\"https://img.shields.io/npm/v/next-api-middleware/latest.svg?style=for-the-badge&labelColor=000000\")
\n ![\"npm@canary\"](\"https://img.shields.io/npm/v/next-api-middleware/canary.svg?style=for-the-badge&labelColor=000000\")
\n