nuxt-og-image 2.0.0-beta.4 → 2.0.0-beta.41

package/README.md

@@ -13,7 +13,7 @@
 Enlightened OG Image generation for Nuxt 3.
 </p>
 
-<img src="https://repository-images.githubusercontent.com/578125755/05ce0b00-ef15-48d0-94b5-b999373a20f9">
+<img src="https://repository-images.githubusercontent.com/578125755/90f77ca8-95be-4e06-9600-332afe1ba24f">
 
 <p align="center">
 <table>
@@ -38,7 +38,7 @@ Enlightened OG Image generation for Nuxt 3.
 - ▲ Render using [Satori](https://github.com/vercel/satori): Tailwind classes, Google fonts, emoji support and more!
 - 🤖 Or prerender using the Browser: Supporting painless, complex templates
 - 📸 Feeling lazy? Just generate screenshots for every page: hide elements, wait for animations, and more
-- ⚙️ Works on the edge: Vercel Edge and Cloudflare Workers
+- ⚙️ Works on the edge: Vercel Edge, Netlify Edge and Cloudflare Workers
 
 ## Demos
 
@@ -46,13 +46,33 @@ Enlightened OG Image generation for Nuxt 3.
 - [StackBlitz - Minimal Playground Example](https://stackblitz.com/edit/nuxt-starter-pxs3wk?file=pages/index.vue)
 - [StackBlitz - Alpine Theme](https://stackblitz.com/edit/github-hgunsf?file=package.json)
 
+## Runtime Provider Compatibility
+
+Both Satori and Browser will work in Node based environments. Prerendering is fully supported.
+
+When you want to generate dynamic images at runtime there are certain Nitro runtime limitations.
+
+| Provider                                                                        | Satori   | Browser |
+|---------------------------------------------------------------------------------|----------|---------|
+| Node                                                                            | ✅        | ✅       |
+| [Vercel](https://nuxt-og-image-playground.vercel.app/)                          | ✅        | ❌    |
+| [Vercel Edge](https://nuxt-og-image-playground-gkdt.vercel.app/)                | ✅        | ❌       |
+| [Cloudflare Pages](https://nuxt-og-image-playground.pages.dev/)                 | ✅        | ❌       |
+| [Netlify](https://nuxt-og-image-playground-netlify.netlify.app/)                | Soon     | ❌       |
+| [Netlify Edge](https://nuxt-og-image-playground-netlify-edge.netlify.app/)      | ❌ (Soon) | ❌       |
+| [StackBlitz](https://stackblitz.com/edit/nuxt-starter-pxs3wk?file=package.json) | ✅        | ❌       |
+
+Other providers are yet to be tested. Please create an issue if your nitro preset is not listed.
+
 ## Install
 
+Note: The `main` branch is documentation for the beta version, it's recommended to use this version.
+
 ```bash
 # Install module
-npm install --save-dev nuxt-og-image
+npm install --save-dev nuxt-og-image@beta
 # Using yarn
-yarn add --dev nuxt-og-image
+yarn add --dev nuxt-og-image@beta
 ```
 
 ## Setup
@@ -71,27 +91,6 @@ export default defineNuxtConfig({
 
 This feature uses Nuxt Islands, which requires Nuxt >= 3.1.
 
-### Add your host name
-
-The `og:image` meta tag requires the full URL, so you must provide your site host.
-
-_nuxt.config.ts_
-
-```ts
-export default defineNuxtConfig({
-  // Recommended
-  runtimeConfig: {
-    public: {
-      siteUrl: process.env.NUXT_PUBLIC_SITE_URL || 'https://example.com',
-    }
-  },
-  // OR
-  ogImage: {
-    host: 'https://example.com',
-  },
-})
-```
-
 # Guides
 
 ## Your first Satori `og:image`
@@ -241,6 +240,78 @@ Out of the box, this module provides support for the following:
 
 If you find Satori is too limiting for your needs, you can always use the `browser` provider to capture browser screenshots instead.
 
+## SSG Images
+
+When using `nuxt generate`, you will need to provide some additional configuration.
+
+- You must provide a `siteUrl` so that the meta tags can be generated correctly as absolute URLs.
+
+```ts
+export default defineNuxtConfig({
+  // Recommended
+  runtimeConfig: {
+    public: {
+      siteUrl: process.env.NUXT_PUBLIC_SITE_URL || 'https://example.com',
+    }
+  },
+  // OR
+  ogImage: {
+    host: 'https://example.com',
+  },
+})
+```
+
+- You must prerender all pages that use `og:image`.
+
+```ts
+export default defineNuxtConfig({
+  nitro: {
+    prerender: {
+      crawlLinks: true, // recommended  
+      routes: [
+        '/',
+        // list all routes that use og:image if you're not using crawlLinks
+        '/about',
+        '/blog',
+        '/blog/my-first-post',
+      ]
+    }
+  }
+})
+```
+
+## SSR Images
+
+When using `nuxt build`, you can only use the `browser` provider with the `node` Nitro preset.
+
+If you intend to use the `browser` provider in production, make sure you include the `playwright` dependency.
+
+  ```bash
+  npm i playwright
+  ```
+
+You can get around this by prerendering any pages that use `og:image`. Note that dynamic browser generated images are not supported at all,
+you should use the Satori provider.
+
+
+```ts
+export default defineNuxtConfig({
+  nitro: {
+    prerender: {
+      crawlLinks: true, // recommended  
+      routes: [
+        '/',
+        // list all routes that use og:image if you're not using crawlLinks
+        '/about',
+        '/blog',
+        '/blog/my-first-post',
+      ]
+    }
+  }
+})
+```
+
+
 ## Taking screenshots
 
 If you want to simply take a screenshot of your page, you can use the `OgImageScreenshot` component or `defineOgImageScreenshot` composable.
@@ -282,6 +353,135 @@ _package.json_
 }
 ```
 
+## Custom Fonts / Supporting non-english characters
+
+When creating your OG Image, you'll probably want to use a font custom to your project. 
+
+To make this easier for you, Google Fonts are loaded by default with Inter 400 and Inter 700. 
+
+You can easily load different Google Fonts by using their name+weight. For example:
+
+```ts
+export default defineNuxtConfig({
+  ogImage: {
+    fonts: [
+      // will load the Noto Sans font from Google fonts
+      'Noto+Sans:400'
+    ]
+  }
+})
+```
+
+This also lets you support non-english characters by adding the appropriate font to your config.
+
+For example, to support Hebrew characters, you can use the config:
+
+```ts
+export default defineNuxtConfig({
+  ogImage: {
+      fonts: [
+        // will load this font from Google fonts
+        'Noto+Sans+Hebrew:400'
+      ]
+  }
+})
+````
+
+If you'd like to load a font locally,
+then you can provide the configuration as an object:
+
+```ts
+export default defineNuxtConfig({
+  ogImage: {
+    fonts: [
+      {
+        name: 'optieinstein',
+        weight: 800,
+        // path must point to a public font file
+        path: '/OPTIEinstein-Black.otf',
+      }
+    ],
+  }
+})
+```
+
+Make sure to set the font family in your component to match the font name.
+
+```vue
+<template>
+<div :style="{ fontFamily: 'optieinstein' }">
+  <!-- Your component  -->
+</div>
+</template>
+```
+
+## Runtime Caching
+
+When images are generated at runtime, caching is enabled by default to reduce the load on your server. 
+
+By default, it will use the default storage engine for your Nitro preset. 
+You can customise the storage engine by providing a `runtimeCacheStorage` option to the `ogImage` config.
+
+The option takes the same configuration as the Nuxt `nitro.storage` option. 
+See the [Nitro Storage Layer](https://nitro.unjs.io/guide/storage) documentation for more details.
+
+For example:
+
+```ts
+export default defineNuxtConfig({
+  ogImage: {
+    // cloudflare kv binding example, set your own config
+    runtimeCacheStorage: {
+      driver: 'cloudflare-kv-binding',
+      binding: 'OG_IMAGE_CACHE'
+    }
+  }
+})
+````
+
+By default, static images will be cached for 24 hours. You can change the image TTL by providing `cacheTtl` when defining the image.
+
+```ts
+defineOgImageStatic({
+  // ...
+  cacheTtl: 60 * 60 * 24 * 7 // 7 days
+})
+```
+
+Alternatively, you can change the default cacheTtl time in your nuxt.config.
+
+
+```ts
+export default defineNuxtConfig({
+  ogImage: {
+    defaults: {
+      cacheTtl: 60 * 60 * 24 * 7 // 7 days
+    }
+  }
+})
+````
+
+You can also provide a configuration for the `cacheKey`. This gives you control over the cache bursting of the images.
+
+```vue
+<script lang="ts" setup>
+defineOgImageStatic({
+  cacheKey: `${myData.id}:${myData.updatedAt}`,
+})
+</script>
+```
+
+If you prefer not to cache your images you can always disable them by providing a `false` value.
+
+```ts
+export default defineNuxtConfig({
+  ogImage: {
+    // no runtime cache
+    runtimeCacheStorage: false
+  }
+})
+````
+
 # API
 
 The module exposes a composition and component API to implement your `og:image` generation. You should pick
@@ -290,7 +490,7 @@ whichever one you prefer using.
 ## OgImageStatic / defineOgImageStatic
 
 The `OgImageStatic` component and the `defineOgImageStatic` composable creates a static image
-that will be pre-rendered.
+that will be prerendered.
 
 The options follow the [OgImageOptions](#OgImageOptions) interface,
 any additional options will be passed to the `component` as props.
@@ -322,7 +522,7 @@ defineOgImageStatic({
 
 ## OgImageDynamic / defineOgImageDynamic
 
-The `OgImageDynamic` component and the `defineOgImageDynamic` composable creates a dynamic image. They are not pre-rendered and will
+The `OgImageDynamic` component and the `defineOgImageDynamic` composable creates a dynamic image. They are not prerendered and will
 be generated at runtime.
 
 The options follow the [OgImageOptions](#OgImageOptions) interface,
@@ -396,12 +596,14 @@ The name of the component to use as the template. By default, it uses OgImageBas
 - Required: `false`
 
 The provider to use to generate the image. The default provider is `satori`.
-When you use `browser` it will use Puppeteer to generate the image.
+When you use `browser` it will use Playwright to generate the image.
 
-### `prerender`
+### `static`
 
 - Type: `boolean`
-- Default: `true` when static, `false` when dynamic
+- Default: `true` when using `defineOgImageStatic`, `false` when dynamic
+
+Controls the prerendering of the image. A non-static image is one that will be generated at runtime and not cached.
 
 
 ## OgImageScreenshot / defineOgImageScreenshot
@@ -495,13 +697,13 @@ defineOgImageScreenshot({
 
 ## Module Config
 
-### `host`
+### `siteUrl`
 
 - Type: `string`
 - Default: `undefined`
 - Required: `true`
 
-The host of your site. This is required to generate the absolute path of the `og:image`.
+The site URL of your site. This is required when prerendering to generate the absolute path of the `og:image`.
 
 ### `defaults`
 
@@ -511,15 +713,6 @@ The host of your site. This is required to generate the absolute path of the `og
 
 The default options to use when generating images.
 
-### `forcePrerender`
-
-- Type: `boolean`
-- Default: `false`
-- Required: `false`
-
-This is enabled when you run `nuxi generate`. It forces all OG images to be pre-rendered as the server is not available to generate
-runtime images.
-
 ### `fonts`
 
 - Type: ``${string}:${number}`[]`
@@ -546,16 +739,21 @@ export default defineNuxtConfig({
 
 Options to pass to Satori when generating images. See the [Satori docs](https://github.com/vercel/satori).
 
-### `experimentalNitroBrowser` (experimental)
+### `runtimeSatori`
 
 - Type: `boolean`
-- Default: `false`
-- Required: `false`
+- Default: `true`
+
+Whether to use Satori at runtime. This is useful to disable if you're prerendering all your images.
+
+### `runtimeBrowser`
+
+- Type: `boolean`
+- Default: `process.dev`
 
-In a server runtime, the default behaviour is to generate images using Satori. If you'd like to generate runtime images using the a browser instance 
-for screenshots, you can enable this setting.
+Whether to use Playwright at runtime. You will need to enable this for production environments and ensure you are using 
+a supported nitro preset and have the required dependencies.
 
-This is experimental and may not work in all environments.
 
 ## Examples
 

package/dist/client/200.html

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html >
 <head><meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1"><link rel="modulepreload" as="script" crossorigin href="/__nuxt_og_image__/client/_nuxt/entry.74018bda.js"><link rel="preload" as="style" href="/__nuxt_og_image__/client/_nuxt/entry.7a8c1ab2.css"><link rel="prefetch" as="script" crossorigin href="/__nuxt_og_image__/client/_nuxt/error-component.cf7543e5.js"><link rel="stylesheet" href="/__nuxt_og_image__/client/_nuxt/entry.7a8c1ab2.css"><script>"use strict";const w=window,de=document.documentElement,knownColorSchemes=["dark","light"],preference=window.localStorage.getItem("nuxt-color-mode")||"system";let value=preference==="system"?getColorScheme():preference;const forcedColorMode=de.getAttribute("data-color-mode-forced");forcedColorMode&&(value=forcedColorMode),addColorScheme(value),w["__NUXT_COLOR_MODE__"]={preference,value,getColorScheme,addColorScheme,removeColorScheme};function addColorScheme(e){const o=""+e+"",t="";de.classList?de.classList.add(o):de.className+=" "+o,t&&de.setAttribute("data-"+t,e)}function removeColorScheme(e){const o=""+e+"",t="";de.classList?de.classList.remove(o):de.className=de.className.replace(new RegExp(o,"g"),""),t&&de.removeAttribute("data-"+t)}function prefersColorScheme(e){return w.matchMedia("(prefers-color-scheme"+e+")")}function getColorScheme(){if(w.matchMedia&&prefersColorScheme("").media!=="not all"){for(const e of knownColorSchemes)if(prefersColorScheme(":"+e).matches)return e}return"light"}
+<meta name="viewport" content="width=device-width, initial-scale=1"><link rel="modulepreload" as="script" crossorigin href="/__nuxt_og_image__/client/_nuxt/entry.f180d9dc.js"><link rel="preload" as="style" href="/__nuxt_og_image__/client/_nuxt/entry.f4586a2b.css"><link rel="prefetch" as="script" crossorigin href="/__nuxt_og_image__/client/_nuxt/error-component.0102aa4e.js"><link rel="stylesheet" href="/__nuxt_og_image__/client/_nuxt/entry.f4586a2b.css"><script>"use strict";const w=window,de=document.documentElement,knownColorSchemes=["dark","light"],preference=window.localStorage.getItem("nuxt-color-mode")||"system";let value=preference==="system"?getColorScheme():preference;const forcedColorMode=de.getAttribute("data-color-mode-forced");forcedColorMode&&(value=forcedColorMode),addColorScheme(value),w["__NUXT_COLOR_MODE__"]={preference,value,getColorScheme,addColorScheme,removeColorScheme};function addColorScheme(e){const o=""+e+"",t="";de.classList?de.classList.add(o):de.className+=" "+o,t&&de.setAttribute("data-"+t,e)}function removeColorScheme(e){const o=""+e+"",t="";de.classList?de.classList.remove(o):de.className=de.className.replace(new RegExp(o,"g"),""),t&&de.removeAttribute("data-"+t)}function prefersColorScheme(e){return w.matchMedia("(prefers-color-scheme"+e+")")}function getColorScheme(){if(w.matchMedia&&prefersColorScheme("").media!=="not all"){for(const e of knownColorSchemes)if(prefersColorScheme(":"+e).matches)return e}return"light"}
 </script></head>
-<body ><div id="__nuxt"></div><script>window.__NUXT__={serverRendered:false,config:{public:{},app:{baseURL:"\u002F__nuxt_og_image__\u002Fclient",buildAssetsDir:"\u002F_nuxt\u002F",cdnURL:""}},data:{},state:{}}</script><script type="module" src="/__nuxt_og_image__/client/_nuxt/entry.74018bda.js" crossorigin></script></body>
+<body ><div id="__nuxt"></div><script type="application/json" id="__NUXT_DATA__" data-ssr="false">[{"_errors":1,"serverRendered":2,"data":3,"state":4},{},false,{},{}]</script><script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__nuxt_og_image__/client",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="module" src="/__nuxt_og_image__/client/_nuxt/entry.f180d9dc.js" crossorigin></script></body>
 </html>

package/dist/client/404.html

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html >
 <head><meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1"><link rel="modulepreload" as="script" crossorigin href="/__nuxt_og_image__/client/_nuxt/entry.74018bda.js"><link rel="preload" as="style" href="/__nuxt_og_image__/client/_nuxt/entry.7a8c1ab2.css"><link rel="prefetch" as="script" crossorigin href="/__nuxt_og_image__/client/_nuxt/error-component.cf7543e5.js"><link rel="stylesheet" href="/__nuxt_og_image__/client/_nuxt/entry.7a8c1ab2.css"><script>"use strict";const w=window,de=document.documentElement,knownColorSchemes=["dark","light"],preference=window.localStorage.getItem("nuxt-color-mode")||"system";let value=preference==="system"?getColorScheme():preference;const forcedColorMode=de.getAttribute("data-color-mode-forced");forcedColorMode&&(value=forcedColorMode),addColorScheme(value),w["__NUXT_COLOR_MODE__"]={preference,value,getColorScheme,addColorScheme,removeColorScheme};function addColorScheme(e){const o=""+e+"",t="";de.classList?de.classList.add(o):de.className+=" "+o,t&&de.setAttribute("data-"+t,e)}function removeColorScheme(e){const o=""+e+"",t="";de.classList?de.classList.remove(o):de.className=de.className.replace(new RegExp(o,"g"),""),t&&de.removeAttribute("data-"+t)}function prefersColorScheme(e){return w.matchMedia("(prefers-color-scheme"+e+")")}function getColorScheme(){if(w.matchMedia&&prefersColorScheme("").media!=="not all"){for(const e of knownColorSchemes)if(prefersColorScheme(":"+e).matches)return e}return"light"}
+<meta name="viewport" content="width=device-width, initial-scale=1"><link rel="modulepreload" as="script" crossorigin href="/__nuxt_og_image__/client/_nuxt/entry.f180d9dc.js"><link rel="preload" as="style" href="/__nuxt_og_image__/client/_nuxt/entry.f4586a2b.css"><link rel="prefetch" as="script" crossorigin href="/__nuxt_og_image__/client/_nuxt/error-component.0102aa4e.js"><link rel="stylesheet" href="/__nuxt_og_image__/client/_nuxt/entry.f4586a2b.css"><script>"use strict";const w=window,de=document.documentElement,knownColorSchemes=["dark","light"],preference=window.localStorage.getItem("nuxt-color-mode")||"system";let value=preference==="system"?getColorScheme():preference;const forcedColorMode=de.getAttribute("data-color-mode-forced");forcedColorMode&&(value=forcedColorMode),addColorScheme(value),w["__NUXT_COLOR_MODE__"]={preference,value,getColorScheme,addColorScheme,removeColorScheme};function addColorScheme(e){const o=""+e+"",t="";de.classList?de.classList.add(o):de.className+=" "+o,t&&de.setAttribute("data-"+t,e)}function removeColorScheme(e){const o=""+e+"",t="";de.classList?de.classList.remove(o):de.className=de.className.replace(new RegExp(o,"g"),""),t&&de.removeAttribute("data-"+t)}function prefersColorScheme(e){return w.matchMedia("(prefers-color-scheme"+e+")")}function getColorScheme(){if(w.matchMedia&&prefersColorScheme("").media!=="not all"){for(const e of knownColorSchemes)if(prefersColorScheme(":"+e).matches)return e}return"light"}
 </script></head>
-<body ><div id="__nuxt"></div><script>window.__NUXT__={serverRendered:false,config:{public:{},app:{baseURL:"\u002F__nuxt_og_image__\u002Fclient",buildAssetsDir:"\u002F_nuxt\u002F",cdnURL:""}},data:{},state:{}}</script><script type="module" src="/__nuxt_og_image__/client/_nuxt/entry.74018bda.js" crossorigin></script></body>
+<body ><div id="__nuxt"></div><script type="application/json" id="__NUXT_DATA__" data-ssr="false">[{"_errors":1,"serverRendered":2,"data":3,"state":4},{},false,{},{}]</script><script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__nuxt_og_image__/client",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="module" src="/__nuxt_og_image__/client/_nuxt/entry.f180d9dc.js" crossorigin></script></body>
 </html>

package/dist/client/_nuxt/IconCSS.8bbd2aa2.css

@@ -0,0 +1 @@
+span[data-v-46d643c4]{background-color:currentColor;display:inline-block;-webkit-mask-image:var(--243647bc);mask-image:var(--243647bc);-webkit-mask-repeat:no-repeat;mask-repeat:no-repeat;-webkit-mask-size:100% 100%;mask-size:100% 100%;vertical-align:middle}

package/dist/client/_nuxt/IconCSS.db300c72.js

@@ -0,0 +1 @@
+import{a as r,b as u,e as p,f as t,o as l,h as _,i as d,j as m}from"./entry.f180d9dc.js";const f=r({__name:"IconCSS",props:{name:{type:String,required:!0},size:{type:String,default:""}},setup(a){const s=a;u(e=>({"243647bc":i.value}));const n=p();n?.nuxtIcon?.aliases;const c=t(()=>(n?.nuxtIcon?.aliases||{})[s.name]||s.name),i=t(()=>`url('https://api.iconify.design/${c.value.replace(":","/")}.svg')`),o=t(()=>{if(!s.size&&typeof n.nuxtIcon?.size=="boolean"&&!n.nuxtIcon?.size)return;const e=s.size||n.nuxtIcon?.size||"1em";return String(Number(e))===e?`${e}px`:e});return(e,x)=>(l(),_("span",{style:d({width:o.value,height:o.value})},null,4))}});const g=m(f,[["__scopeId","data-v-46d643c4"]]);export{g as default};

package/dist/client/_nuxt/ImageLoader.7571516f.css

@@ -0,0 +1 @@
+img[data-v-23ec6856]{height:auto!important;margin:0 auto;max-width:100%;transition:.4s ease-in-out;width:auto!important}

package/dist/client/_nuxt/ImageLoader.9ee91833.js

@@ -0,0 +1 @@
+import{a as _,r as c,m,w as r,f as u,s as d,o as g,h as f,i as y,j as v}from"./entry.f180d9dc.js";const x=_({__name:"ImageLoader",props:{src:String,aspectRatio:Number,description:String},setup(a){const s=a,n=c(),o=c(0);function i(e){const t=n.value,p=Date.now();t.src="",o.value=0,t.style.opacity="0",t.onload=()=>{t.style.opacity="1",o.value=Date.now()-p},t.src=e}m(()=>{r(()=>s.src,e=>{i(e)},{immediate:!0})});const l=u(()=>s.description.replace("%s",o.value.toString()));return r(l,e=>{d.value=e}),(e,t)=>(g(),f("img",{ref_key:"image",ref:n,class:"max-h-full border-1 border-light-500 rounded",style:y({aspectRatio:a.aspectRatio})},null,4))}});const w=v(x,[["__scopeId","data-v-23ec6856"]]);export{w as _};