Connect your Hygraph project to Imgix

Imgix lets you create, transform, and optimize images and videos.

#What you can do with the Hygraph-Imgix integration

With the Imgix app, you can serve assets from your Hygraph project and from other Imgix sources to add to your content.

#Prerequisites to use this integration

You must have a Hygraph account. If you don't have one, you can create one here.
You must have a Hygraph project with at least one model.
You must have a Imgix account. If you don't have one yet, you can create one here.

Apps are environment specific. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

#Configure a source

The first thing we need to do is configure a source in your Imgix account. The configuration flow will vary depending on whether you want to serve assets from your Hygraph project or from one of the other configurable sources.

#Using assets from Hygraph

Create a new Imgix source, selecting Web Folder as a Storage Type. This document contains more details about the Web Folder source.
Enter the base URL for your Imgix source. If your Hygraph project is using the Legacy asset system, you will need to use https://media.graphassets.com/ as the base URL. If your project uses the Hygraph Asset Management system, follow the instructions below to obtain the URL, go to the Assets tab in the Hygraph app and right click any asset thumbnail, then select Copy Image Address at the bottom of the preview. Keep the part before /output=... and delete the rest.

Base URL example: If your copied URL is
```
https://eu-central-1-shared-euc1-02.graphassets.com/clv45iyzm039407umd5w7aemt/output=format:jpg/resize=width:59,height:59,fit:crop/clw6dt8hndhuu07w6tcaqt9h3
```
You should use the following as the base URL:
```
https://eu-central-1-shared-euc1-02.graphassets.com/clv45iyzm039407umd5w7aemt
```
Use the default Imgix subdomain or configure your own, and press the Deploy Source button.

Would you like to know more?

Checkout Imgix's documentation for more detailed instructions on configuring the Web Folder source.

#Using assets from other sources

This flow is different depending on the selected source. Check out Imgix's documentation for instructions on configuring your Imgix source.

#Install the Imgix app

Click here to install the Imgix App on Hygraph, then follow these steps:

The installation flow will vary depending on whether you want to serve assets from your Hygraph project or from one of the other configurable sources.

#Install using a Hygraph source

Use the dropdowns to select which project and environment you want to install the app in, then click Install app.
The permissions pop-up will display. Clicking Authorize app finishes the installation and takes you to the app configuration screen.
Next, you need to configure the app. To do that, you first need to select Webfolder as a source type in the Hygraph app configuration - this should be the default value.
Enter your imgix source domain in the Source URL field, prefixed with https://.
Source URL example
If you used my-assets during the creation of your Imgix source, then the Source URL would be https://my-assets.imgix.net.
Click Save config settings to finish the configuration process. A pop-up notification in the bottom right corner of the screen will indicate that the changes have been saved.

#Install using other sources

Use the dropdowns to select which project and environment you want to install the app in, then click Install app.
The permissions pop-up will display. Clicking Authorize app finishes the installation and takes you to the app configuration screen.
Next, you need to configure the app. To do that, you first need to select Other as a source type in the Hygraph app configuration.
Enter your imgix source domain in the Source URL field, prefixed with https://.

Source URL example
If you used my-assets during the creation of your Imgix source, then the Source URL would be https://my-assets.imgix.net.
Fill in the API Key field with an API key obtained from your Imgix account.

Pro Tip
To create a new imgix API key, use the dropdown menu in the top-right corner of the Imgix dashboard, then go to API Keys and select Generate new key.
The permission that is necessary for the app to access your assets is Asset Manager Browse.
Fill in the Source ID field with the ID if your Imgix source. To find your source ID, go to your Imgix dashboard, navigate to Sources, and select View on the source you want. You will find the source ID under the Source ID field.
Click Save config settings to finish the configuration process. A pop-up notification in the bottom right corner of the screen will indicate that the changes have been saved.

#Add the Imgix field to your model

Navigate to the Schema builder.
Select the model that you want to add the Imgix field to.
Select the Imgix field from the Add fields right sidebar.
Complete the Display name field, and the API ID will be auto-filled by the system. Optionally, you can also add a Description.
This screen also allows you to control different properties of your Akeneo field: you can allow multiple values, or you can localize the field, by selecting the checkboxes in the Field options section.
Click Add.

#Use Imgix in your Hygraph project

Navigate to the Content editor.
Select the view that you configured the Imgix for.
Click + Add entry to create a new entry or, alternatively, edit an existing entry by clicking on the pencil icon.
Locate the Imgix section of the screen and click on Add assets. This opens a new screen where you can select and add assets to your Hygraph content entry.
Select the asset(s) you want, and then click Add selected assets. If your Imgix Field configuration allows multiple values, you will be able to select multiple assets.
After selecting the asset(s) you want and returning to the content entry, your selection will display on the list. You can optionally use the six dots icon to drag and drop the assets on the list to organize them in the order you want, or click on the X on the right of an asset card to remove it form the list.
Finally, click Save or Save & Publish, as needed.

#Troubleshooting

These are known limitations due to the way Hygraph & Imgix work. Please read these carefully before using this app.

If you replace an asset file in Hygraph, it will not update and show the old version instead. Please delete the asset completely and create a new one if you want to change the displayed image.
Sometimes, fields might get clipped and the button to add or change assets might not be visible. Refreshing the page resolves the issue. This a rare but known bug for Hygraph apps. If the issue still persists after a refresh open an issue.

#Resources

imgix documentation