@cf-wasm/og
Version:
Generate Open Graph Images dynamically from HTML/CSS without a browser.
202 lines (201 loc) • 6.73 kB
TypeScript
import type { ReactElement } from 'react';
import type { FontBuffer } from '../core/font';
import { type Font, type PngResult, type RenderOptions, type SvgResult } from '../core/render';
import { BaseResponse, type BaseResponseOptions } from '../core/response';
import type { FontWeight } from '../core/satori';
import type { MayBePromise } from '../core/types';
/** An interface representing the element result of a figma template */
export interface ElementResult {
/** The element as {@link ReactElement} */
element: ReactElement<any, string | React.JSXElementConstructor<any>>;
/** The width of the image */
width: number;
/** The height of the image */
height: number;
/** The dynamic fonts */
fonts: Font[];
}
/** An interface representing a figma complex template */
export interface FigmaComplexTemplate {
value: string;
props?: {
centerHorizontally?: boolean;
} & React.CSSProperties;
}
/** An interface representing figma options */
export interface FigmaOptions {
/**
* Link to the Figma template frame.
*
* You can get the URL in Figma by right-clicking a frame and selecting "Copy link".
* @example https://www.figma.com/file/QjGNQixWnhu300e1Xzdl2y/OG-Images?type=design&node-id=11356-2443&mode=design&t=yLROd7ro8mP1PxMY-4
*/
url: string;
/**
* A mapping between Figma layer name and the value you want to replace it with.
*
* @example Sets Figma text layer named "Title" to "How to create OG Images"
* ```js
* { "Title": "How to create OG Images" }
* ```
*
* @example Sets multiple Figma text layers and provides custom styles
* ```js
* {
* "Title": { value: "How to create OG Images", props: { color: "red", centerHorizontally: true } },
* "Description": { value: "A short story", props: { centerHorizontally: true } },
* }
* ```
*
* `centerHorizontally` centers text layer horizontally.
*/
template: Record<string, FigmaComplexTemplate | string>;
/** Figma API token */
token: string;
}
export type LoadFontsFunction = (fontFamily: string, fontWeight: FontWeight | undefined, fontStyle: 'normal' | 'italic' | undefined) => MayBePromise<ArrayBuffer | FontBuffer | undefined>;
/** An interface representing options for {@link renderFigma} function */
export interface RenderFigmaOptions extends Omit<RenderOptions, 'width' | 'height'> {
loadFonts?: LoadFontsFunction;
}
/** An interface representing options for {@link FigmaImageResponse} */
export interface FigmaImageResponseOptions extends RenderFigmaOptions, BaseResponseOptions {
}
/**
* A helper function to parse figma url and return its `fileId` and `nodeId`
*
* @param figmaUrl The figma file url
*
* @returns An object containing `fileId` and `nodeId`
*/
export declare const parseFigmaUrl: (figmaUrl: string) => {
fileId: string;
nodeId: string;
};
/**
* Asserts if value is undefined
*
* @param value The value
* @param errorMessage The error message
*
* @returns The same value if it is not undefined otherwise throws an error
*/
export declare const assertValue: (value: string | undefined, errorMessage: string) => string;
/**
* Checks if target is a figma complex template
*
* @param template The complex template or any value
*
* @returns `true` if the target is a complex template otherwise `false`
*/
export declare const isComplexTemplate: (template: unknown) => boolean;
/**
* Converts svg string to base64 data uri string
*
* @param svg The svg as string
*
* @returns The base64 data uri string for the svg
*/
export declare const svgToBase64: (svg: string) => string;
/**
* Gets the `width` and `height` of the svg string
*
* @param svg The svg string
*
* @returns An Object containing `width` and `height`
*/
export declare const getSvgDimensions: (svg: string) => {
width: number;
height: number;
};
/**
* Gives all the text nodes in a svg string
*
* @param svg The svg as string
*
* @returns An Array of text nodes as string
*/
export declare const getTextNodes: (svg: string) => string[];
/**
* Gives all the tspan nodes in a text node string
*
* @param svg The text node as string
*
* @returns An Array of tspan nodes as string
*/
export declare const getTspanNodes: (text: string) => string[];
/**
* Parses the tspan node of a svg and returns its attributes
*
* @param tspanNode The tspan node as string
*
* @returns The attributes of the tspan node as an object
*/
export declare const parseTspanNode: (tspanNode: string) => {
x: string;
y: string;
content: string;
};
/**
* Parses the text node of a svg and returns its attributes
*
* @param textNode The text node as string
*
* @returns The attributes of the text node as an object
*/
export declare const parseTextNode: (textNode: string) => {
id: string;
fill: string;
fontFamily: string;
fontSize: string;
fontWeight: string | undefined;
fontStyle: "normal" | "italic" | undefined;
letterSpacing: string;
x: string;
y: string;
children: {
x: string;
y: string;
content: string;
}[];
};
/**
* Removes all the text nodes of a svg string
*
* @param svg The svg as string
*
* @returns The replaced svg as string
*/
export declare const removeTextNodes: (svg: string) => string;
/**
* Get the Figma template's svg
*
* @param figmaOptions The {@link FigmaOptions}
*
* @returns The svg as string
*/
export declare const getFigmaSvg: (figmaOptions: FigmaOptions) => Promise<string>;
export declare const loadTextNodeFonts: (nodeAttributes: ReturnType<typeof parseTextNode>[], loadFonts: LoadFontsFunction) => Promise<Font[]>;
/**
* Renders Figma template to image
*
* @param figmaOptions The {@link FigmaOptions}
* @param renderOptions The {@link RenderFigmaOptions}
*
* @returns An object containing methods for rendering the Figma template to image
*/
export declare const renderFigma: (figmaOptions: FigmaOptions, renderOptions?: RenderFigmaOptions) => {
asElement: () => Promise<ElementResult>;
asSvg: () => Promise<SvgResult>;
asPng: () => Promise<PngResult>;
};
/** A class for rendering Figma template to image as {@link Response} */
export declare class FigmaImageResponse extends BaseResponse {
/**
* Creates an instance of {@link FigmaImageResponse}
*
* @param figmaOptions Figma options {@link FigmaOptions}
* @param responseOptions The same as {@link ImageResponseOptions} except `width` and `height`. `width` and `height` are automatically set from the Figma frame's size.
*/
constructor(figmaOptions: FigmaOptions, responseOptions?: FigmaImageResponseOptions);
}