# Nuxt

## Getting Started

## Create a connection

1. Sign in to [OpenGraph+](/)
2. Go to your website's **Meta Tags** page
3. Create a new connection and copy your connection URL

Your connection URL looks like `https://$OGPLUS_KEY.ogplus.net`.

## Find your layout

**App-level:** `app.vue` is the entry point for your Nuxt app.

**Layouts:** `layouts/default.vue` wraps pages that use the default layout.

Either location works for site-wide meta tags.

## Add Open Graph meta tags

Use `useSeoMeta` in your layout to set default Open Graph tags site-wide. These control how your pages appear when shared on Twitter, Slack, LinkedIn, and other platforms.

```vue
<!-- app.vue or layouts/default.vue -->
<script setup>
const route = useRoute()

useSeoMeta({
  ogTitle: 'My Site',
  ogDescription: 'Welcome to my site',
  ogUrl: `https://mysite.com${route.path}`,
  ogSiteName: 'My Site',
  ogType: 'website',
  ogImage: `https://$OGPLUS_KEY.ogplus.net${route.path}`,
  twitterCard: 'summary_large_image',
})
</script>
```

Replace `https://$OGPLUS_KEY.ogplus.net` with your connection URL, and `"My Site"` with your actual site name.

### What each tag does

| Tag | Purpose |
|-----|---------|
| `og:title` | The title shown in the link preview |
| `og:description` | The description shown below the title |
| `og:url` | The canonical URL of the page |
| `og:site_name` | Your website's name |
| `og:type` | Content type (`website`, `article`, `product`) |
| `og:image` | The social card image (powered by OpenGraph+) |
| `twitter:card` | Tells Twitter to show a large image card |

## Dynamic tags for pages

Call `useSeoMeta` in page components to override the layout defaults with data from your API.

### Blog posts

```vue
<!-- pages/posts/[slug].vue -->
<script setup>
const { data: post } = await useFetch(`/api/posts/${useRoute().params.slug}`)

useSeoMeta({
  ogTitle: post.value.title,
  ogDescription: post.value.excerpt,
  ogType: 'article',
  ogImage: `https://$OGPLUS_KEY.ogplus.net/posts/${useRoute().params.slug}`,
  twitterCard: 'summary_large_image',
})
</script>
```

### Products

```vue
<!-- pages/products/[id].vue -->
<script setup>
const { data: product } = await useFetch(`/api/products/${useRoute().params.id}`)

useSeoMeta({
  ogTitle: product.value.name,
  ogDescription: `$${product.value.price} — ${product.value.description}`,
  ogType: 'product',
  ogImage: `https://$OGPLUS_KEY.ogplus.net/products/${useRoute().params.id}`,
  twitterCard: 'summary_large_image',
})
</script>
```

## Using useHead

`useHead` is an alternative that maps directly to HTML meta tag attributes:

```vue
<script setup>
const route = useRoute()

useHead({
  meta: [
    { property: 'og:title', content: 'My Site' },
    { property: 'og:description', content: 'Welcome to my site' },
    { property: 'og:url', content: `https://mysite.com${route.path}` },
    { property: 'og:site_name', content: 'My Site' },
    { property: 'og:type', content: 'website' },
    { property: 'og:image', content: `https://$OGPLUS_KEY.ogplus.net${route.path}` },
    { name: 'twitter:card', content: 'summary_large_image' },
  ]
})
</script>
```

Both approaches work identically. `useSeoMeta` is the more idiomatic Nuxt 3 option.

## SSR note

Nuxt renders on the server by default, so your meta tags will be present in the initial HTML response. No extra configuration needed for social crawlers to pick them up.

## Verify

Start your development server and view the page source. Check that all `og:` meta tags are present with the correct values.

Open the preview tool in your OpenGraph+ dashboard and paste a URL from your site to see the social card image.


## Customize

OpenGraph+ captures your page in a headless browser and renders it as an image. You control what gets captured using meta tags in your layout and CSS in your stylesheets.

All of the rendering options below are standard HTML meta tags and CSS, so they work the same regardless of framework. The [HTML, CSS, & HTTP guide](/docs/html-css) covers each one in detail. This page shows how to wire them into a Nuxt app.

## Meta tags

Add these to your layout alongside your `og:image` tag. They're all optional.

```vue
<!-- app.vue or layouts/default.vue -->
<script setup>
useHead({
  meta: [
    // Render at 800px wide instead of the default
    { property: 'og:plus:viewport:width', content: '800' },
    // Only capture this element instead of the full page
    { property: 'og:plus:selector', content: '.post-header' },
    // Inject inline styles on the captured element
    { property: 'og:plus:style', content: 'padding: 60px; background: #0f172a; color: white;' },
  ]
})
</script>
```

See the [Rendering](/docs/html-css/rendering) guide for what each meta tag does and how they interact.

## CSS styling

OpenGraph+ adds a `data-ogplus` attribute to your `<html>` element during capture. Use it in your stylesheets to hide navigation, adjust spacing, or restyle anything for the social card without affecting your actual site.

```css
/* assets/css/main.css */
html[data-ogplus] {
  nav { display: none; }
  footer { display: none; }
  .hero { padding: 60px; }
}
```

If you're using Tailwind, there's a plugin that gives you `ogplus:` variants like `ogplus:hidden` and `ogplus-twitter:bg-sky-500`. See [CSS Styling](/docs/html-css/data-attributes) for plain CSS examples and [Tailwind setup](/docs/html-css/data-attributes#tailwind-css).

## Templates

For fully custom social card layouts that pull content from your page, use `<template>` elements. These let you build a completely different layout for screenshots without touching your visible page.

```vue
<!-- layouts/default.vue -->
<template>
  <div>
    <slot />
    <component :is="'template'" id="ogplus">
      <div style="padding: 48px; background: #0f172a; color: white; height: 100%;">
        <h1 style="font-size: 48px;">
          ${document.querySelector('h1')?.textContent}
        </h1>
      </div>
    </component>
  </div>
</template>
```

See the [Templates](/docs/html-css/templates) guide for expression syntax, platform-specific templates, and full examples.

## Testing locally

The [Preview Bookmarklet](/docs/html-css/bookmarklet) sets the `data-ogplus` attribute in your browser so you can see how your CSS and Tailwind variants look without deploying or waiting for a real crawler to hit your page.

## Full example

A blog post page with all the pieces together:

```vue
<!-- pages/posts/[slug].vue -->
<script setup>
const { data: post } = await useFetch(`/api/posts/${useRoute().params.slug}`)

useSeoMeta({
  ogTitle: post.value.title,
  ogDescription: post.value.excerpt,
  ogType: 'article',
  ogImage: `https://$OGPLUS_KEY.ogplus.net/posts/${useRoute().params.slug}`,
  twitterCard: 'summary_large_image',
})

useHead({
  meta: [
    { property: 'og:plus:selector', content: '.post-header' },
    { property: 'og:plus:style', content: 'padding: 60px; background-color: #0f172a; color: white;' },
    { property: 'og:plus:viewport:width', content: '800' },
  ]
})
</script>
```


## Caching

OpenGraph+ reads HTTP cache headers from your responses to decide when to re-render social card images. Nuxt gives you several ways to control these headers.

This page covers the Nuxt side. For how OpenGraph+ handles caching at the HTTP level, see the [HTTP Caching](/docs/html-css/caching) guide.

## Route rules

Set cache headers per route pattern in `nuxt.config.ts`:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/': { headers: { 'cache-control': 'public, max-age=3600' } },
    '/blog/**': { headers: { 'cache-control': 'public, max-age=86400' } },
    '/about': { headers: { 'cache-control': 'public, max-age=604800' } },
  }
})
```

This is the simplest way to control caching across your Nuxt app.

## Server middleware

For dynamic cache logic, use a server middleware:

```ts
// server/middleware/cache.ts
export default defineEventHandler((event) => {
  setResponseHeader(event, 'Cache-Control', 'public, max-age=3600')
})
```

Or set headers in specific server routes:

```ts
// server/api/posts/[slug].ts
export default defineEventHandler((event) => {
  setResponseHeader(event, 'Cache-Control', 'public, max-age=86400')
  // ...
})
```

## Static generation

If you're using `nuxt generate` for static site generation, your cache headers come from your hosting provider (Vercel, Netlify, Cloudflare Pages, etc.). Configure headers through their respective config files.

For hybrid rendering with `prerender: true` on specific routes:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/blog/**': { prerender: true },
  }
})
```

Pre-rendered pages are served as static files. Cache headers depend on your hosting configuration.

## Meta tag overrides

If you can't control HTTP headers, use meta tags instead:

```vue
<script setup>
useHead({
  meta: [
    { property: 'og:plus:cache:max_age', content: '86400' },
    { property: 'og:plus:cache:etag', content: 'v1-about-page' },
  ]
})
</script>
```

See the [HTTP Caching guide](/docs/html-css/caching) for the full list of meta tag overrides.

## Purging cached images

When you need to force a refresh immediately, go to your website dashboard, find the page, and click purge. This clears the cached image and triggers a re-render on the next request.

## Recommendations

| Page type | Strategy |
|-----------|----------|
| Static pages (about, contact) | `cache-control: public, max-age=604800` (1 week) |
| Blog posts | `cache-control: public, max-age=86400` (1 day) |
| Index / listing pages | `cache-control: public, max-age=3600` (1 hour) |
| Dynamic / user content | No caching or short TTL |


## Troubleshooting

Something not working? Here are the most common issues and how to fix them.

## Meta tags not in page source

Nuxt 3 renders on the server by default, so `useHead` and `useSeoMeta` should produce meta tags in the initial HTML.

**Check:** View your page source, not DevTools. DevTools shows client-hydrated HTML. Page source shows what crawlers see.

If tags are missing, make sure `useHead` or `useSeoMeta` is called in a component that runs on the server, not inside a `<ClientOnly>` wrapper.

## Client-only components

Components wrapped in `<ClientOnly>` don't render on the server. If your meta tag logic is inside a client-only component, social crawlers won't see it.

Move `useHead` / `useSeoMeta` calls to the parent page or layout component instead.

## Wrong image showing

This is almost always a caching issue. Social platforms and OpenGraph+ both cache images.

1. Open the preview tool in your OpenGraph+ dashboard
2. Paste your URL to see what OpenGraph+ currently has
3. If the image is stale, purge it from the dashboard
4. Re-check with the preview tool

## Social platforms not updating

Twitter, LinkedIn, and Slack cache images aggressively on their end. After confirming the correct image appears in the OpenGraph+ preview tool:

- **Twitter:** Use the [Card Validator](https://cards-dev.twitter.com/validator) to force a refresh
- **LinkedIn:** Use the [Post Inspector](https://www.linkedin.com/post-inspector/) to clear their cache
- **Facebook:** Use the [Sharing Debugger](https://developers.facebook.com/tools/debug/) to scrape again

This is platform-side caching that OpenGraph+ cannot control.

## Purging cached images

1. Go to your website dashboard in OpenGraph+
2. Find the page you want to refresh
3. Click purge to clear the cached image

The next request from a social platform will trigger a fresh render.

## Testing

Use the preview tool in your OpenGraph+ dashboard to verify your setup before sharing URLs. This shows you exactly what social platforms will see.