nuxt-neo

nuxt-neo is an open-source Nuxt.js module that adds a middleware API layer between the browser, your server, and third-party private APIs, using a controllers-and-actions pattern to unify data flow across client and server.

What is nuxt-neo?

nuxt-neo is a Nuxt.js module that automatically generates API routes from the folder and file structure of an "api" directory, letting you define controllers and actions instead of writing route handlers manually. It runs on Nuxt.js applications and is developed by ezypeeze on GitHub, distributed via npm under an MIT license. The module intercepts requests on both server and client side, so you can call the same API endpoints the same way regardless of where code executes.

Key Features

• Auto-generated routes — placing a file at api/users/list.js automatically exposes an endpoint without manual route registration.
• Middleware injection — apply middleware globally to all API routes, or scope it to a specific controller or action, giving you per-endpoint control over authentication, logging, or other pre-processing.
• One consistent access method — call the same API from asyncData, fetch, or other client-side code, reducing boilerplate when switching between server and client execution.
• Global HTTP errors — centralized error handling lets you return consistent HTTP error responses across your API, improving debugging and client-side error handling.
• Opinionated but flexible — the controllers-and-actions structure enforces a predictable pattern while still allowing customization of middleware and routing behavior.

Who should use nuxt-neo?

• Nuxt.js developers who want to build a backend API without leaving their Nuxt project, using a structured controllers-and-actions layout instead of raw Express or Nuxt server routes.
• Full-stack teams that need a uniform data-fetching strategy — nuxt-neo lets the same API be called from server-side rendering and client-side navigation with identical code.
• Developers integrating third-party APIs who want a middleware layer to forward, transform, or secure requests to private upstream services before they reach the browser.

Use cases

• Building API endpoints for a Nuxt app — define a controller and actions in the api folder, and nuxt-neo exposes them as REST-style routes automatically, ready for asyncData or fetch calls.
• Proxying private APIs — place middleware that adds API keys or rewrites URLs, so the browser never talks directly to the upstream service.
• Centralizing error handling — use the global HTTP error mechanism to return JSON errors with proper status codes, making client-side error handling more predictable.

How does nuxt-neo work?

nuxt-neo reads the folder and file structure of your api directory and generates corresponding routes during Nuxt build time. Each file or folder maps to a route, with actions defined inside controllers. Middleware can be registered globally or per controller/action, and all requests are funneled through a single client-side helper.

FAQ

What is the license?

nuxt-neo is released under the MIT license, so you can use, modify, and distribute it freely in personal or commercial projects.

Does nuxt-neo work on both server and client?

Yes. The module abstracts the execution context, so the same API call syntax works during server-side rendering and client-side navigation, which prevents duplication of data-fetching logic.

How do I create a new API endpoint?

Create a new file inside the api folder in the controller/action structure, for example api/users/list.js. nuxt-neo automatically generates the route and makes it accessible through the unified API method.

Can I apply middleware to specific actions?

Yes, middleware can be declared globally for the entire API, per controller, or per action, giving you granular control over request processing.