diff --git a/README.md b/README.md index 4fee31f..aaed041 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,193 @@ -# create-svelte +# SvelteKit Open Graph Image Generation -Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/master/packages/create-svelte). +Dynamically generate Open Graph images from an HTML+CSS template or Svelte component using fast and efficient conversion from HTML > SVG > PNG. Based on [Satori](https://github.com/vercel/satori#documentation). No headless browser required. -Read more about creating a library [in the docs](https://kit.svelte.dev/docs/packaging). +## Disclaimer -## Creating a project +This documentation is currently unmaintained, as the development focus is compatibility with cloudflare, vercel and vercel edge. -If you're seeing this, you've probably already done this step. Congrats! +## Installation ```bash -# create a new project in the current directory -npm create svelte@latest - -# create a new project in my-app -npm create svelte@latest my-app +pnpm install -D @ethercorps/sveltekit-og ``` -## Developing - -Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server: +> Using with Cloudflare Pages or Workers then you have to provide `url` polyfill by just installing it as `devDependency`. ```bash -npm run dev - -# or start the server and open the app in a new browser tab -npm run dev -- --open +pnpm i -D url ``` -Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app. +## Usage -## Building +Create a file at `/src/routes/og/+server.ts`. Alternatively, you can use JavaScript by removing the types from this example. -To build your library: +```typescript +// src/routes/og/+server.ts +import { ImageResponse } from '@ethercorps/sveltekit-og'; +import { RequestHandler } from './$types'; -```bash -npm run package +const template = ` +
+
+

+ Ready to dive in? + Start your free trial today. +

+
+
+ Get started +
+
+ Learn more +
+
+
+
+`; + +const fontFile = await fetch('https://og-playground.vercel.app/inter-latin-ext-400-normal.woff'); +const fontData: ArrayBuffer = await fontFile.arrayBuffer(); + +export const GET: RequestHandler = async () => { + return await ImageResponse(template, { + height: 630, + width: 1200, + fonts: [ + { + name: 'Inter Latin', + data: fontData, + weight: 400 + } + ] + }); +}; ``` -To create a production version of your showcase app: +Then run `npm dev` and visit `localhost:5173/og` to view your generated PNG. Remember that hot module reloading does not work with server routes, so if you change your HTML or CSS, hard refresh the route to see changes. -```bash -npm run build +## Example Output + +![Rendered OG image](static/demo.png) + +## Headers + +When run in development, image headers contain `cache-control: no-cache, no-store`. In production, image headers contain `'cache-control': 'public, immutable, no-transform, max-age=31536000'`, which caches the image for 1 year. In both cases, the `'content-type': 'image/png'` is used. + +## Styling + +Notice that our example uses TailwindCSS classes (e.g. `tw="bg-gray-50"`). Alternatively, your HTML can contain style attributes using any of [the subset of CSS supported by Satori](https://github.com/vercel/satori#css). + +Satori supports only a subset of HTML and CSS. For full details, see [Satori’s documentation](https://github.com/vercel/satori#documentation). Notably, Satori only supports flex-based layouts. + +## Fonts + +Satori supports `ttf`, `otf`, and `woff` font formats; `woff2` is not supported. To maximize the font parsing speed, `ttf` or `otf` are recommended over `woff`. + +By default, `@ethercorps/sveltekit-og` includes only 'Noto Sans' font. If you need to use other fonts, you can specify them as shown in the example. Notably, you can also import a font file that is stored locally within your project and are not required to use fetch. + +## Examples + +- `ImageResponse` · [_source_](/src/routes/new/+server.ts) · [_demo_](https://sveltekit-og-five.vercel.app/new) +- `componentToImageResponse` · [_source_](/src/routes/component-og/) · [_demo_](https://sveltekit-og-five.vercel.app/component-og) + +## API Reference + +The package exposes an `ImageResponse` and `componentToImageResponse` constructors, with the following options available: + +```typescript +import {ImageResponse, componentToImageResponse} from '@ethercorps/sveltekit-og' +import {SvelteComponent} from "svelte"; + +// ... +ImageResponse( + element : string, + options : { + width ? : number = 1200 + height ? : number = 630, + backgroundColor ? : string = "#fff" + fonts ? : { + name: string, + data: ArrayBuffer, + weight: number, + style: 'normal' | 'italic' + }[] + debug ? : boolean = false + graphemeImages ? : Record; + loadAdditionalAsset ? : (languageCode: string, segment: string) => Promise; + // Options that will be passed to the HTTP response + status ? : number = 200 + statusText ? : string + headers ? : Record + }) + +componentToImageResponse( + component : typeof SvelteComponent, + props : {}, // All export let example inside prop dictionary + options : { + width ? : number = 1200 + height ? : number = 630 + fonts ? : { + name: string, + data: ArrayBuffer, + weight: number, + style: 'normal' | 'italic' + }[] + debug ? : boolean = false + graphemeImages ? : Record; + loadAdditionalAsset ? : (languageCode: string, segment: string) => Promise; + // Options that will be passed to the HTTP response + status ? : number = 200 + statusText ? : string + headers ? : Record + }) ``` -You can preview the production build with `npm run preview`. +## Changelog -> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment. +### v1.2.3 Update (Breaking Changes) -## Publishing +> Now you have to install dependency by yourself which will make it easier to build for all plateforms. -Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)). - -To publish your library to [npm](https://www.npmjs.com): - -```bash -npm publish ``` +npm i @resvg/resvg-js +``` + +``` +npm i satori +``` + +> From now on their will be no issues related to build, and soon this library going to have its own documentation. + +### v1.2.2 Update (Breaking Change) + +- We don't provide access to satori from `@ethercorps/sveltekit-og`. + +### v1.0.0 Update (Breaking Changes) + +Finally, We have added html to react like element like object converter out of the box and with svelte compiler. +Now you can use `{ toReactElement }` with `"@ethercorps/sveltekit-og"` like: + +- We have changed to function based instead of class based ImageResponse and componentToImageResponse. +- Removed `@resvg/resvg-wasm` with `@resvg/resvg-js` because of internal errors. +- Removed `satori-html` because now we have `toReactElement` out of the box with svelte compiler. + > If you find a problem related to undefined a please check [_vite.config.js_](/vite.config.ts) and add ` define: { _a: 'undefined' } in config.` + +> If you find any issue and have suggestion for this project please open a ticket and if you want to contribute please create a new discussion. + +## Acknowledgements + +This project will not be possible without the following projects: + +- [Satori & @vercel/og](https://github.com/vercel/satori) +- [Noto by Google Fonts](https://fonts.google.com/noto) +- [svg2png-wasm](https://github.com/ssssota/svg2png-wasm) + +## Authors + +- [@theetherGit](https://www.github.com/theetherGit) +- [@etherCorps](https://www.github.com/etherCorps) + +## Contributors + +- [@jasongitmail](https://github.com/jasongitmail) diff --git a/static/demo.png b/static/demo.png new file mode 100644 index 0000000..bb74d9c Binary files /dev/null and b/static/demo.png differ