@astrojs/og v0.0.4
@astrojs/og 🌄
⚠️ This integration is still experimental! Only
output: 'server'
environments andnode
environments are supported currently.
This Astro integration makes it easy to add social Open Graph images to your Astro project!
Why @astrojs/og
?
Branded Open Graph images make your content significantly more appealing on social media sites. However, creating these images has historically been difficult—static images require constant back-and-forth to keep edits in sync, whereas fully dynamic images required heavy-handed solutions like a headless browser or low-level canvas
APIs.
This integration comes with a straight-forward <og.image>
component that renders an image from your existing markup and components. By creating a src/pages/og/
directory and adding .astro
pages, you instantly have the full power of Astro at your disposal for creating Open Graph images.
Installation
Quick Install
The astro add
command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren't sure which package manager you're using, run the first command.) Then, follow the prompts, and type "y" in the terminal (meaning "yes") for each one.
# Using NPM
npx astro add og
# Using Yarn
yarn astro add og
# Using PNPM
pnpm astro add og
If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.
Manual Install
First, install the @astrojs/og
package using your package manager. If you're using npm or aren't sure, run this in the terminal:
npm install @astrojs/og
Then, apply this integration to your astro.config.*
file using the integrations
property:
astro.config.mjs
import og from "@astrojs/og";
export default {
// Note that only `server` is supported (for now!)
output: "server",
integrations: [og()],
};
Usage
---
import { og } from '@astrojs/image/components';
---
<og.image title="Hello world!" />
The included <og.image>
component will generate a <meta property="og:image">
tag. You must also create a src/pages/og/
directory that contains .astro
files which will generate your open graph images. By default, src/pages/og/index.astro
is required.
---
import { Container } from '@astrojs/image/components';
const { title } = Object.fromEntries(Astro.url.searchParams.entries());
---
<Container>
<h1>{title}</h1>
</Container>
<og.image />
Astro’s <og.image />
component requires the alt
attribute, which provides descriptive text for images. A warning will be logged if alt text is missing, and a future release of the integration will throw an error if no alt text is provided.
src
Type: string
Required: false
Source path to the image component.
For components located in your project's src/pages/og
directory, use the file path relative to the src/pages/og
directory. (e.g. src="blog"
will reference src/pages/og/blog.astro
)
alt
Type: string
Required: true
Defines an alternative text description of the image.
as
Type: 'meta' | 'img'
Default: 'meta'
The output element to render to. A <meta>
tag will be generated if as
is not provided.
Set as="img"
to debug image during development.
width
Type: number
Default: 1200
The desired width of the output image. If provided, height
is also required.
Dimensions are optional and will default to 1200 x 630
if not provided.
height
Type: number
Default: 630
The desired height of the output image. If provided, width
is also required.
Dimensions are optional and will default to 1200 x 630
if not provided.
debug
Type: boolean
Default: false
Enable debug
rendering for satori
, which will draw bounding boxes for debugging.
Configuration
There are no integration options at the moment. In the future, support for custom fonts will be exposed at the integration level.
Troubleshooting
- If your installation doesn't seem to be working, try restarting the dev server.
- If you edit and save a file and don't see your site update accordingly, try refreshing the page.
- If refreshing the page doesn't update your preview, or if a new installation doesn't seem to be working, then restart the dev server.
For help, check out the #support
channel on Discord. Our friendly Support Squad members are here to help!
You can also check our Astro Integration Documentation for more on integrations.
Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!
Changelog
See CHANGELOG.md for a history of changes to this integration.