Laravel Nuxt Laravel Package

Getting Started

1. Install and publish. composer require m2s/laravel-nuxt, then publish the package's config/views with php artisan vendor:publish --provider="M2S\LaravelNuxt\LaravelNuxtServiceProvider". The published config/laravel-nuxt.php is your single source of truth — read it before doing anything else, because the keys there (Nuxt source directory, build/output directory, SSR toggle) determine where the rest of your project must live.
2. Scaffold the frontend. Run php artisan list and look for nuxt:* commands (typically an install/scaffold command that drops a resources/nuxt skeleton with nuxt.config.js, pages/, layouts/). If no command exists, create the directory manually and npm install nuxt @nuxtjs/axios inside it — the package only needs the config file and build output to exist where its config says they should be.
3. First use case: replace the Blade SPA shell. Add a terminal catch-all route in routes/web.php, e.g. Route::get('{path?}', 'NuxtController@index')->where('path', '.*');, after your API and auth routes. That single route is what turns a Laravel app into "Laravel API + Nuxt front end." Verify it by hitting / and confirming you get the Nuxt HTML rather than a 404.
4. Local loop. Two terminals: php artisan serve on :8000, and npm run dev inside the Nuxt directory on :3000 with an axios/proxy entry pointing /api at Laravel. You develop against the Nuxt dev server and only exercise the Laravel route when testing the production build.

Implementation Patterns

Route ordering is the architecture. Put routes/api.php and any Laravel-rendered pages (login redirects, Nova, health checks, webhooks) first, and the Nuxt catch-all last. The catch-all is a black hole — anything registered after it is unreachable.

Two deployment modes, one codebase. The package's ssr flag (or equivalent) is the switch:

• Static/SPA mode — npm run generate/build emits files into the configured output dir; Laravel serves the shell and Nuxt hydrates client-side. Cheapest to run, no Node process in production.
• SSR mode — requires a live Node process (nuxt start) that Laravel either proxies to or that sits behind the same reverse proxy. Use this only if you actually need SEO on dynamic routes; otherwise the operational cost is not worth it for an internal tool.

Laravel as the API, Nuxt as the view. Keep all data fetching in routes/api.php and consume it from asyncData/fetch. Configure axios with baseURL: '/api' and withCredentials: true. For auth, use Sanctum's cookie flow: EnsureFrontendRequestsAreStateful in app/Http/Kernel.php, SANCTUM_STATEFUL_DOMAINS including your Nuxt dev host and port, and credentials: true on the axios instance.

Passing server-side data into the shell. For per-request values (CSRF token, feature flags, user id), inject them from the controller into the rendered view as window.__INITIAL_STATE__ or <meta> tags and read them in a Nuxt plugin. Do not try to make the Nuxt bundle call back into Laravel synchronously during the initial render if you're in static mode.

CI/deploy workflow. Treat the Nuxt directory like any front-end package: npm ci && npm run build in CI, then ship the emitted output alongside the Laravel release. Add the generated output dir to .gitignore in dev and to your deploy artifact in prod. php artisan route:cache and config:cache should be run after the build, not before.

Local proxy pattern. In nuxt.config.js, set axios: { baseURL: '/api' } and proxy: { '/api': 'http://localhost:8000' }. This keeps the same relative URLs in dev and prod and avoids CORS entirely during development.

Gotchas and Tips

• This package is effectively unmaintained (19 stars, 0 dependents). Before committing, check composer.json constraints against your PHP/Laravel version and confirm it supports the Nuxt major version you're using. It targets Nuxt 2 conventions (dist/, nuxt generate); Nuxt 3's Nitro/.output/public layout will not line up without you doing the wiring yourself.
• The catch-all will shadow things. /storage/..., /nova, /horizon, /telescope, and any webhook endpoint must be registered before it. If a route suddenly 404s or returns HTML, this is almost always why.
• Blank page = missing build output. The most common failure is the package pointing at a build directory that was never built (or was built to a different path). Confirm the value in config/laravel-nuxt.php matches dir/buildDir/generate.dir in nuxt.config.js. There is no loud error — you just get an empty shell.
• Dev server bypasses Laravel. npm run dev never touches your catch-all route, so a broken route or bad config only surfaces when you test the built output. Test npm run build && php artisan serve before every deploy.
• SSR needs Node running. If you enable SSR, php artisan serve alone won't render anything meaningful. Budget for a process manager (supervisor/systemd) and a health check.
• Route caching quirks. Optional catch-alls with where('path', '.*') can behave inconsistently under route:cache. If routes break only in production, clear and rebuild the route cache to isolate it.
• Extension points are thin. The practical escape hatches are: publish and edit the views, subclass or replace the package's controller in your own Route::get, and edit the config. If you need more than that, vendor the ~small package into app/ rather than fighting it — it's a thin wrapper, not a framework.
• Debugging checklist: does the configured build dir exist and contain index.html (or the SSR server entry)? Does storage/logs/laravel.log show the request reaching the controller? Does the rendered HTML contain your Nuxt script tags? That sequence localizes the problem to build, routing, or view in three steps.