flytachi / winter-front-nuxt
A Nuxt frontend in a Winter application: declared in one line, served by the application's own HTTP server, built into its image
Requires
- php: >=8.4
- flytachi/winter-kernel: ^4.6@RC
Requires (Dev)
- phpunit/phpunit: @stable
- squizlabs/php_codesniffer: @stable
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 13:16:48 UTC
README
A Nuxt frontend in a Winter application, declared in one line. The application's own HTTP
server sends its built files beside the API — no nginx, no proxy, no Node in production —
and call service docker builds it into the image.
$components->frontend(Nuxt::spa('frontend'));
📖 The frontend in the documentation
Installation
composer require flytachi/winter-front-nuxt
Requires PHP 8.4+ and flytachi/winter-kernel 4.6+. Nuxt 3 or 4 in a folder
of the project.
Quick start
1. Declare it in the application — the first argument is the frontend's folder, from the project root:
use Flytachi\Winter\Front\Nuxt\Nuxt; protected static function components(Components $components): void { $components->frontend(Nuxt::spa('frontend')); }
2. Configure Nuxt — a single-page app:
// frontend/nuxt.config.ts export default defineNuxtConfig({ ssr: false, nitro: { compressPublicAssets: true }, })
3. Build it:
cd frontend && pnpm install && pnpm run generate
call run serves it: http://localhost:8000/users/7 is the app, /api/... the
controllers. Until it is built the API works, the frontend is FAILED in
call app status and a page answers 503; once .output/public is there it is up within a
few seconds — no restart.
4. Put it in the image:
call service docker
A Node stage of its own builds it; the image gets .output/public only.
Modes
| Factory | nuxt.config.ts |
Unknown page | |
|---|---|---|---|
| Single-page app | Nuxt::spa() |
ssr: false |
the app's 200.html — the browser routes |
| Pre-rendered site | Nuxt::ssg() |
no ssr key; prerender |
404 |
// Nuxt::ssg() — every page built in advance (SEO), the links followed from / export default defineNuxtConfig({ nitro: { compressPublicAssets: true, prerender: { crawlLinks: true, routes: ['/'] } }, })
Both are built with generate. Rendering on every request (SSR) and nuxt dev under
call run dev are coming.
Where it answers
Nuxt::spa('frontend'); // at /, beside the API Nuxt::spa('admin', path: '/admin'); // under a path Nuxt::spa('admin', port: 9091, routes: '/admin'); // a port of its own Nuxt::spa('admin', port: 9091, routes: ['/admin', '/auth']); Nuxt::spa('admin', port: 9091, routes: '/admin', exclusive: false);
- A controller always wins. The frontend gets a GET or HEAD no route took. A
POSTto a typo is the API's 404, never the page; so is a browser'sfetch()of a path no route has. path:— the app must know it too:app: { baseURL: '/admin/' }. Nuxt then puts that path in front ofuseFetch('/api/...')as well; for the API at the root sayuseFetch('/api/users', { baseURL: '/' }).port:withroutes:— on its port the frontend answers everything but itsroutes, which reach the controllers; those prefixes are closed on the HTTP port, so an admin API is not reachable from outside by accident.exclusive: falsekeeps them open there too.name:— how logs andcall app statusname it; by default the folder's name.
The package manager
Told by the lock file in the folder; the image's build stage runs:
| Lock file | Install | Build |
|---|---|---|
pnpm-lock.yaml |
pnpm install --frozen-lockfile |
pnpm run generate |
package-lock.json |
npm ci |
npm run generate |
yarn.lock |
yarn install --frozen-lockfile (--immutable for yarn 2+) |
yarn run generate |
bun.lock |
bun install --frozen-lockfile |
bun run generate |
pnpm and yarn come through corepack, at the version packageManager in package.json
names. Several lock files: the one packageManager names, or say it:
Nuxt::spa('frontend', packageManager: PackageManager::Npm);
pnpm 10+ runs no install scripts unless they are allowed — Nuxt needs esbuild's:
# frontend/pnpm-workspace.yaml — pnpm 11 allowBuilds: esbuild: true # pnpm 10: onlyBuiltDependencies: [esbuild]
The install step gets package.json, the lock file, .npmrc, pnpm-workspace.yaml and
.yarnrc.yml — not folders. An install that needs more (patches/ of pnpm's
patchedDependencies, yarn's .yarn/releases, patch-package in postinstall) fails
there: for now such a build is written into the Dockerfile by hand.
The image's .dockerignore must leave out **/node_modules, **/.nuxt and **/.output:
call service docker says so when it does not.
What it says at start
call run logs, as warnings, what does not match the mode:
the frontend "frontend": nuxt.config.ts has no ssr: false — generate prerenders every page; set it for a single-page app, or use Nuxt::ssg()
the frontend "admin": app.baseURL is not "/admin/" — the pages ask for /_nuxt/ instead of /admin/_nuxt/; set app: { baseURL: '/admin/' }
the frontend "frontend": not built yet: run "pnpm run generate" in frontend/
Only literal values are read: ssr: process.env.SPA !== '1' is taken as it is.
NUXT_APP_BASE_URL in the environment counts as baseURL. A warning never stops the
start.
Testing
composer test
License
MIT — see LICENSE.