{"id":17852,"library":"nuxt-proxy","title":"Nuxt Proxy Middleware","description":"nuxt-proxy is a Nuxt 3 module that integrates `http-proxy-middleware` and `h3` to provide HTTP proxying capabilities directly within a Nuxt application. It enables developers to configure declarative proxy rules in `nuxt.config.ts`, facilitating the routing of specific client-side API requests to backend servers. This is commonly used to circumvent CORS restrictions or to unify API endpoints under a single origin. The current stable version is 0.4.1. Releases typically focus on bug fixes, dependency updates (e.g., `h3`, `@nuxt/kit`), and minor feature enhancements such as runtime configuration overrides. Its key differentiator is a streamlined, module-based setup within the Nuxt ecosystem, leveraging Nuxt's Nitro server for efficient middleware handling, offering a more integrated solution than manually setting up a proxy.","status":"active","version":"0.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/wobsoriano/nuxt-proxy","tags":["javascript","proxy","nuxt","vue","http","connect","h3","typescript"],"install":[{"cmd":"npm install nuxt-proxy","lang":"bash","label":"npm"},{"cmd":"yarn add nuxt-proxy","lang":"bash","label":"yarn"},{"cmd":"pnpm add nuxt-proxy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core framework for the module to operate within.","package":"nuxt","optional":false},{"reason":"Underlying proxy library used by nuxt-proxy. Managed internally by the module.","package":"http-proxy-middleware","optional":false},{"reason":"Nuxt 3's server engine, which nuxt-proxy integrates with for middleware handling. Managed internally by the module.","package":"h3","optional":false}],"imports":[{"note":"nuxt-proxy is activated by adding its name to the `modules` array in `nuxt.config.ts`. No direct JavaScript import statements are typically used in components or server routes for this module.","symbol":"Module Activation","correct":"export default defineNuxtConfig({\n  modules: [\n    'nuxt-proxy'\n  ],\n  // ...\n})"},{"note":"Proxy rules are configured via the `proxy` property within `defineNuxtConfig`. This object directly maps to the options of `http-proxy-middleware`.","symbol":"Proxy Configuration","correct":"export default defineNuxtConfig({\n  proxy: {\n    options: {\n      target: 'https://jsonplaceholder.typicode.com',\n      changeOrigin: true\n    }\n  }\n})"},{"note":"Proxy options can be overridden at runtime using the `runtimeConfig.proxy` property in `nuxt.config.ts` or via environment variables (e.g., `NUXT_PROXY_OPTIONS_TARGET`). `process.env` access is typical for fetching runtime values.","symbol":"Runtime Configuration Overrides","correct":"export default defineNuxtConfig({\n  runtimeConfig: {\n    proxy: {\n      options: { target: process.env.NUXT_PROXY_OVERRIDE_TARGET ?? 'https://jsonplaceholder.typicode.com' }\n    }\n  }\n})"}],"quickstart":{"code":"import { defineNuxtConfig } from 'nuxt';\n\nexport default defineNuxtConfig({\n  modules: [\n    'nuxt-proxy'\n  ],\n  proxy: {\n    options: {\n      target: process.env.NUXT_PROXY_TARGET ?? 'https://jsonplaceholder.typicode.com',\n      changeOrigin: true,\n      pathRewrite: {\n        '^/api/todos': '/todos',\n        '^/api/users': '/users'\n      },\n      pathFilter: [\n        '/api/todos',\n        '/api/users'\n      ]\n    }\n  },\n  // Example of using runtimeConfig for proxy options\n  runtimeConfig: {\n    proxy: {\n      options: {\n        target: process.env.NUXT_RUNTIME_PROXY_TARGET ?? 'https://jsonplaceholder.typicode.com'\n      }\n    }\n  }\n});\n\n// In a Vue component or server route (e.g., pages/index.vue)\n// <script setup>\n// const { data: todos } = await useFetch('/api/todos');\n// console.log('Fetched Todos:', todos.value);\n// const { data: users } = await useFetch('/api/users');\n// console.log('Fetched Users:', users.value);\n// </script>","lang":"typescript","description":"Demonstrates how to enable `nuxt-proxy` as a module, configure basic proxy rules in `nuxt.config.ts` including `target`, `pathRewrite`, and `pathFilter`, and show how client-side `useFetch` interacts with the proxied endpoints. It also includes an example of runtime configuration."},"warnings":[{"fix":"Evaluate if `h3.proxyRequest` meets your requirements. If so, consider using it directly in a Nuxt server route (`server/api/**/*.ts`) instead of `nuxt-proxy`.","message":"The `nuxt-proxy` README explicitly advises checking h3's built-in `proxyRequest` helper before using this module. For simple proxy needs, `h3`'s native solution might be more lightweight and performant.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Ensure you are on `nuxt-proxy@0.4.1` or newer. If issues persist, verify your `pnpm` workspace configuration and check `http-proxy-middleware` for specific ESM caveats.","message":"Past ESM compatibility issues with `http-proxy-middleware` (via pnpm patch) were noted in v0.4.1. While fixed, this indicates potential for environment-specific issues, especially with package managers like pnpm or strict ESM setups.","severity":"gotcha","affected_versions":"<0.4.1"},{"fix":"Consult the documentation on runtime configuration. Typically, environment variables take precedence over `runtimeConfig`, which in turn overrides direct `proxy` configuration in `defineNuxtConfig`.","message":"Understanding the precedence of proxy configuration is crucial. Options can be set directly in `defineNuxtConfig.proxy`, in `runtimeConfig.proxy`, and via environment variables. Incorrect placement or naming can lead to settings not being applied.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Carefully review the `http-proxy-middleware` documentation for `pathRewrite` and `pathFilter` syntax and behavior. Test proxy routes thoroughly to ensure they resolve to the expected backend endpoints.","message":"Misconfiguration of `pathRewrite` and `pathFilter` options can lead to requests not being proxied correctly or being sent to unintended backend paths. `pathFilter` defines which paths activate the proxy, while `pathRewrite` modifies the path before forwarding.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Verify that your `pathFilter` regex or array includes the requested path (`/api/todos`). Ensure `pathRewrite` correctly transforms the path to what the target API expects (e.g., from `/api/todos` to `/todos`). Double-check the `target` URL for accuracy and connectivity.","cause":"The proxy rule's `pathFilter` is not matching the incoming request path, or `pathRewrite` is incorrectly configured, leading to the request not being intercepted or forwarded to the wrong backend path, resulting in a 404 from the Nuxt server or the backend.","error":"GET http://localhost:3000/api/todos 404 (Not Found)"},{"fix":"Add `changeOrigin: true` to your `proxy.options` in `nuxt.config.ts`. If the issue persists, the backend server itself may need configuration to allow requests from the origin the proxy presents, or to include `Access-Control-Allow-Origin` headers for the proxied requests.","cause":"Despite using a proxy to circumvent CORS, the backend server might still be enforcing CORS policies. This can happen if `changeOrigin: true` is not set in the proxy options, or if the backend itself doesn't send the appropriate CORS headers for the proxied request.","error":"Access to XMLHttpRequest at 'http://backend.example.com/data' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource."},{"fix":"Ensure you are using `nuxt-proxy@0.4.1` or newer. If using pnpm, try adding a `.pnpmfile.cjs` or `package.json` `pnpm.patchedDependencies` entry to explicitly patch `http-proxy-middleware` for ESM compatibility, as indicated in `nuxt-proxy`'s changelog, if the issue persists.","cause":"This error typically occurs in specific environments (e.g., pnpm with certain strict settings) where `http-proxy-middleware` might not be correctly resolved as an ESM module, despite fixes in recent `nuxt-proxy` versions.","error":"Error: Cannot find module 'http-proxy-middleware' imported from <some-path>/nuxt-proxy/dist/module.mjs"},{"fix":"Ensure the environment variable is correctly named, typically `NUXT_PROXY_OPTIONS_TARGET` for the root proxy options target. Verify that `runtimeConfig.proxy` is set up in `nuxt.config.ts` to consume these environment variables, and there are no other configurations with higher precedence overriding it.","cause":"The environment variable for proxy configuration is either misspelled, not correctly prefixed for Nuxt's runtime config, or is being overridden by a more specific configuration.","error":"Proxy configuration not applied from environment variable NUXT_PROXY_OPTIONS_TARGET"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}