<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/neg4n/next-api-compose/development/.github/assets/code_dark.png">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/neg4n/next-api-compose/development/.github/assets/code_light.png">
<img align="right" width="500px" height="500px" alt="next-api-compose example code theme aware" src="https://raw.githubusercontent.com/neg4n/next-api-compose/development/.github/assets/code_dark.png"/>
</picture>
Introduction
This library provides a hassle-free way of composing multiple middleware functions into one Next.js API Route Handler's method in the App Directory router.
[!IMPORTANT]
The 2.0.0 version of the library supports both app and pages directory oriented API utilities. If you're still using Pages Router and you want to migrate from versions below 2.0.0, please read migration guide and ocassionally consider checking out intro to the App Router.
Features
Installing and basic usage
Install the package by running:
then create an API Route Handler in the App Directory:
in TypeScript (recommended)
in JavaScript:
Error handling
Handling errors both in middleware and in the main handler is as simple as providing sharedErrorHandler to the compose function's second parameter (a.k.a compose settings). Main goal of the shared error handler is to provide clear and easy way to e.g. send the error metadata to Sentry or other error tracking service.
By default, shared error handler looks like this:
... and some usage example:
will return {"error": "foo"} along with 500 status code instead of throwing an error.
Theory and caveats
-
Unfortunately there is no way to dynamically export named ESModules (or at least I did not find a way) so you have to use export { GET, POST } syntax instead of something like export compose(...) if you're composing GET and POST methods :(
-
Middleware is executed as specified in the per-method array, so if you want to execute middleware in a specific order, you have to be careful about it. Early returned new Response() halts the middleware chain.
Contributors
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tbody>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://neg4n.dev/"><img src="https://avatars.githubusercontent.com/u/57688858?v=4?s=100" width="100px;" alt="Igor"/><br /><sub><b>Igor</b></sub></a><br /><a href="https://github.com/neg4n/next-api-compose/commits?author=neg4n" title="Code">💻</a> <a href="https://github.com/neg4n/next-api-compose/commits?author=neg4n" title="Tests">⚠️</a> <a href="#example-neg4n" title="Examples">💡</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/mgrabka"><img src="https://avatars.githubusercontent.com/u/116151164?v=4?s=100" width="100px;" alt="Maksymilian Grabka"/><br /><sub><b>Maksymilian Grabka</b></sub></a><br /><a href="https://github.com/neg4n/next-api-compose/commits?author=mgrabka" title="Tests">⚠️</a> <a href="https://github.com/neg4n/next-api-compose/commits?author=mgrabka" title="Code">💻</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/kacper3123"><img src="https://avatars.githubusercontent.com/u/89151689?v=4?s=100" width="100px;" alt="kacper3123"/><br /><sub><b>kacper3123</b></sub></a><br /><a href="https://github.com/neg4n/next-api-compose/commits?author=kacper3123" title="Documentation">📖</a></td>
</tr>
</tbody>
</table>
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
License and acknowledgements
The project is licensed under The MIT License. Thanks for all the contributions! Feel free to open an issue or a pull request even if it is just a question 🙌