@flyyer/flyyer
    TypeScript icon, indicating that this package has built-in type declarations

    3.4.1 • Public • Published

    flyyer-js

    npm-version downloads size tree-shake

    Format URLs to generate social media images using Flyyer.io.

    To create templates with React.js or Vue.js use create-flyyer-app 👈

    Flyyer live image

    This module is agnostic to any JS framework and has only one dependency: qs.

    Index

    Get started (5 minutes)

    1. Install module

    This module supports Node.js, Browser and can be bundled with any tool such as Rollup, Webpack, etc and includes Typescript definitions.

    yarn add @flyyer/flyyer
    
    # or with npm:
    npm install --save @flyyer/flyyer

    2. Flyyer.io smart image link

    Haven't registered your website yet? Go to Flyyer.io and import your website to create a project (e.g. website-com).

    For each of your routes, create an instance.

    import { Flyyer } from "@flyyer/flyyer";
    
    const flyyer = new Flyyer({
      // Your project slug
      project: "website-com",
      // Relative path
      path: `/path/to/product`,
    });
    
    console.log(flyyer.href());
    // > https://cdn.flyyer.io/v2/website-com/_/__v=1618281823/path/to/product

    2.1 Next.js

    Remember to dynamically get the current path for each page. If you are using Next.js you should probably do this:

    import { useRouter } from 'next/router'
    
    function SEO() {
      const router = useRouter();
      const flyyer = new Flyyer({
        project: "my-project",
        path: router.asPath,
      });
      // ...
    }

    Check our official Next.js documentation here;

    3. Setup <head> meta tags

    You'll get the best results doing this:

    <meta property="og:image" content={flyyer.href()} />
    <meta name="twitter:image" content={flyyer.href()} />
    <meta name="twitter:card" content="summary_large_image" />

    4. Manage rules

    Login at Flyyer.io, select your project and go to Manage rules. Then create a rule like the following:

    Flyyer basic rule example

    Voilà! To create templates with React.js or Vue.js use create-flyyer-app 👈

    Advanced usage

    Advanced features include:

    • Custom variables: additional information for your preview that is not present in your website. [Note: if you need customization you should take a look at Flyyer Render]
    • Custom metadata: set custom width, height, resolution, and more (see example).
    • Signed URLs.

    Here you have a detailed full example for project website-com and path /path/to/product.

    import { Flyyer } from "@flyyer/flyyer";
    
    const flyyer = new Flyyer({
      // Project slug, find it in your dashboard https://flyyer.io/dashboard/.
      project: "website-com",
      // The current path of your website (by default it's `/`).
      path: "/path/to/product",
    
      // [Optional] In case you want to provide information that is not present in your page set it here.
      variables: {
        title: "Product name",
        img: "https://flyyer.io/img/marketplace/flyyer-banner.png",
      },
      // [Optional] Additional variables.
      meta: {
        id: "jeans-123", // stats identifier (e.g. product SKU), defaults to `path`.
        width: 1080, // force width (pixels).
        height: 1080, // force height (pixels).
        v: null, // cache-burst, to circumvent platforms' cache, default to a timestamp, null to disable.
      },
    });

    Read more about integration guides here: https://docs.flyyer.io/guides

    Flyyer Lite

    If you are not using Signed URLs you can opt-in for @flyyer/flyyer-lite which is a lightweight version because it doesn't include crypto functions.

    yarn add @flyyer/flyyer-lite

    Usage is the same:

    import { Flyyer } from "@flyyer/flyyer-lite";
    // ...

    FlyyerRender

    • Flyyer uses the rules defined on your dashboard to decide how to handle every image. It analyse your website to render a content-rich image. Let's say "Flyyer renders images based on the content of this route".

    • FlyyerRender instead requires you to explicitly declare template and variables for the images to render, giving you more control for customization. Let's say "FlyyerRender renders an image using this template and these explicit variables".

    import { FlyyerRender } from "@flyyer/flyyer";
    const flyyer = new FlyyerRender({
      tenant: "flyyer",
      deck: "default",
      template: "main",
      variables: { title: "try changing this" },
    });
    const url = flyyer.href()
    // https://cdn.flyyer.io/v2/flyyer/default/main.jpeg?title=try+changing+this

    Resultant flyyer live image

    After installing this module you can format URLs. Here is an example with React.js, but note this can be used with any framework:

    import React from "react";
    import { FlyyerRender } from "@flyyer/flyyer";
    
    function Head() {
      const flyyer = new FlyyerRender({
        tenant: "tenant",
        deck: "deck",
        template: "template",
        variables: {
          title: "Hello world!",
          image: "https://yoursite.com/image/products/1.png",
        },
      });
      const url = flyyer.href();
    
      return (
        <head>
          <meta property="og:image" content={url} />
          <meta name="twitter:image" content={url} />
          <meta name="twitter:card" content="summary_large_image" />
        </head>
      );
    }

    Variables can be complex arrays and objects.

    const flyyer = new FlyyerRender({
      // ...
      variables: {
        items: [
          { text: "Oranges", count: 12 },
          { text: "Apples", count: 14 },
        ],
      },
      meta {
        id: "slug-or-id", // To identify the resource in our analytics report
      }
    });

    IMPORTANT: variables must be serializable.

    You can set image dimensions, note if your are planing to use this as <img src={flyyer.href()} /> you should disable cache-bursting.

    const flyyer = new FlyyerRender({
      tenant: "tenant",
      deck: "default",
      template: "main",
      variables: {
        title: "Awesome 😃",
        description: "Optional description",
      },
      meta: {
        v: null, // prevent cache-bursting in browsers
        width: 1080, // in pixels
        height: 1920, // in pixels
      }
    });
    
    <img src={flyyer.href()}>

    Resultant flyyer live image

    To create templates with React.js or Vue.js use create-flyyer-app 👈


    Development

    Prepare the local environment:

    yarn install

    To decode an URL for debugging purposes:

    console.log(decodeURI(url));
    // > https://cdn.flyyer.io/v2/tenant/deck/template.jpeg?title=Hello+world!&__v=123

    Helpers to compare instances (ignores __v param and performs a shallow compare of variables).

    import {
      isEqualFlyyer,
      isEqualFlyyerRender,
      isEqualFlyyerMeta,
    } from "@flyyer/flyyer";
    
    const boolean = isEqualFlyyer(fio1, fio2);

    Test

    To run tests:

    yarn test

    FAQ

    What is the difference between Flyyer and FlyyerRender?

    • Flyyer uses the rules defined on your dashboard to decide how to handle every image. It analyse your website to render a content-rich image. Let's say "Flyyer renders images based on the content of this route".

    • FlyyerRender instead requires you to explicitly declare template and variables for the images to render, giving you more control for customization. Let's say "FlyyerRender renders an image using this template and these explicit variables".

    Is it compatible with Nextjs, React, Vue, Express and other frameworks?

    This is framework-agnostic, you can use this library on any framework on any platform.

    How to configure Flyyer rules?

    Visit your project rules and settings on the Flyyer Dashboard.

    What is the __v= thing?

    Most social networks caches images, we use this variable to invalidate their caches but we ignore it on our system to prevent unnecessary renders. We strongly recommend it and its generated by default.

    Pass meta: { v: null } to disabled it (not recommended).

    Install

    npm i @flyyer/flyyer

    DownloadsWeekly Downloads

    42

    Version

    3.4.1

    License

    MIT

    Unpacked Size

    317 kB

    Total Files

    27

    Last publish

    Collaborators

    • lopezjurip
    • francomendez