Nuxt starter

Nuxt starter for Roadiz-driven sites and platforms, with UI stories, i18n, optimized images, and a production-ready Docker setup.

Quick start

1. Duplicate .env.sample into .env and fill the required values.
2. Install dependencies:

pnpm install

3. Start the dev server:

pnpm dev

4. Open http://localhost:3000.
5. (Optional) Start stories:

docker compose up -d
pnpm stories

Architecture in 2 minutes

• Dynamic routing via Roadiz in app/pages/[...slug].vue.
• Pages come from a Roadiz web response and render through global blocks.
• Stories are available on /_stories to preview components.
• Maintenance page is generated via a dedicated build.

Full details: docs/architecture.md.

Folder structure

• app/pages Nuxt routes (catch-all for Roadiz)
• app/components app components
• app/blocks Roadiz blocks components
• app/assets images, icons, styles, story fixtures
• server Nitro server API and story assets
• i18n locales and config

Prerequisites

• Node 24.12.0
• PNPM 9.12.0

Environment (.env)

Duplicate .env.sample into .env, then fill in:

• NUXT_PUBLIC_SITE_URL, NUXT_PUBLIC_SITE_ENV
• NUXT_PUBLIC_API_URL (if using a remote API)
• NUXT_PUBLIC_INTERVENTION_REQUEST_* for the image provider
• XILOFONE_* if you want to fetch translations

The full list and usage details are in docs/architecture.md.

Useful commands

## Development
pnpm dev
## Stories (UI)
pnpm stories
## Production build
pnpm build
## Production preview
pnpm preview

## Lint and format style (CSS / SCSS / Vue files)
pnpm lint:css
## Lint fix (script and style)
pnpm lint-fix

i18n

Translations come from Xilofone and can be fetched with:

At the beginning of a project, import the translation files into Xilofone before running pnpm xilo.

pnpm xilo

nuxt-i18n docs: https://v8.i18n.nuxtjs.org/

API

The application connects to an API using the NUXT_PUBLIC_API_URL environment variable.

When the Node SSR process and the browser live in different network planes, set NUXT_SERVER_API_URL so SSR requests use a different URL than the browser. This happens in two common scenarios:

Local development — both the API and Nuxt run in Docker, but the browser runs on the host machine:

# Browser reaches the API through the exposed Docker port
NUXT_PUBLIC_API_URL=http://localhost:8080
# Node SSR reaches the API directly inside the Docker network
NUXT_SERVER_API_URL=http://api:8080

Cloud/Kubernetes — keep SSR traffic inside the cluster network:

NUXT_PUBLIC_API_URL=https://api.example.com
NUXT_SERVER_API_URL=http://api.internal

When NUXT_SERVER_API_URL is absent, both SSR and browser use NUXT_PUBLIC_API_URL. The server URL is never exposed to the client bundle.

Warning: NUXT_SERVER_API_URL must only be used for data fetching. Never use it to build URLs that are rendered in HTML (image src, anchor href, etc.): server and client would produce different values, causing Vue hydration mismatches. Rendered URLs always use NUXT_PUBLIC_API_URL.

Image

Images

Nuxt Image is configured with the Intervention Request provider. Docs: https://image.nuxt.com/

SVG

Import an SVG as a component:

<script setup lang="ts">
import IconCheck from '~/assets/images/icons/check.svg?component'
</script>

<template>
    <IconCheck />
</template>

For icons, use VIcon with assets in app/assets/images/icons.

Maintenance

The maintenance build generates a static page:

pnpm generate:maintenance

Monitoring

Sentry is configured via NUXT_PUBLIC_SENTRY_DSN.

Sitemap

Sitemap is generated by @nuxtjs/sitemap with /api/sitemap as a source.

Docker build

Node build:

docker buildx build --target node-prod -t nuxt-starter/node .

Full build with bake:

docker buildx bake

Contributing

See CONTRIBUTING.md.