A production-ready Nuxt 4 starter template with TypeScript, Tailwind CSS v4, NuxtUI v4, Better Auth and modern tooling. The app lives in nuxt-base-template/; this repository root only carries the release tooling.
New projects are scaffolded by the lenne.Tech CLI, which clones the current template from this repository:
npm install -g @lenne.tech/cli
# Frontend only
lt frontend nuxt --name my-awesome-project
# Or a fullstack monorepo (API + this app)
lt fullstack initThen cd into the project and run pnpm run dev. The development server starts at http://localhost:3001.
npx create-nuxt-baseis retired. The npm package stopped receiving releases at 2.7.0 and still ships that old template; use the lt CLI instead.
| Technology | Version | Description |
|---|---|---|
| Nuxt | 4.x | Vue 3 meta-framework with SSR support |
| TypeScript | 6.0.x | Strict type checking enabled |
| Tailwind CSS | 4.x | Utility-first CSS with Vite plugin |
| NuxtUI | 4.x | Component library with dark mode |
Complete authentication system using Better Auth:
| Feature | Description |
|---|---|
| Email/Password | Standard auth with client-side SHA256 hashing |
| Two-Factor (2FA) | TOTP-based 2FA with backup codes |
| Passkey/WebAuthn | Passwordless authentication (Touch ID, Face ID, etc.) |
| Password Reset | Email-based password reset flow |
| Session Management | SSR-compatible cookie-based sessions |
Pre-built auth pages: login, register, forgot-password, reset-password, 2fa
📖 See AUTH.md for detailed documentation
| Package | Purpose |
|---|---|
| Pinia | State management |
| VueUse | Vue composition utilities |
| @hey-api/client-fetch | Type-safe API client |
| Valibot | Schema validation for forms |
- @nuxtjs/seo - Sitemap, robots.txt, Schema.org (OG images, AI Ready and Skew Protection are off by default)
- @nuxtjs/plausible - Privacy-friendly analytics, off unless an analytics host is set explicitly
| Tool | Purpose |
|---|---|
| OxLint | Fast linting |
| OxFmt | Code formatting |
| Playwright | E2E testing |
| @lenne.tech/bug.lt | Bug reporting to Linear (dev only) |
| dayjs-nuxt | Date/time handling |
- TUS resumable upload support (
tus-js-client) - Pre-built
TusFileUpload.vuecomponent
- Multi-stage production
Dockerfile(non-root runner, self-contained Nitro output) - Built from the monorepo root as build context:
docker build -f projects/app/Dockerfile . - Build identity injected at runtime via
NUXT_PUBLIC_APP_COMMIT HEALTHCHECKonGET /; container listens on port 3000 (compose maps host 3001 → 3000)- Local development runs via
lt dev up, not in a container - Migrating an existing fork? See
migration-guides/2.11.0-docker-workflow.md
my-project/
├── app/
│ ├── assets/css/ # Tailwind CSS
│ ├── components/ # Vue components (auto-imported)
│ │ ├── Modal/ # Modal components
│ │ ├── Transition/ # Transition components
│ │ └── Upload/ # File upload components
│ ├── composables/ # Composables (auto-imported)
│ ├── interfaces/ # TypeScript interfaces
│ ├── layouts/ # Nuxt layouts
│ ├── lib/ # Auth client configuration
│ ├── middleware/ # Route middleware (auth, admin, guest)
│ ├── pages/ # File-based routing
│ │ ├── auth/ # Authentication pages
│ │ └── app/ # Protected app pages
│ ├── utils/ # Utility functions
│ └── app.config.ts # NuxtUI configuration
├── docs/ # Developer docs (Markdown, not served)
├── tests/ # Playwright E2E tests
├── nuxt.config.ts # Nuxt configuration
├── openapi-ts.config.ts # API type generation config
└── playwright.config.ts # E2E test configuration
| Script | Description |
|---|---|
pnpm run dev |
Start development server |
pnpm run build |
Build for production |
pnpm run preview |
Preview production build |
pnpm run generate-types |
Generate TypeScript types from OpenAPI |
pnpm run test |
Run Playwright E2E tests |
pnpm run lint |
Run OxLint |
pnpm run format |
Run OxFmt |
pnpm run check |
Run lint + format check |
pnpm run fix |
Auto-fix lint + format issues |
Create a .env file based on .env.example:
Note the NUXT_ / NUXT_PUBLIC_ prefixes — Nitro maps only prefixed variables onto
runtimeConfig, so an unprefixed SITE_URL reaches nothing.
# Required
NUXT_PUBLIC_SITE_URL=http://localhost:3001
NUXT_API_URL=http://localhost:3000
NUXT_PUBLIC_API_URL=http://localhost:3000
NUXT_PUBLIC_APP_ENV=local
NODE_ENV=development
# Optional
NUXT_PUBLIC_WEB_PUSH_KEY= # Web push notifications
NUXT_PUBLIC_STORAGE_PREFIX=base-dev # Local storage prefix
LINEAR_API_KEY= # Bug reporting
LINEAR_TEAM_NAME= # Bug reporting
LINEAR_PROJECT_NAME= # Bug reportingNUXT_PUBLIC_SITE_URL must be set on every non-local stage. It is the public
origin of the app itself, and it feeds two things: the SEO site config (canonical
URLs, OG tags, sitemap) and the absolute redirect URLs that go into password-reset
and e-mail-verification mails. Left unset in production, the SEO half falls back to
the request's X-Forwarded-Host and the auth half falls back to whichever origin the
browser happens to be on — correct for a single-origin deployment, wrong behind a
proxy or vanity domain, where users receive links pointing at the internal host.
Use the NUXT_PUBLIC_ form, not NUXT_SITE_URL: both reach the SEO config, but only
the public form also populates runtimeConfig.public.siteUrl for the auth redirects.
The starter carries the version of the @lenne.tech/nuxt-extensions release it pins: starter
4.0.0 is the template for nuxt-extensions 4.0.0. Every nuxt-extensions release gets its starter
release with the same number. Changes to the starter alone do not change its version; they land
on main, which lt fullstack init clones, and appear in the changelog of the next release.
The numbers follow nuxt-extensions' schema:
| Part | Meaning |
|---|---|
| MAJOR | The Nuxt major the release targets (4.x.x = Nuxt 4) |
| MINOR | A change a project has to migrate; the migration guide says how |
| PATCH | A fix or an addition a project can take over without any change |
The switch to this schema skips numbers: the starter goes from 2.38.5 to 4.0.0, and
nuxt-extensions from 1.28.0 to 4.0.0. There is no starter 3.x and no nuxt-extensions 2.x or 3.x.
The migration guides in migration-guides/ are named after the starter
version they lead to.
- Node.js ^22.22.3 or ^24.15.0 (the floor of Nuxt 4.6 and @nuxtjs/seo 6)
- pnpm 11 (pinned through
packageManager)
MIT