ogis

v0.2.0

Published

2 months ago

TypeScript client for OGIS OpenGraph image generation service

Downloads

0High
0Medium
0Low

twango

opengraph og-image image-generation typescript ogis

ogis: Open Graph Images as a Service

Generate beautiful Open Graph images via URL. No design skills required.

Quick Start

Install the SDK:

npm install ogis

Next.js (App Router)

// app/blog/[slug]/page.tsx
import { OgisClient } from 'ogis';

const ogis = new OgisClient({ baseUrl: 'https://img.ogis.dev' });

export async function generateMetadata({ params }) {
  const post = await getPost(params.slug);

  return {
    openGraph: {
      images: [ogis.generateUrl({
        title: post.title,
        description: post.excerpt,
        template: 'twilight'
      })]
    }
  };
}

SvelteKit

<script lang="ts">
  import { OgisClient } from 'ogis';

  const ogis = new OgisClient({ baseUrl: 'https://img.ogis.dev' });
  const ogImage = ogis.generateUrl({
    title: 'My Page',
    template: 'minimal'
  });
</script>

<svelte:head>
  <meta property="og:image" content={ogImage} />
  <meta property="og:image:width" content="1200" />
  <meta property="og:image:height" content="630" />
</svelte:head>

Astro

---
import { OgisClient } from 'ogis';

const ogis = new OgisClient({ baseUrl: 'https://img.ogis.dev' });
const ogImage = ogis.generateUrl({
  title: frontmatter.title,
  description: frontmatter.description
});
---

<head>
  <meta property="og:image" content={ogImage} />
</head>

Nuxt

<script setup lang="ts">
import { OgisClient } from 'ogis';

const ogis = new OgisClient({ baseUrl: 'https://img.ogis.dev' });

useSeoMeta({
  ogImage: ogis.generateUrl({
    title: 'My Page',
    template: 'modern'
  })
});
</script>

Plain HTML / Any Framework

No SDK needed - just construct the URL:

<meta property="og:image" content="https://img.ogis.dev/?title=Hello%20World&template=twilight" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

Templates

Browse all templates at ogis.dev/playground.

Parameters

All parameters are optional and passed as query parameters or SDK options.

| Parameter | Description | Example | |-----------|-------------|---------| | title | Main heading text | My Blog Post | | description | Secondary text below title | A deep dive into... | | subtitle | Small text above title | Tutorial | | template | Template name (see above) | twilight | | logo | URL to logo image | https://example.com/logo.png | | image | URL to background/hero image | https://example.com/hero.jpg |

Templates may support additional color customization parameters. See the playground for template-specific options.

Self-Hosting

Docker

docker run -d -p 3000:3000 twango/ogis:latest

Docker Compose

docker compose up -d

From Source

cargo build --release
./target/release/ogis

Configuration

Configure via environment variables (prefixed with OGIS_) or CLI arguments:

| Environment Variable | CLI Argument | Default | Description | |---------------------|--------------|---------|-------------| | OGIS_PORT | --port | 3000 | Server port | | OGIS_HOST | --host | 0.0.0.0 | Server host | | OGIS_HMAC_SECRET | --hmac-secret | - | Enable HMAC authentication | | OGIS_DEFAULT_TEMPLATE | --default-template | twilight | Default template | | OGIS_MAX_INPUT_LENGTH | --max-input-length | 500 | Max text length | | OGIS_CACHE_SIZE | --cache-size | 1000 | Image cache size |

Run ogis --help for all options.

Authentication

For private instances, enable HMAC-SHA256 signature validation:

# Server
docker run -d -p 3000:3000 -e OGIS_HMAC_SECRET=your-secret twango/ogis:latest

// Client
const ogis = new OgisClient({
  baseUrl: 'https://your-instance.com',
  hmacSecret: process.env.OGIS_SECRET
});

// URLs are automatically signed
const url = ogis.generateUrl({ title: 'Secure Image' });
// => https://your-instance.com/?title=Secure+Image&signature=abc123...

See Authentication docs for details.

Documentation

License

AGPL-3.0