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/vueSetup 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.xmlIf 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.xmlStep 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/, includesSitemap: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:
.htaccessor Nginx config routes all paths toindex.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.