Vue.js SPA SEO: how I made my app invisible to Google (and how I fixed it)

I spent three months building CitoyenNote — a Vue.js 3 + Vite SPA. Clean code, Composition API, composables for everything, Pinia for state management. The kind of codebase you're actually proud of. Then I typed the site name into Google and got back a single result: the homepage. With a title of "Document". No description. And none of the 80+ municipality pages were indexed.

That's the SPA SEO problem in a nutshell. Here's what I learned fixing it.

What Google actually sees in a SPA

A classic server-rendered page serves complete HTML on the first request. Google's crawler receives a full <head> with a title, meta description, canonical URL — everything it needs to index the page.

A Vue.js SPA in CSR mode serves this on every URL:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Document</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/assets/index-Bx9kLmQp.js"></script>
  </body>
</html>

Google's crawler does execute JavaScript — but with significant caveats: it uses an older Chromium version, JS rendering is deferred and lower priority than HTML crawling, and there's no guarantee of complete execution on every page. Relying on JS execution for SEO is a gamble. The fix is to give Google correct HTML right from the start.

The full solution requires six steps.

Step 1: get the index.html basics right

The static index.html at the root of your Vite project is the baseline every page will fall back to when JavaScript hasn't run yet. It should be respectable:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <title>CitoyenNote — Citizen reviews of French municipalities</title>
    <meta name="description" content="Read and share ratings and reviews about your municipality: safety, schools, public transport, urban planning. Unfiltered citizen feedback." />

    <!-- Open Graph -->
    <meta property="og:type" content="website" />
    <meta property="og:title" content="CitoyenNote — Citizen reviews of French municipalities" />
    <meta property="og:description" content="Read and share ratings and reviews about your municipality: safety, schools, public transport, urban planning." />
    <meta property="og:url" content="https://citoyennote.fr/" />
    <meta property="og:image" content="https://citoyennote.fr/og-image.jpg" />
    <meta property="og:locale" content="en_US" />

    <!-- Twitter Card -->
    <meta name="twitter:card" content="summary_large_image" />
    <meta name="twitter:title" content="CitoyenNote — Citizen reviews of French municipalities" />
    <meta name="twitter:description" content="Read and share ratings and reviews about your municipality." />
    <meta name="twitter:image" content="https://citoyennote.fr/og-image.jpg" />

    <link rel="canonical" href="https://citoyennote.fr/" />
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

This static fallback is what social media crawlers (Twitter, LinkedIn, Slack) will read when sharing your homepage — they rarely execute JavaScript.

Step 2: @unhead/vue for dynamic meta tags

For every route to have its own title and meta description, you need a library that manipulates the <head> reactively as the route changes. The current standard for Vue 3 is @unhead/vue, which replaces the older vue-meta.

Installation

npm install @unhead/vue

Setup in main.ts

import { createApp } from 'vue'
import { createHead } from '@unhead/vue'
import App from './App.vue'
import router from './router'

const app = createApp(App)
const head = createHead()

app.use(router)
app.use(head)
app.mount('#app')

Usage in a component

The simplest approach: call useHead() in each page component, with computed values that react to async data loading.

// views/MunicipalityView.vue
<script setup lang="ts">
import { computed } from 'vue'
import { useHead } from '@unhead/vue'
import { useMunicipality } from '@/composables/useMunicipality'

const props = defineProps<{ slug: string }>()
const { municipality, loading } = useMunicipality(props.slug)

useHead({
  title: computed(() =>
    municipality.value
      ? `${municipality.value.name} — CitoyenNote`
      : 'Loading... — CitoyenNote'
  ),
  meta: [
    {
      name: 'description',
      content: computed(() =>
        municipality.value
          ? `Citizen reviews of ${municipality.value.name} (${municipality.value.department}): overall score ${municipality.value.score}/10, ${municipality.value.reviewCount} reviews.`
          : 'Municipality reviews on CitoyenNote.'
      ),
    },
    {
      property: 'og:title',
      content: computed(() =>
        municipality.value ? `${municipality.value.name} — CitoyenNote` : 'CitoyenNote'
      ),
    },
    {
      property: 'og:description',
      content: computed(() =>
        municipality.value
          ? `Citizen reviews of ${municipality.value.name}: overall score ${municipality.value.score}/10.`
          : ''
      ),
    },
    {
      property: 'og:url',
      content: computed(() =>
        `https://citoyennote.fr/municipality/${props.slug}`
      ),
    },
    {
      property: 'og:type',
      content: 'article',
    },
  ],
  link: [
    {
      rel: 'canonical',
      href: computed(() => `https://citoyennote.fr/municipality/${props.slug}`),
    },
  ],
})
</script>

The key point: the values are computed(), so they update automatically when municipality.value is populated after the API call. No need to manually call anything when data arrives.

Extract into a composable

If you have many page types, avoid duplicating useHead() calls. Extract into a typed composable:

// composables/useMunicipalitySeo.ts
import { computed, type Ref } from 'vue'
import { useHead } from '@unhead/vue'
import type { Municipality } from '@/types'

export function useMunicipalitySeo(
  municipality: Ref<Municipality | null>,
  slug: string
) {
  useHead({
    title: computed(() =>
      municipality.value
        ? `${municipality.value.name} — CitoyenNote`
        : 'CitoyenNote'
    ),
    meta: [
      {
        name: 'description',
        content: computed(() =>
          municipality.value
            ? `Citizen reviews of ${municipality.value.name}: score ${municipality.value.score}/10, ${municipality.value.reviewCount} reviews.`
            : ''
        ),
      },
      {
        property: 'og:title',
        content: computed(() =>
          municipality.value ? `${municipality.value.name} — CitoyenNote` : 'CitoyenNote'
        ),
      },
      {
        property: 'og:url',
        content: `https://citoyennote.fr/municipality/${slug}`,
      },
    ],
    link: [{ rel: 'canonical', href: `https://citoyennote.fr/municipality/${slug}` }],
  })
}

Usage in the component becomes a single line:

useMunicipalitySeo(municipality, props.slug)

Step 3: robots.txt

Place a robots.txt at the root of your public/ folder — Vite will copy it as-is to the build output:

User-agent: *
Allow: /

Sitemap: https://citoyennote.fr/sitemap.xml

If parts of your app shouldn't be indexed (admin panels, user dashboards, private routes), block them explicitly:

User-agent: *
Disallow: /admin/
Disallow: /dashboard/
Disallow: /settings/
Allow: /

Sitemap: https://citoyennote.fr/sitemap.xml

Step 4: dynamic sitemap

A static sitemap only covers routes you know at build time. For a content-heavy app with thousands of municipality pages, the sitemap must be generated dynamically from the database.

In CitoyenNote's case, the backend is a Go API (Echo framework). I added a dedicated /sitemap.xml route:

// routes/sitemap.go
package routes

import (
    "encoding/xml"
    "net/http"
    "time"

    "github.com/labstack/echo/v4"
    "citoyennote/internal/repository"
)

type URLSet struct {
    XMLName xml.Name `xml:"urlset"`
    Xmlns   string   `xml:"xmlns,attr"`
    URLs    []URL    `xml:"url"`
}

type URL struct {
    Loc        string  `xml:"loc"`
    LastMod    string  `xml:"lastmod,omitempty"`
    ChangeFreq string  `xml:"changefreq,omitempty"`
    Priority   float64 `xml:"priority,omitempty"`
}

func SitemapHandler(repo repository.MunicipalityRepository) echo.HandlerFunc {
    return func(c echo.Context) error {
        municipalities, err := repo.ListAll(c.Request().Context())
        if err != nil {
            return err
        }

        urlset := URLSet{
            Xmlns: "http://www.sitemaps.org/schemas/sitemap/0.9",
        }

        // Static routes
        urlset.URLs = append(urlset.URLs,
            URL{Loc: "https://citoyennote.fr/", Priority: 1.0, ChangeFreq: "daily"},
            URL{Loc: "https://citoyennote.fr/search", Priority: 0.8, ChangeFreq: "weekly"},
        )

        // Dynamic municipality pages
        for _, m := range municipalities {
            urlset.URLs = append(urlset.URLs, URL{
                Loc:        "https://citoyennote.fr/municipality/" + m.Slug,
                LastMod:    m.UpdatedAt.Format(time.DateOnly),
                ChangeFreq: "weekly",
                Priority:   0.7,
            })
        }

        c.Response().Header().Set("Content-Type", "application/xml; charset=UTF-8")
        return xml.NewEncoder(c.Response()).Encode(urlset)
    }
}

No build step, no caching needed for this size. For a site with 100,000+ pages, consider splitting into a sitemap index and multiple sub-sitemaps (Google's limit is 50,000 URLs per sitemap file).

Submit the sitemap URL in Google Search Console and verify it parses correctly.

Step 5: JSON-LD structured data

JSON-LD is Google's preferred format for Schema.org structured data. It goes in a <script type="application/ld+json"> tag in the <head>. @unhead/vue handles this cleanly:

// Add to useMunicipalitySeo.ts
useHead({
  // ... existing title/meta config ...
  script: [
    {
      type: 'application/ld+json',
      innerHTML: computed(() => {
        if (!municipality.value) return ''

        return JSON.stringify({
          '@context': 'https://schema.org',
          '@type': 'Place',
          name: municipality.value.name,
          description: `Citizen reviews of ${municipality.value.name}.`,
          url: `https://citoyennote.fr/municipality/${slug}`,
          aggregateRating: {
            '@type': 'AggregateRating',
            ratingValue: municipality.value.score,
            reviewCount: municipality.value.reviewCount,
            bestRating: 10,
            worstRating: 0,
          },
        })
      }),
    },
  ],
})

The AggregateRating type is what enables star ratings to appear directly in Google search results (rich snippets). Not guaranteed, but Google does pick it up reliably for well-structured pages with enough reviews.

For a blog or article, use @type: "BlogPosting" with datePublished, dateModified, and author. For a product, use @type: "Product". The Google structured data gallery lists all types that qualify for rich results.

Step 6: the 404 route

A SPA with client-side routing needs a server-level fallback. Without it, directly navigating to /municipality/paris returns a real 404 from the server before Vue even loads. Google interprets that as a 404 and won't index the page.

The fix depends on your hosting. On Apache:

# .htaccess at the root of your SPA
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /

  # Don't rewrite real files and directories
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d

  # Everything else goes to index.html
  RewriteRule ^ index.html [L]
</IfModule>

On Nginx:

location / {
    try_files $uri $uri/ /index.html;
}

On Vite's dev server, this works automatically. On production, it's on you.

Inside Vue Router, add a catch-all route that returns a proper 404 UI — and critically, set the HTTP status code. With SSR or prerendering this is straightforward. With pure CSR, the HTTP response for a non-existent route is always 200 (the server returns index.html). Google handles this gracefully for most cases, but it's worth knowing.

// router/index.ts
const routes = [
  // ... your routes ...
  {
    path: '/:pathMatch(.*)*',
    name: 'NotFound',
    component: () => import('@/views/NotFoundView.vue'),
  },
]

The honest limitation: CSR vs SSR

All of the above makes a CSR SPA considerably more Google-friendly. But there's a ceiling.

Google's crawler does execute JavaScript, but it does so in a second wave, hours or days after the initial crawl. The initial crawl reads raw HTML. So what Google sees first is your static index.html — the same fallback on every URL — with no route-specific content.

If your site depends on search visibility for hundreds or thousands of distinct pages (municipality pages, product pages, article pages), you have two real options:

SSR (Server-Side Rendering): Nuxt 3 for Vue.js. The server renders the full HTML for each request. Google gets the right HTML immediately. The cost: a Node.js server, more complex infrastructure, hydration to manage.
SSG (Static Site Generation): Nuxt or VitePress can pre-render all routes at build time to static HTML files. Perfect for content that doesn't change per-user. The cost: dynamic content (user-specific data, real-time scores) needs hydration after the static shell loads.

For CitoyenNote, I stayed with CSR + the fixes above because the content (municipality scores, reviews) changes frequently and Google does eventually index the JavaScript-rendered pages correctly. The SEO improvement from the fixes was significant: 80+ pages indexed within two weeks of the sitemap submission, versus zero before.

If I were starting again from scratch on a project where SEO is the primary acquisition channel, I'd go with Nuxt 3 from day one.

SEO checklist for Vue.js SPAs

A summary you can run through before launching:

index.html: complete <head> with charset, viewport, default title, meta description, Open Graph tags, Twitter Card, canonical URL
@unhead/vue: installed, registered in main.ts, useHead() called in every page component with computed reactive values
Canonical URLs: set on every page, including the homepage
robots.txt: present in public/, includes Sitemap: directive
Sitemap: all indexable URLs listed, dynamic pages included, submitted to Google Search Console
JSON-LD: relevant schema type on key pages (Place, Product, BlogPosting, Organization...)
Server fallback: .htaccess or Nginx config routes all paths to index.html
404 route: catch-all route defined in Vue Router
Google Search Console: sitemap submitted, URL inspection run on a sample of key pages, coverage report checked after 2 weeks
Social sharing test: Facebook Debugger and Twitter Card Validator on at least 3 URLs (homepage, a content page, a 404)

None of this is particularly complicated. The painful part is discovering three months into a project that you forgot to do it. The checklist exists so you don't have to rediscover it the hard way.

推荐订阅源

DEV Community