# Migration to Hygraph Asset Management System

Migrate your assets from the legacy asset system to the Hygraph Asset Management System

## Overview

**Migrate to the Hygraph Asset Management System:**

- The new asset system migration tooling is only be available for Hygraph Studio.
- We will automatically migrate free projects that have not migrated by the **end of April, 2025**.
- Paid & Enterprise projects have an extended migration timeline until **end of May, 2025**.

At the moment, Hygraph projects can use one of two asset systems. Projects created after February 2024 will use the new **Hygraph Asset Management** system, while older projects will use the **Legacy asset system**.

This document discusses the differences between both systems and the migration flows available.

If your project uses the old asset system and needs to migrate to the new one, the UI will show you that an action is required:

![Asset migration - action required](https://hygraph.com/images/docs/api-reference/assets/asset-migration-required.png)

When you go to **Project Settings > Environments**, you will see this.

![Asset migration - action required](https://hygraph.com/images/docs/api-reference/assets/migration-required.png)

**Please note:**

- **Paid projects** can create a [test environment for asset migration](https://hygraph.com/docs/api-reference/assets/asset-migration#migration-environment), but **free projects** can't. 

- **All projects** can migrate the master environment and others ["in-place"](https://hygraph.com/docs/api-reference/assets/asset-migration#in-place-migration), turning them into read-only during migration. They can do this one environment at a time.

## Changes

The systems differ in four important areas. This section shows you a comparative view of these differences.

### Asset URL

The URL the new Hygraph Asset Management system uses to deliver assets slightly differs from the Legacy system.

Instead of the [`media.graphassets.com`](http://media.graphassets.com) URL that the Legacy Asset System uses, the new URL uses a regional subdomain and so it looks like this: [`regionalSubdomain.graphassets.com`](http://regionalSubdomain.graphassets.com). 

For example, if your project is hosted in our shared Germany (Frankfurt) region, the domain will be [`eu-central-1-shared-euc1-02.graphassets.com`](http://eu-central-1-shared-euc1-02.graphassets.com/).

Additionally, the old asset URL only contains a unique handle and some additional transformations following this format:

```json
media.graphassets.com/<transformations>/handle
```

The new Hygraph Asset Management system URL includes an additional environment identifier and an optional filename at the end:

```json
<regional-subdomain>.graphassets.com/<environmentId>/<transformations>/handle/filename.jpg
```

**Pro Tip:**

The optional filename at the end of the URL needs to match the filename used to upload the asset. 

The file extension (`jpg`, `webp`, etc.) needs to match the current version of the asset. If you convert a `jpg` to `webp` using URL transformations, that extension at the end needs to be `webp`.

#### environmentId

With the Hygraph Asset Management System, the asset URL includes the identifier `environmentId`, like so:

```json
<regional-subdomain>.graphassets.com/<environmentId>/<transformations>/handle/filename.jpg
```

This `environmentId` is the asset config `apikey` from a specific environment.

You can easily get this ID in the API Playground, from the management API:

```graphql
{
  viewer {
    project(id: "...") {
      environment(name: "master") {
        assetConfig {
          apiKey #<-- this is the "envID"
        }
      }
    }
  }
}
```

Select the `Management API` in the API Playground to get this information. To do this, use the menu at the top-left of the API Playground, like so:

![Management API in the API Playground](https://hygraph.com/images/docs/api-reference/assets/management-api-in-playground.png)

#### Next.js

For Next.js you will need a new configuration for the asset domain. Since the images are in the Hygraph CDN, you need to specify our domain in the `next.config.js` file. For more information, [check this guide](https://nextjs.org/docs/app/api-reference/components/image#remotepatterns).

```js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.graphassets.com',
      },
    ],
  },
};
```

#### Astro

For Astro you will need a new configuration for the asset domain. Since the images are in the Hygraph CDN, you need to specify our domain in the `astro.config.mjs` file:

```js
export default defineConfig({
  // ... Rest of the configuration
  image: {
    domains: ["https://**.graphassets.com"],
  },
});
```

### Transformations

The Legacy Asset system natively supported the URL transformations `resize` and `output`. 

**Pro Tip:**

If you were using other undocumented transformations, please reach out to us or check in the following information if the new system supports them.

The new Hygraph Asset Management system supports additional transformations:

- [resize](https://hygraph.com/docs/api-reference/assets/transformations#resize)
- [blur](https://hygraph.com/docs/api-reference/assets/transformations#blur)
- [border](https://hygraph.com/docs/api-reference/assets/transformations#border)
- [compress](https://hygraph.com/docs/api-reference/assets/transformations#compress)
- [crop](https://hygraph.com/docs/api-reference/assets/transformations#crop)
- [quality](https://hygraph.com/docs/api-reference/assets/transformations#quality)
- [sharpen](https://hygraph.com/docs/api-reference/assets/transformations#sharpen)
- [auto_image](https://hygraph.com/docs/api-reference/assets/transformations#auto-image)
- [output](https://hygraph.com/docs/api-reference/assets/transformations#file-type-conversion) (File type conversions)

**Pro Tip:**

**File Conversions (output)**

At the moment, the Hygraph Asset Management system only supports transformations between image mime types. [Check out this table to learn about this in detail](https://hygraph.com/docs/api-reference/assets/transformations#file-type-conversion).

If you were using more advanced transformations, like `xls to pdf` or other unsupported ones, please reach out to us and let us know.

### Uploading Assets via API

While the Legacy Asset System used the Asset Upload API, with the new Hygraph Asset Management system asset uploads are a part of the native GraphQL API. You can still upload assets using a [remote URL](https://hygraph.com/docs/api-reference/assets/uploading-assets#upload-by-remote-url) or a [local file](https://hygraph.com/docs/api-reference/assets/uploading-assets#upload-by-file), though the process is slightly different.

Size limits for uploaded files depend on the plan. [Check out our pricing page.](https://hygraph.com/pricing)

**Webhooks & asset uploads:**

Make sure you read our [webhooks documentation](https://hygraph.com/docs/api-reference/basics/webhooks#webhooks-and-assets) to understand how they work with the Hygraph Asset Management System.

#### Upload by file

**Uploading a local file** is now a two-step process. You will need to first call a `createAsset` mutation passing some basic information about the asset, and then use the returned information to send the actual file via a pre-signed URL. 

**Pro Tip:**

[Our documentation explains this process in detail](https://hygraph.com/docs/api-reference/assets/uploading-assets#upload-by-file).

#### Upload by remote URL

The **Upload assets by remote URL** method lets you upload assets in the GraphQL API by passing the URL of an asset hosted somewhere publicly accessible in the `createAsset` mutation.

Here's an example for you:

```graphql
mutation test {
  createAsset(
    data: {
			uploadUrl:"https://images.unsplash.com/photo-1682687218147-9806132dc697"
    }
  ) {
    id
    url
  }
}
```

### Upload Status

The new Hygraph Asset Management System handles the uploading process asynchronously, and so asset entries now have an **upload status**. 

**Warning:**

This is mostly relevant when using **Upload by file**, but also applies to **uploading via remote URL**, except we handle the fetching of the remote asset directly.

When first calling the `createAsset` mutation, the asset entry is created in an `ASSET_CREATE_PENDING` status while we wait for the file to be sent to us via the pre-signed URL. After successfully receiving the file, the status switches to `ASSET_UPLOAD_COMPLETE`. If there is an error, it will switch to `ASSET_ERROR_UPLOAD` instead. 

**Webhooks & asset uploads:**

Make sure you read our [webhooks documentation](https://hygraph.com/docs/api-reference/basics/webhooks#webhooks-and-assets) to understand how they work with the Hygraph Asset Management System.

If you do not send a file within the default time window, the asset entry stays in `ASSET_CREATE_PENDING` and might be cleaned up eventually. 

Be aware that all non-successful asset uploads are hidden by default on the API, but can be retrieved like this:

```graphql
{
  assets(where: {
    upload: {status_not_in: ASSET_UPLOAD_COMPLETE}
  }) {
    createdAt
    id
    publishedAt
    fileName
    url
    updatedAt
  }
}
```

### Upload Widget

The upload widget in the Hygraph UI is different depending on the asset system that your project uses.

Projects that use the new Hygraph Asset Management system can see a new upload widget within the webapp. For now, it only offers uploading a local file, but will soon be extended to also support uploading a remote URL. 

This is what it looks like at the moment:

![UI - Hygraph Asset Management system](https://hygraph.com/images/docs/api-reference/assets/hygraph-asset-management-system-ui.png)

Compared to this, the upload widget for the Legacy Asset system offers options to upload local files, upload using a remote URL, doing a web search, as well as using Facebook, Instagram and Google Drive:

![UI - Legacy Asset system](https://hygraph.com/images/docs/api-reference/assets/legacy-asset-system-ui.png)

**Note:**

If you'd like to see any of these options brought back or if you have additional suggestions, please let us know!

### Webhooks

If your project uses webhooks with the Hygraph Asset Management System, be aware that asset uploads are asynchronous. "Create" webhooks are triggered before uploads complete, causing potential issues if external systems expect assets to be available immediately.

The asset status starts as `ASSET_CREATE_PENDING` and switches to `ASSET_UPLOAD_COMPLETE` when ready.

Learn more about this process [here](https://hygraph.com/docs/api-reference/basics/webhooks#webhooks-and-assets).

## Migration environment

**Warning:**

**The new asset system migration tooling is only be available for Hygraph Studio.**

**Note:**

This option is only available for paid plans. Please [contact sales](https://hygraph.com/contact) for further information.

The resulting environment cannot be promoted to Master, but you can use it for testing purposes, to assess the impact of the migration and look into what additional actions you may need to take.

Every Hygraph project with a paid plan - Growth, Growth with add-ons, and Enterprise - will receive a free environment that allows you to clone your `master` environment using the new asset management system. 

To start the migration process using a test environment, go to `Project settings > General > Environments` and click `Configure migration`. 

Select `Clone Master environment with new asset system for testing` on the Asset migration popup.

![Migration environment](https://hygraph.com/images/docs/api-reference/assets/migration-environment.png)

Click `Start migration` to continue.

The newly created environment will be a one-to-one copy of your `master` environment with all your assets migrated to use the new system, including all the above mentioned changes.

The system assigns the new environment the name **Asset migration**, and a notification at the top of the screen informs you that the environment has been successfully migrated to the new asset system:

![Asset migration environment](https://hygraph.com/images/docs/api-reference/assets/asset-migration-environment-cloned.png)

In that migration environment, you can test how the new asset system behaves and if there are any breaking changes compared to your production environment.

[The comparison information](https://hygraph.com/docs/api-reference/assets/asset-migration#changes) in this document will help you spot potential issues. For instance, since we've explained that asset URLs change with the new system, you might want to look into where you are using those URLs that might need updating. 

**Warning:**

This migration environment can't be promoted to `master` and will be fully removed once the Legacy Asset System is deprecated. 

Please use it for testing purposes, before using our [in-place migration](https://hygraph.com/docs/api-reference/assets/asset-migration#in-place-migration) process. 

After cloning the migration environment, the `Clone Master environment with new asset system for testing` will no longer appear on the **Asset migration** popup

## In-place migration

**Warning:**

**The new asset system migration tooling is only be available for Hygraph Studio.**

The migration flow offers two options for in-place migration. You can migrate your Master environment or others you may have.

To start the migration process, go to `Project settings > General > Environments` and click `Configure migration`. 

On the **Asset migration** popup, select which environment you want to migrate to the new asset system:

![In-place migration options](https://hygraph.com/images/docs/api-reference/assets/asset-migration-options.png)

- `Migrate Master environment`: This option migrates your Master environment to the new asset system.
- `Migrate a specific environment other than master`: This option allows you to select other environments you may have. Please note that if you have more than one environment, you will eventually need to migrate all of them.

As this migration involves the risk of breaking changes, the system will prompt you to confirm that you have read our migration documentation:

![Asset migration warning](https://hygraph.com/images/docs/api-reference/assets/asset-migration-warning.png)

Click `Start migration` to continue. **Your environment will turn read-only for the duration of the migration process.**

During the migration process, the migration status displays on the left side of the screen:

![Migration in progress](https://hygraph.com/images/docs/api-reference/assets/asset-migration-callouts.png)

### Asset URLs in JSON fields

During the migration process, we go through every single `Markdown` and `Rich Text` field, and replace the old asset URL with the new one.

However, one field that could potentially store asset URLs as well is the `Single Line`, `Multiple Line`, and `JSON` field, but we don't automatically migrate them.

If your project uses these fields to store asset URLs, you will need to update them manually. To do so, you will need to go through all available content entries that use these fields, and check if they contain `media.graphassets.com`. If they do, you should manually replace that URL with the new one. This can also be done by using Content API filters.

## Migration & old URLs

Like we mentioned before, the new asset system uses slightly different URLs. Make sure to check for asset URLs stored in other places, such as source code or external systems.

**When will my old URLs stop working?:**

We will sunset the old asset domain after the **end of June, 2025**.