# App Framework migration guide

Learn how to migrate from UI Extension to the App Framework. This document covers how to declare your app for migration, create a setup page, work with the field or sidebar UIX, and how to update fields in your project to use the new app elements.

## 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**.

**Warning:**

You need to complete all three steps to successfully migrate from UI Extensions to the App framework.

At the end of the document, we also offer an [example](https://hygraph.com/classic-docs/app-framework/migration#step-by-step-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](https://app.hygraph.com/apps/new), 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](https://hygraph.com/classic-docs/app-framework/migration#2-create-a-setup-page) 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](https://hygraph.com/classic-docs/app-framework/register-an-app#elements) 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](https://hygraph.com/classic-docs/app-framework/migration#3-update-fields-to-use-the-new-app-elements).
   - `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](https://hygraph.com/images/classic-docs/app-framework/app-framework-migration-declare.png)

**Warning:**

You can add multiple UIX/App Elements under the same app, so as soon as the app is installed, users will be able to use all of the elements.

The <b>Elements</b> section of the form is explained in detail in <a href="/classic-docs/app-framework/register-an-app#elements">this document</a>.

## 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](https://hygraph.com/classic-docs/app-framework/migration#step-by-step-example), the final code for your app should look similar to this:

```jsx
// 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>
  );
};
```

```jsx
// 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](https://hygraph.com/classic-docs/app-framework/migration#step-by-step-example), the final code for your app should look similar to this:

```jsx
// 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>
  );
};
```

```jsx
// 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](https://hygraph.com/images/classic-docs/app-framework/app-framework-migration-updateelements.png)

## Step by step example

Imagine you have the following **Field UIX**:

```jsx
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**:

```jsx
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](https://hygraph.com/classic-docs/app-framework/migration#1-declare-your-app-for-migration), 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](https://hygraph.com/classic-docs/app-framework/migration#1-declare-your-app-for-migration).
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](https://hygraph.com/classic-docs/app-framework/migration#2-create-a-setup-page). 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](https://hygraph.com/classic-docs/app-framework/migration#3-update-fields-to-use-the-new-app-elements).

## Resources

- [App Framework:](https://hygraph.com/classic-docs/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:](https://hygraph.com/classic-docs/app-framework/register-an-app) Documentation for developers on how to register an app on the **Hygraph** platform.
- [Using app tokens:](https://hygraph.com/classic-docs/app-framework/app-tokens) Document on how to generate an app token for your app during installation.
- [Install an app:](https://hygraph.com/classic-docs/app-framework/app-installation) Step by step guide on how to install an app in your **Hygraph** project.
- [Delete an app:](https://hygraph.com/classic-docs/app-framework/delete-an-app) Documentation for developers on how to delete an app you have created.
- [First steps:](https://hygraph.com/classic-docs/app-framework/first-steps/overview) Comprehensive step-by-step guide on how to develop an app with custom field and sidebar elements.
- [Next.js starter:](https://hygraph.com/classic-docs/app-framework/quick-starters/nextjs) Document that guides you through the process of developing an app with a custom field using our `Next.js` starter.
- [API Reference:](https://hygraph.com/classic-docs/app-framework/api-reference/api-reference-common) Our App Framework API Reference.