Vue.js: SSR/SSG & Nuxt

A traditional Vue SPA (CSR):
  1. The browser requests → receives an empty HTML shell (<div id="app"></div>)
  2. Downloads JS (500KB)
  3. Executes JS (Vue boots)
  4. Renders the content
  5. The user sees the content
  
  First screen: 3-5 seconds
  SEO: Google cannot see the content (the SPA content is rendered by JS)

Nuxt 3 SSR:
  1. The browser requests → the server renders the complete HTML
  2. Returns HTML that already contains the content (0.5s first screen)
  3. Downloads JS (needed for hydration)
  4. The client "activates" (takes over interactivity)
  
  First screen: 0.5 seconds
  SEO: ✅ Perfect (the HTML contains the content)

// server/api/products.js (Nuxt 3 automatic routing)
export default defineEventHandler(async (event) => {
  return await $fetch('https://api.example.com/products')
})

First render: region ① shows the server-built <ul> string (two li elements), region ② shows the same two products rendered by Vue — the tag hierarchy matches exactly.
The console prints both results: the string and the outerHTML line up, which is why the browser can paint the SSR result immediately and then let Vue take over (hydrate).
Click "add $10 to every price": region ② shows 109 / 139 while region ① stays put (it is the previous server response); click "Simulate a page reload" and the two line up again.

npx nuxi@latest init my-nuxt-app
cd my-nuxt-app
npm install
npm run dev  # defaults to http://localhost:3000

my-nuxt-app/
├── assets/              # Assets (images, fonts)
│   └── css/
│       └── main.css
├── components/          # Shared components
│   ├── AppHeader.vue
│   └── AppFooter.vue
│   └── product/
│       └── ProductCard.vue  # Nested directories are auto-registered
├── composables/         # Composables
│   └── useAuth.ts
├── layouts/             # Layouts
│   ├── default.vue      # Default layout
│   └── admin.vue        # Admin layout
├── middleware/          # Route middleware
│   └── auth.ts
├── pages/               # File routing (generated automatically)
│   ├── index.vue        # /
│   ├── about.vue       # /about
│   ├── products/
│   │   ├── index.vue    # /products
│   │   └── [id].vue     # /products/:id
│   └── admin/
│       └── index.vue    # /admin
├── plugins/             # Nuxt plugins
│   └── pinia.ts
├── public/              # Static assets
├── server/              # Server-side code
│   ├── api/             # API routes (registered automatically)
│   │   └── products.ts  # /api/products
│   └── middleware/      # Server middleware
├── stores/              # Pinia stores
├── app.vue              # Root component
├── nuxt.config.ts       # Nuxt config
└── package.json

pages/index.vue           → /
pages/about.vue          → /about
pages/products/index.vue → /products
pages/products/[id].vue  → /products/:id
pages/admin/index.vue    → /admin

<script setup lang="ts">
// useFetch runs on the server during SSR and on the client during CSR
const { data, pending, error, refresh } = await useFetch('/api/products')

// The 5 returned values
// data: the response data
// pending: loading state
// error: error information
// refresh: a method to refetch
// status: the status code
</script>

<script setup lang="ts">
const { data } = await useAsyncData('products', () => 
  $fetch('/api/products')
)

// Options: cache, dependencies, transform
const { data: users } = await useAsyncData(
  'users',
  () => $fetch('/api/users'),
  {
    cache: 'force-cache',  // force caching
    default: () => []      // default value
  }
)
</script>

<script setup lang="ts">
// useState replaces ref (SSR-friendly)
const cart = useState('cart', () => ({ items: [], total: 0 }))

// Mutating
cart.value.items.push(product)
</script>

// 1. useFetch: server-side data prefetching
const { data } = await useFetch('/api/products')

// 2. useAsyncData: general-purpose async data
const { data } = await useAsyncData('key', fetcher)

// 3. useState: global state (SSR-friendly)
const user = useState('user', () => null)

// 4. useRoute: the current route
const route = useRoute()

// 5. useRuntimeConfig: runtime configuration
const config = useRuntimeConfig()

export default defineNuxtConfig({
  // 1. Modules
  modules: [
    '@nuxtjs/tailwindcss',
    '@pinia/nuxt',
    '@vueuse/nuxt'
  ],
  
  // 2. CSS
  css: ['~/assets/css/main.css'],
  
  // 3. Runtime configuration
  runtimeConfig: {
    apiSecret: 'xxx',  // server-side
    public: {
      apiBase: 'https://api.example.com'  // client-side
    }
  },
  
  // 4. Rendering mode
  ssr: true,  // enable SSR
  
  // 5. App configuration
  app: {
    head: {
      title: 'My App',
      meta: [
        { name: 'description', content: 'My app description' }
      ]
    }
  }
})

<script setup lang="ts">
// ✅ Nuxt auto-imports:
// - Vue 3 APIs (ref, computed, watch)
// - Nuxt 3 composables (useFetch, useState)
// - Components (components/ directory)
// - The utils/ directory

const count = ref(0)
const { data } = await useFetch('/api/products')
</script>

<script setup lang="ts">
useHead({
  title: 'iPhone 15 Pro - My Shop',
  meta: [
    { name: 'description', content: 'Buy iPhone 15 Pro at best price' },
    { property: 'og:title', content: 'iPhone 15 Pro' },
    { property: 'og:image', content: '/iphone.jpg' }
  ]
})
</script>

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/tailwindcss',  // Tailwind CSS integration
    '@pinia/nuxt',          // Pinia state management
    '@vueuse/nuxt',         // VueUse utilities
    '@nuxt/image',          // Image optimization
    'nuxt-icon'             // Icon system
  ]
})

Nuxt installs and registers all five modules, then logs each one during startup:

[Nuxt] ℹ Installing modules...
[Nuxt] ✔ @nuxtjs/tailwindcss
[Nuxt] ✔ @pinia/nuxt
[Nuxt] ✔ @vueuse/nuxt
[Nuxt] ✔ @nuxt/image
[Nuxt] ✔ nuxt-icon
[Nuxt] ✔ Vite server built in 3.2s

my-nuxt-app/
├── pages/            # File routing (generated automatically)
├── components/       # Auto-registered components
├── composables/      # Auto-imported
├── server/api/       # API routes (server-side)
├── server/middleware/
├── middleware/       # Client middleware
├── plugins/          # Nuxt plugins
├── layouts/          # Layouts
└── nuxt.config.ts    # Nuxt config

On startup Nuxt scans these directories and wires everything up automatically, printing the generated routes:

[Nuxt] ℹ Vite server warmed up in 412ms
[Nuxt] ✔ Auto-imports ready (vue, nuxt, components, composables)
[Nuxt] ✔ Routes generated:
  /              → pages/index.vue
  /about         → pages/about.vue
  /products      → pages/products/index.vue
  /products/:id  → pages/products/[id].vue
  /api/products  → server/api/products.ts

The block renders as a two-column reference table listing the five composables and their roles:

API                 Purpose
------------------  --------------------------------------------------
useFetch            Server-side data prefetching (SSR-friendly)
useAsyncData        General-purpose async data fetching
useState            Global state (SSR-friendly, auto-serialized)
useRoute            Current route information
useRuntimeConfig    Runtime configuration

The block renders as a two-column table that maps each scenario to the matching Nuxt mode:

Scenario       Nuxt approach
-------------  -----------------
Content site   SSG (nuxi generate)
E-commerce     SSR (default)
Admin          CSR (ssr: false)
Full stack     Nuxt + server/api
Static blog    SSG + Markdown

The block renders as a five-row troubleshooting table for the most frequent Nuxt pitfalls:

Error                        Symptom              Solution
---------------------------  -------------------  ------------------------------
useFetch data does not show  Missing await        const { data } = await ...
SSR hydration fails          Data mismatch        useState instead of ref
Routing does not work        Wrong file path      Put the file in pages/
Module installation fails    Wrong name           Check the modules spelling
SEO cannot see the page      ssr: false           Enable SSR