@ogify/core 0.1.4 → 0.5.0

package/README.md

@@ -1,97 +1,113 @@
-# OGify - Beautiful Dynamic OG Images in Seconds
+# OGify - Generate beautiful OG images in minutes
 
 [![npm version](https://badge.fury.io/js/%40ogify%2Fcore.svg)](https://badge.fury.io/js/%40ogify%2Fcore)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
-Generate stunning Open Graph images in seconds, not hours. OGify eliminates the complexity of OG image generation with zero-config font loading, automatic caching, and production-ready templates.
+Zero-config dynamic Open Graph images for Next.js, Nuxt, Remix, and more. Just copy & paste the production-ready templates.
+
+![OGify](../../apps/examples/outputs/aligned-aligned-ltr.png)
 
 ## ⚡ Why OGify?
 
-- 🔌 **Zero-config**: Works out of the box with Next.js, Remix, Astro, etc.
-- 🎨 **No font management**: Just specify a Google Font name - no downloads, no font files, no hassle.
-- 📦 **No asset pipeline**: Emojis load dynamically from CDNs.
-- 🖼️ **Rich templates**: OGify provides a set of production-ready templates with zero configuration.
-- ⚡ **Smart caching**: OGify automatically caches fonts, emojis, and generated images - no configuration required.
-- 🛡️ **Type-safe**: Full TypeScript support catches errors before runtime.
+- 🔌 **Zero-config**: Works out of the box with Next.js, Remix, Nuxt, and more.
+- 🔤 **Hassle-free assets**: Just specify a Google Font name, Emoji provider - no downloads, no font files, no hassle.
+- 🎨 **Flexible Customization**: Intuitive API & Tailwind-like syntax helps building eye-catching templates faster.
+- 🖼️ **Production-ready templates**: OGify provides a set of production-ready templates with zero configuration.
+- ⚡ **Smart caching**: Automatically caches fonts, emojis, and generated images - no configuration required.
+- 🌍 **RTL Support**: Built-in support for Right-to-Left languages like Arabic, Hebrew, and Persian.
 
 ## 📦 Installation
 
 ```bash
-pnpm add @ogify/core
+pnpm add @ogify/core @ogify/templates
+```
+
+or
+
+```bash
+npm install @ogify/core @ogify/templates
+```
+
+or
+
+```bash
+yarn add @ogify/core @ogify/templates
 ```
 
 ## 🚀 Quick Start
 
-### 1. Define a Template
+### 1. Choose a Template
 
-Create a template using `defineTemplate` with an HTML renderer function:
+OGify comes with a collection of beautiful, production-ready templates. Check out [our gallery](https://ogify.dev/templates) for more.
 
 ```typescript
-import { defineTemplate, OgTemplateOptions } from '@ogify/core';
-
-const blogTemplate = defineTemplate({
-  id: 'blog-post',
-  name: 'Blog Post',
-  description: 'Template for blog post OG images',
-  fonts: [
-    { name: 'Inter', weight: 700 },
-    { name: 'Inter', weight: 400 }
-  ],
-  renderer: ({ params }: OgTemplateOptions) => {
-    return `
-      <div style="display: flex; flex-direction: column; width: 100%; height: 100%; background: white; padding: 40px;">
-        <h1 style="font-size: 60px; font-weight: 700; color: #000;">
-          ${params.title}
-        </h1>
-        <p style="font-size: 30px; color: #666;">
-          ${params.description}
-        </p>
-      </div>
-    `;
-  },
-});
+import template from '@ogify/templates/basic';
+import type { TemplateParams } from '@ogify/templates/basic';
 ```
 
 ### 2. Create a Renderer
 
-Create a renderer instance and register your templates:
+Create a renderer instance and register your template:
 
 ```typescript
-import { createTemplateRenderer } from '@ogify/core';
-
-const renderer = createTemplateRenderer({
-  templates: [blogTemplate],
-  defaultParams: {
-    brand: 'My Company'
+import { createRenderer } from '@ogify/core';
+import template from '@ogify/templates/basic';
+import type { TemplateParams } from '@ogify/templates/basic';
+
+const renderer = createRenderer<{ basic: TemplateParams }>({
+  templates: { basic: template },
+  sharedParams: {
+    brandLogo: 'https://ogify.dev/logo.svg',
+    brandName: 'OGify',
   }
 });
 ```
 
 ### 3. Generate an Image
 
-Render a template to a PNG buffer:
+Render the template to a PNG buffer:
 
 ```typescript
 // Basic usage (1200x630)
-const imageBuffer = await renderer.renderToImage('blog-post', {
+const imageBuffer = await renderer.renderToImage('basic', {
   title: 'Hello World',
-  description: 'My first OG image'
+  subtitle: 'My first OG image',
+  layout: 'centered', // aligned | centered | split
+  cta: 'Read More',
+  primaryColor: '#000000',
 });
 
 // Custom dimensions for Twitter (1200x675)
-const twitterImage = await renderer.renderToImage('blog-post', {
-  title: 'Hello World'
+const twitterImage = await renderer.renderToImage('basic', {
+  title: 'Hello World',
+  subtitle: 'My first OG image',
+  layout: 'split',
 }, {
   width: 1200,
   height: 675
 });
+
+// RTL Support (Arabic/Hebrew/Persian)
+const rtlImage = await renderer.renderToImage('basic', {
+  title: 'مرحبا بالعالم',
+  subtitle: 'هذه أول صورة OG لي',
+  layout: 'aligned',
+}, {
+  isRTL: true
+});
 ```
 
 **That's it!** You're ready for production. No font files to download, no build configuration, no asset pipeline.
 
 ## 🚀 Time-Saving Features
 
+### **Rich Templates**
+
+Access a growing library of beautiful, production-ready templates. [Browse Templates](https://ogify.dev/templates)
+
+**Time saved**: Hours of design and implementation time
+
 ### **Zero-Config Google Fonts**
 
 Traditional approach (manual setup):
@@ -99,23 +115,24 @@ Traditional approach (manual setup):
 ```typescript
 // ❌ Manual: Download fonts, manage files, configure paths
 import fs from 'fs';
-const fontData = fs.readFileSync('./fonts/Inter-Bold.ttf');
-const font2Data = fs.readFileSync('./fonts/Inter-Regular.ttf');
+
+const fontData = fs.readFileSync('./fonts/Inter-Regular.ttf');
+const font2Data = fs.readFileSync('./fonts/Inter-Bold.ttf');
 
 const fonts = [
-  { name: 'Inter', data: fontData, weight: 700 },
-  { name: 'Inter', data: font2Data, weight: 400 }
+  { name: 'Inter', data: fontData, weight: 400 },
+  { name: 'Inter', data: font2Data, weight: 700 }
 ];
 ```
 
-OGify approach (zero config):
+OGify approach (zero-config):
 
 ```typescript
 // ✅ OGify: Just specify the font name - we handle the rest
 const template = defineTemplate({
   fonts: [
-    { name: 'Inter', weight: 700 },  // Automatically loaded from Google Fonts
-    { name: 'Inter', weight: 400 }
+    { name: 'Inter', weight: 400 },  // Automatically loaded from Google Fonts
+    { name: 'Inter', weight: 700 }
   ],
   // ...
 });
@@ -127,13 +144,13 @@ const template = defineTemplate({
 
 ```typescript
 // First render: Downloads fonts from Google (~500ms)
-await renderer.renderToImage('blog-post', { title: 'Post 1' });
+await renderer.renderToImage('basic', { title: 'Post 1', subtitle: '...' });
 
 // Second render: Uses cached fonts (~50ms) - 10x faster! ⚡
-await renderer.renderToImage('blog-post', { title: 'Post 2' });
+await renderer.renderToImage('basic', { title: 'Post 2', subtitle: '...' });
 
 // All subsequent renders: Lightning fast
-await renderer.renderToImage('blog-post', { title: 'Post 3' });
+await renderer.renderToImage('basic', { title: 'Post 3', subtitle: '...' });
 ```
 
 **Performance**: 10x faster after first render, no configuration needed
@@ -152,6 +169,33 @@ renderer: ({ params }) => `
 
 **Time saved**: No emoji sprite sheets, no asset management, no build step
 
+## 🛠️ Creating Custom Templates
+
+If you want to build your own templates from scratch, you can use `defineTemplate`.
+
+```typescript
+import { defineTemplate, OgTemplateOptions } from '@ogify/core';
+
+const blogTemplate = defineTemplate({
+  fonts: [
+    { name: 'Inter', weight: 400 },
+    { name: 'Inter', weight: 700 }
+  ],
+  renderer: ({ params }: OgTemplateOptions) => {
+    return `
+      <div style="display: flex; flex-direction: column; width: 100%; height: 100%; background: white; padding: 40px;">
+        <h1 style="font-size: 60px; font-weight: 700; color: #000;">
+          ${params.title}
+        </h1>
+        <p style="font-size: 30px; color: #666;">
+          ${params.description}
+        </p>
+      </div>
+    `;
+  },
+});
+```
+
 ## 📚 Advanced Usage
 
 ### Custom Fonts
@@ -160,9 +204,6 @@ Load fonts from Google Fonts, custom URLs, or embedded data:
 
 ```typescript
 const template = defineTemplate({
-  id: 'custom-fonts',
-  name: 'Custom Fonts Template',
-  description: 'Template with custom fonts',
   fonts: [
     // Google Fonts (automatic)
     { name: 'Roboto', weight: 400 },
@@ -183,11 +224,8 @@ Choose from multiple emoji providers:
 
 ```typescript
 const template = defineTemplate({
-  id: 'emoji-template',
-  name: 'Emoji Template',
-  description: 'Template with emoji support',
   fonts: [{ name: 'Inter', weight: 400 }],
-  emojiProvider: 'twemoji', // or 'fluent', 'noto', 'openmoji', etc.
+  emojiProvider: 'twemoji', // 'fluent' | 'fluentFlat' | 'noto' | 'blobmoji' | 'openmoji'
   renderer: ({ params }) => `
     <div>
       <h1>${params.title}</h1>
@@ -202,8 +240,8 @@ const template = defineTemplate({
 Add custom logic before and after rendering:
 
 ```typescript
-const renderer = createTemplateRenderer({
-  templates: [blogTemplate],
+const renderer = createRenderer({
+  templates: { 'blog-post': blogTemplate },
   beforeRender: async (templateId, params) => {
     console.log(`Rendering ${templateId}`, params);
     // Log analytics, validate params, etc.
@@ -215,16 +253,49 @@ const renderer = createTemplateRenderer({
 });
 ```
 
+### Caching Configuration
+
+Configure caching strategy for fonts and emojis/icons:
+
+```typescript
+// Memory Cache (default)
+const memoryRenderer = createRenderer({
+  templates: { 'blog-post': blogTemplate },
+  cache: {
+    type: 'memory',
+    ttl: 3600000, // 1 hour
+    max: 100 // max items
+  }
+});
+
+// Filesystem Cache
+const fsRenderer = createRenderer({
+  templates: { 'blog-post': blogTemplate },
+  cache: {
+    type: 'filesystem',
+    dir: './.ogify-cache', // cache directory
+    ttl: 3600000, // 1 hour
+    max: 100 // max items
+  }
+});
+```
+
 ### Platform-Specific Dimensions
 
 Generate images for different platforms:
 
 ```typescript
 // Facebook/LinkedIn (1200x630)
-const facebookImage = await renderer.renderToImage('blog-post', params);
+const facebookImage = await renderer.renderToImage('basic', {
+  title: 'Hello World',
+  subtitle: 'My first OG image',
+});
 
 // Twitter (1200x675)
-const twitterImage = await renderer.renderToImage('blog-post', params, {
+const twitterImage = await renderer.renderToImage('basic', {
+  title: 'Hello World',
+  subtitle: 'My first OG image',
+}, {
   width: 1200,
   height: 675
 });
@@ -234,7 +305,7 @@ const twitterImage = await renderer.renderToImage('blog-post', params, {
 
 ### Supported CSS Properties
 
-Templates support a subset of CSS properties via Satori:
+Templates support a subset of CSS properties via Satori. See [Satori CSS](https://github.com/vercel/satori?tab=readme-ov-file#css) for more details.
 
 - **Layout**: `display: flex`, `flexDirection`, `alignItems`, `justifyContent`
 - **Spacing**: `padding`, `margin`, `gap`
@@ -242,6 +313,7 @@ Templates support a subset of CSS properties via Satori:
 - **Background**: `backgroundColor`, `backgroundImage`
 - **Border**: `border`, `borderRadius`
 - **Size**: `width`, `height`, `maxWidth`, `maxHeight`
+- ...
 
 ### Tailwind-like Utilities
 
@@ -264,23 +336,21 @@ Defines a new OG template.
 
 **Parameters:**
 
-- `id` (string): Unique identifier
-- `name` (string): Human-readable name
-- `description` (string): Template description
 - `renderer` (function): Function that returns HTML string
 - `fonts` (array): Array of font configurations
 - `emojiProvider` (optional): Emoji provider to use
 
 **Returns:** `OgTemplate`
 
-### `createTemplateRenderer(config)`
+### `createRenderer(config)`
 
 Creates a new template renderer instance.
 
 **Parameters:**
 
-- `templates` (array): Array of template definitions
-- `defaultParams` (optional): Default parameters for all templates
+- `templates` (object): Map of template definitions keyed by ID
+- `sharedParams` (optional): Default parameters for all templates
+- `cache` (optional): Cache configuration object
 - `beforeRender` (optional): Hook called before rendering
 - `afterRender` (optional): Hook called after rendering
 
@@ -293,40 +363,48 @@ Renders a template to a PNG buffer.
 **Parameters:**
 
 - `templateId` (string): ID of the template to render
-- `params` (object): Parameters to pass to the template
+- `params` (object | function): Parameters (or function returning params) to pass to the template
 - `options` (optional): Rendering options
   - `width` (number): Image width (default: 1200)
   - `height` (number): Image height (default: 630)
+  - `isRTL` (boolean): Enable Right-to-Left text direction (default: false)
 
 **Returns:** `Promise<Buffer>`
 
-### `renderer.getTemplate(id)`
+### RTL Support
 
-Retrieves a template by ID.
+OGify supports Right-to-Left (RTL) languages via the `isRTL` option.
 
-**Returns:** `OgTemplate | undefined`
+```typescript
+const image = await renderer.renderToImage('basic', {
+  title: 'مرحبا بالعالم', // Arabic: Hello World
+  subtitle: 'هذه أول صورة OG لي',
+}, {
+  isRTL: true
+});
+```
 
-### `renderer.getTemplateIds()`
+### `renderer.getTemplate(id)`
 
-Gets all registered template IDs.
+Retrieves a template by ID.
 
-**Returns:** `string[]`
+**Returns:** `OgTemplate | undefined`
 
 ## ⚡ Performance & Production
 
 ### **Automatic Caching (Zero Config)**
 
-OGify automatically caches fonts and emojis in memory - no configuration required:
+OGify automatically caches fonts, emojis, and generated images in memory - no configuration required
 
 ```typescript
 // First render: Downloads fonts from Google Fonts (~500ms)
-await renderer.renderToImage('blog-post', { title: 'Post 1' });
+await renderer.renderToImage('basic', { title: 'Post 1', subtitle: '...' });
 
 // Second render: Uses cached fonts (~50ms) - 10x faster! ⚡
-await renderer.renderToImage('blog-post', { title: 'Post 2' });
+await renderer.renderToImage('basic', { title: 'Post 2', subtitle: '...' });
 
 // Third+ renders: Lightning fast from cache
-await renderer.renderToImage('blog-post', { title: 'Post 3' });
+await renderer.renderToImage('basic', { title: 'Post 3', subtitle: '...' });
 ```
 
 ## 📋 Changelog
@@ -347,4 +425,5 @@ Built on top of:
 
 - [satori](https://github.com/vercel/satori) - SVG generation
 - [satori-html](https://github.com/vercel/satori-html) - HTML to VDOM conversion
-- [resvg-js](https://github.com/thx/resvg-js) - PNG conversion
+- [@resvg/resvg-js](https://github.com/thx/resvg-js) - SVG to PNG conversion
+- [lru-cache](https://github.com/isaacs/node-lru-cache) - LRU cache