Developers - Helpers

Helpers

Installation

To install the Perfection Helpers in your application, you can use the Helpers NPM package.

Install the NPM package as follows

Npm

>_ Terminal

npm install @perfectiondev/oversite-helpers

Yarn

>_ Terminal

yarn add @perfectiondev/oversite-helpers

Pnpm

>_ Terminal

pnpm i @perfectiondev/oversite-helpers

Bun

>_ Terminal

bun add -g @perfectiondev/oversite-helpers

Create a client

Before continuing, make sure you already have an .env file wwhere you store your Perfection Site Name, API Key and Subscription ID. This file should be localted at the root folder of your project.

Secondly, import @perfection/oversite-helpers module and create a reusable oversiteHelpers client as follow:

Next.js

clients/oversiteHelpers.js

import OH from "@perfectiondev/oversite-helpers";

export class oversiteHelpers {
  static instances = new Map();

  static init = async (pageId) => {
    const helpers = oversiteHelpers.instances.get(pageId);
    const isPreview = process.env.NEXT_PUBLIC_PERFECTION_PREVIEW == "true" ? true : false;

    if (helpers) await helpers.usePage(pageId);
    else {
      const result = await OH.init({
        apiKey: process.env.NEXT_PUBLIC_PERFECTION_API_KEY,
        subscriptionId: process.env.NEXT_PUBLIC_PERFECTION_SUBSCRIPTION_ID,
        siteName: process.env.NEXT_PUBLIC_PERFECTION_SITE_NAME,
        pageId,
        preview: isPreview,
      });
      await result.usePage(pageId);
      oversiteHelpers.instances.set(pageId, result);
    }
  };
  static section = { parts: (partsFn, sectionId) => (typeof partsFn === "function" ? partsFn(sectionId) : (selector, defaultClasses) => defaultClasses) };
}

Nuxt.js

middleware/oversite.global.js

export default defineNuxtRouteMiddleware(async (to) => {
  const { $helpers } = useNuxtApp()

  await $helpers.usePage(
    typeof to.meta.pageId === 'string' ? to.meta.pageId : ''
  )
})

plugins/oversiteHelpers.js

import oversiteHelpers from '@perfectiondev/oversite-helpers'

export default defineNuxtPlugin(async () => {
  const helpers = await oversiteHelpers.init({
    apiKey: import.meta.env.VITE_PUBLIC_PERFECTION_API_KEY,
    siteName: import.meta.env.VITE_PUBLIC_PERFECTION_SITE_NAME,
    subscriptionId: import.meta.env.VITE_PUBLIC_PERFECTION_SUBSCRIPTION_ID,
    preview: import.meta.env.VITE_PUBLIC_PERFECTION_PREVIEW === 'true',
  })

  return {
    provide: { helpers },
  }
})

Initialize the client

Lastly, load this file into your pages/routes, initiate it by passing the same unique pageId set in your Page data-pf attribute.

Next.js (App Router)

app/page.js

import { oversiteHelpers } from "./clients/oversiteHelpers";

export default async function Page() {
  await oversiteHelpers.init("YOUR_PAGE_ID");

  return; // Your code
}

Next.js (Pages Router)

pages/index.js

import { oversiteHelpers } from "./clients/oversiteHelpers";

//On production, consider using getStaticProps + revalidate or caching https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props#caching-with-server-side-rendering-ssr

export async function getServerSideProps() {
  await oversiteHelpers.init("YOUR_PAGE_ID");

  return; //Your code
}

export default function Home() {
  return; //Your code
}

---

How to use

Get All Instances

Next, you need to get all the instances from your current page (with the same pageId set in your Page data-pf attribute)

const helpers = oversiteHelpers.instances.get("homepage");

Retrieve Section Styles

Now , it is time to retrieve styles for a given section with its sectionId, you can do this by doing so:

const section = oversiteHelpers.section.parts(helpers.section.parts, "sectionId");
const section_outer = section("outer", "default_classes");
const section_inner = section("inner", "default_classes");

Retrieve Components Styles

For a component, get its styles by passing its groupId and instanceId, just do the following:

const component = helpers.component.parts("groupId", "instanceId");
const component_h2 = component("h2", "default_classes");

---

About Performances

For getting style changes, we recommended that your pages retrieve styles server-side so that there is no impact on your live website otherwise this will be a bad user-experience with layout shifts.

If you're using a vanilla-renderer, we recommend using a template. For other frameworks, you can check the integration examples above to see how it should be implemented.

---

Integration Examples

• Astro
• Javascript
• Next.js App Router
• Next.js Pages Router
• SvelteKit
• Vue.js