Migration to Hygraph Asset Management System

#Overview

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

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

Asset migration - action required

#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 URL that the Legacy Asset System uses, the new URL uses a regional subdomain and so it looks like this: 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.

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

media.graphassets.com/<transformations>/handle

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

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

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

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:

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.

The new Hygraph Asset Management system supports additional transformations:

• resize
• blur
• border
• compress
• crop
• quality
• sharpen
• auto_image
• output (File type conversions)

#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 or a local file, though the process is slightly different.

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

#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:

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.

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.

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:

{
  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

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

#Migration environment

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

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

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

#In-place migration

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

• 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

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

#Asset URLs in JSON fields

During the migration process, we go through every single String type 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 JSON field, but we don't automatically migrate them.

If your project uses JSON 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 a JSON field, and check if they contain media.graphassets.com. If they do, you should manually replace that URL with the new one.

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