App Framework migration guide

#Overview

This document covers the migration process from UIX to app. In order to follow this guide, you need to have access to our App Framework.

At the end of the document, we also offer an example you can follow.

#1. Declare your app for migration

Follow these steps to declare your app for migration:

1. Access our App registration page, and fill in the form details:
2. Write a Name and, optionally, a Description for your app. Then, add an Avatar URL. This is is the logo that will display next to your app's name. Name, Description, and Avatar URL are later on shown to users in the installation URL.
3. API ID decides the final installation URL for your app. For instance, the installation URL could be something like https://app.hygraph.com/apps/my-app/new.
4. Setup URL is where the app is configured or installed. For an app you'll need a setup page where updateInstallation SDK method has to be called, and a page where the Element (UIX) is deployed. This document section provides additional information on how to create your Setup Page but, essentially, in your Setup URL, you can show users a custom installation form for them to enter the API_KEY and then call updateInstallation(accessed via useApp hook).
5. For the purpose of this document, consider Elements to be a synonymous of UIX. This document contains detailed information on how to use the Elements form. For migrations, please consider the following:
   • Description & Name: This information is rendered in the Field card in the Schema Editor.
   • Type: If you're migrating from a Field UIX, select Field as Element type. If you're migrating from a Sidebar UIX, then use formSidebar instead.
   • Features: Element features indicate where the App Element should be used instead of native Hygraph Renderers.
   • URL: Element URL is what we render in the iframe.
   • Config: This is the same as declaration fieldConfig, and it's used to set up instance config.

Declare your app for migration

#2. Create a Setup Page

The next step is to make a Setup Page and update your UIX code:

1. Replace @graphcms/uix-react-sdk with package @hygraph/app-sdk-react (if you're using vanilla JS SDK @graphcms/uix-sdk then replace it with @hygraph/app-sdk), and update the import accordingly.
2. Remove declaration from Wrapper.

#Field UIX

If you used a Field UIX code, like the one shown in our examples section, the final code for your app should look similar to this:

// Setup page

import { useApp, Wrapper } from '@hygraph/app-sdk-react';

const SetupForm = () => {
  const { installation, updateInstallation } = useApp();
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        updateInstallation({
          config: {
            API_KEY: e.currentTarget.elements.API_KEY.value,
          },
          status: 'COMPLETED',
        });
      }}
    >
      <input type="text" name="API_KEY" />
      <input type="submit" value={'Install App'} />
    </form>
  );
};

const SetupPage = () => {
  return (
    <Wrapper>
      <SetupForm />
    </Wrapper>
  );
};

// Field

import { Wrapper, useFieldExtension } from '@hygraph/app-sdk-react';

function MyField() {
  const { value, onChange, installation } = useFieldExtension();
  console.log(installation.config);

  return <input value={value} onChange={(e) => onChange(e.target.value)} />;
}

export default function MyCustomInputExtensionPage() {
  return (
    // no declaration
    <Wrapper>
      <MyField />
    </Wrapper>
  );
}

#Sidebar UIX

If you used a Sidebar UIX code, like the one shown in our examples section, the final code for your app should look similar to this:

// Setup page

import { useApp, Wrapper } from '@hygraph/app-sdk-react';

const SetupForm = () => {
  const { installation, updateInstallation } = useApp();
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        updateInstallation({
          config: {
            API_KEY: e.currentTarget.elements.API_KEY.value,
          },
          status: 'COMPLETED',
        });
      }}
    >
      <input type="text" name="API_KEY" />
      <input type="submit" value={'Install App'} />
    </form>
  );
};

const SetupPage = () => {
  return (
    <Wrapper>
      <SetupForm />
    </Wrapper>
  );
};

// Sidebar

import { useFormSidebarExtension, Wrapper } from '@hygraph/app-sdk-react';

function SidebarElement() {
  const { extension } = useFormSidebarExtension();
  return (
    <div>
      <h3>Sidebar Example</h3>
      <button onClick={() => alert('Hello, Hygraph!')}>Click Me</button>
    </div>
  );
}

export default function Sidebar() {
  return (
    <Wrapper>
      <SidebarElement />
    </Wrapper>
  );
}

#3. Update fields to use the new App Elements

Once a user has installed the app - updateInstallation is called with status COMPLETED - they can Navigate to the Schema editor, and update their fields, previously used by UIX, to use the new App Element by selecting it from the dropdown as shown in the example below:

Update fields to use the new App Elements

#Step by step example

Imagine you have the following Field UIX:

import { Wrapper, useFieldExtension } from '@graphcms/uix-react-sdk';

function MyField() {
  const { value, onChange } = useFieldExtension();
  return <input value={value} onChange={(e) => onChange(e.target.value)} />;
}

const declaration = {
  extensionType: 'field',
  fieldType: 'STRING',
  name: 'My custom field',
  features: ['FieldRenderer', 'ListRenderer'],
  config: {
    API_KEY: {
      type: 'string',
      displayName: 'API Key',
    },
  },
};

export default function MyCustomInputExtensionPage() {
  return (
    <Wrapper declaration={declaration}>
      <MyField />
    </Wrapper>
  );
}

Or the following Sidebar UIX:

import { Wrapper, useFormSidebarExtension } from '@graphcms/uix-react-sdk';

const SidebarElement = () => {
  const { extension } = useFormSidebarExtension();

  return (
    <div>
      <h3>Sidebar Example</h3>
      <div>
        <button onClick={() => alert('Hello, Hygraph!')}>Click Me!</button>
      </div>
    </div>
  );
};

const declaration = {
  extensionType: 'formSidebar',
  name: 'Sidebar name',
  description: 'Sidebar description',
};

const SidebarExample = () => {
  return (
    <Wrapper declaration={declaration}>
      <SidebarElement />
    </Wrapper>
  );
};

export default SidebarExample;

With UIX you can deploy it on any platform - e.g. Vercel, Netlify, Render, etc. - and share the URL with people who'd like to use the extension.

In this case, people could then go to project > project settings > UI Extensions and add your UIX to their project, which can then be used in place of native Hygraph native renderer.

For an app the process is different. As we mentioned before, you'll need a setup page where updateInstallation SDK method has to be called, and a page where the Element (UIX) is deployed.

To migrate this example from UIX to app follow these steps:

1. Declare your app for migration as explained in detail here.
2. If users tried to install the UIX shown in the example above, they'd be able to add API_KEY from Hygraph's UI, but for apps this is done by the app developer. In this step, you will create a setup page, as shown here. In your setup page, you can render a form for users to enter API_KEY and then call updateInstallation({status: "COMPLETED", config:{ API_KEY: "API Key input value" }}) (accessed via useApp hook). config provided to updateInstallation hook is just like global config for UIX and can be accessed in Field App Element.
3. Once updateInstallation is called with status COMPLETED, you can navigate to the Schema editor and update your fields to use the new App Elements, as shown here.

#Resources

• App Framework: Overview to our App Framework, which extends Hygraph capabilities, offering the possibility of creating your own custom apps and sharing them with other users.
• Register an app: Documentation for developers on how to register an app on the Hygraph platform.
• Using app tokens: Document on how to generate an app token for your app during installation.
• Install an app: Step by step guide on how to install an app in your Hygraph project.
• Delete an app: Documentation for developers on how to delete an app you have created.
• First steps: Comprehensive step-by-step guide on how to develop an app with custom field and sidebar elements.
• Next.js starter: Document that guides you through the process of developing an app with a custom field using our Next.js starter.
• API Reference: Our App Framework API Reference.