🚀 Martin's Nuxt Starter

A modern, full-featured Nuxt 4 starter template with TypeScript, Tailwind CSS, and everything you need to build amazing web applications.

🌐 Live Demo • 📖 Documentation • 🚀 Quick Start

---

✨ Features

🎯 Core Technologies

• 🔥 Nuxt 4 - The latest version of the Vue.js framework
• 📘 TypeScript - Full type safety with vue-tsc
• 🍹 Pinia Colada - Async state management & data fetching
• 🚀 pnpm - Fast, disk space efficient package manager
• 🎨 Tailwind CSS v4 - Modern utility-first CSS framework
• ⚡ Vite - Lightning fast build tool
• 🌍 Internationalization - i18n support with @nuxtjs/i18n

🧩 UI & Components

• 🎨 Nuxt UI v4 - Beautiful, accessible components
• 🌙 Color Mode - Dark/light theme support
• 🖼️ Icons - Comprehensive icon system (@nuxt/icon)
• 🔤 Fonts - Web font optimization (@nuxt/fonts)
• 🖼️ Images - Advanced image optimization (nuxt-image)
• 📱 Modals & Toasts - Ready-to-use overlay components

🔧 Developer Experience

• 📋 ESLint v9 - Code linting with @nuxt/eslint & @antfu/eslint-config
• 🔄 VueUse v13 - Essential Vue composition utilities
• 📚 Storybook - Component development and documentation
• 🧪 Vitest - Fast unit testing with coverage
• 🎭 Playwright - End-to-end testing
• 🔒 Security - Built-in security headers (nuxt-security)

🚀 CI/CD & Quality

• 📝 Commitlint - Conventional commit messages
• 🪝 Git Hooks - Pre-commit validation
• 🔍 Lint Staged - Lint only changed files
• ⚙️ GitHub Actions - Automated testing and deployment

---

🚀 Quick Start

Prerequisites

• Node.js (see .nvmrc for version) - Use NVM for version management
• pnpm - Install globally: npm install -g pnpm

Installation

# Use the correct Node version
nvm use

# Install dependencies
pnpm install

# Start development server
pnpm dev

Available Scripts

Command	Description
pnpm dev	🚀 Start development server
pnpm build	🏗️ Build for production
pnpm generate	📦 Generate static site
pnpm preview	👁️ Preview production build
pnpm test:unit	🧪 Run unit tests
pnpm test:unit-coverage	📊 Run unit tests with coverage
pnpm test:unit-ui	🖥️ Run unit tests with UI
pnpm test:e2e	🎭 Run E2E tests
pnpm test:e2e-ui	🖥️ Run E2E tests with UI
pnpm test:codegen	🎬 Generate E2E tests
pnpm lint	🔍 Lint code
pnpm lint:fix	🔧 Lint and fix code
pnpm typecheck	📘 Type checking

---

📁 Project Structure

my-nuxt-starter/
├── 📁 app/                    # Main application
│   └── 📁 assets/             # Static assets
│   ├── 📁 components/         # Vue components
│   ├── 📁 composables/        # Vue composables
│   ├── 📁 layouts/            # Layout components
│   ├── 📁 pages/              # Page components
├── 📁 tests/                  # Test files
│   └── 📁 e2e/                # End-to-end tests
├── 📁 server/                 # Server-side code
├── 📁 public/                 # Public static files
└── 📄 nuxt.config.ts          # Nuxt configuration

---

🍹 Data Fetching (Pinia Colada)

This project uses Pinia Colada for async state management. It provides caching, deduplication, and invalidation out of the box.

Basic Usage

Use useQuery to fetch data:

<script setup lang="ts">
const { state, asyncStatus } = useQuery({
  key: ['products'],
  query: () => fetch('/api/products').then(r => r.json())
})
</script>

<template>
  <div v-if="asyncStatus === 'loading'">Loading...</div>
  <div v-else-if="state.error">Error: {{ state.error }}</div>
  <div v-else>
    {{ state.data }}
  </div>
</template>

Mutations

Use useMutation to modify data:

<script setup lang="ts">
const { mutate } = useMutation({
  mutation: (newProduct) => fetch('/api/products', {
    method: 'POST',
    body: JSON.stringify(newProduct)
  })
})
</script>

For more details, check the Pinia Colada documentation.

---

💻 Development

Commit Guidelines

Follow the Conventional Commits specification:

<type>: <description>

Types: feat, fix, docs, style, refactor, test, chore, ci, build, perf, revert

Examples:

• feat: add user authentication
• fix: resolve navbar responsive issue
• docs: update installation guide

Unit Test

# Run unit tests
pnpm test:unit

# Run unit tests with coverage
pnpm test:unit-coverage

# Run unit tests with ui
pnpm test:unit-ui

E2E Test

# Install Playwright browsers (required for E2E tests)
pnpm exec playwright install

# Run E2E tests
pnpm test:e2e

# Run E2E tests with ui
pnpm test:e2e-ui

# Run codegen for E2E tests
pnpm test:codegen

🤖 Testing GitHub Actions Locally

We suggest using act to try GitHub Actions locally before pushing to GitHub. This allows you to validate your workflows and save time by running them in a local containerized environment.

📋 Roadmap

🔄 In Progress

• 🎨 Custom Icon Library - Project-specific icons
• 📊 Coverage GitHub Action - Automated coverage reports

🎯 Planned Features

• 🔍 Zod - Runtime type validation
• 🎨 Chromatic - Visual testing
• 🚦 Lighthouse - Performance monitoring

---

🛠️ Troubleshooting

Having issues? Try these steps:

1. 🧹 Clean the project: pnpm clean-project
2. 📋 Check Node version: Ensure you're using the version specified in .nvmrc
3. 📦 Check pnpm version: Verify it matches the version in package.json
4. 🔄 Reinstall dependencies: rm -rf node_modules && pnpm install
5. 🔧 Check environment: Ensure all required environment variables are set

---

🤝 Contributing

We welcome contributions! Please read our Contributing Guidelines before submitting a pull request.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License.

---

🙏 Acknowledgments

Built with ❤️ using amazing open-source projects:

• Nuxt
• Vue.js
• Tailwind CSS
• TypeScript
• pnpm

---

⚠️ Tailwind CSS Linting (Beta)

Please note that ESLint support for Tailwind CSS is currently in beta due to the ongoing development of Tailwind CSS v4. If you encounter any issues or false positives, you can disable this feature by modifying the eslint.config.mjs file or temporarily disabling the specific rules.

---

🌟 Star this repository if you find it helpful!