Create admin link extensions

This tutorial will guide you through creating new admin link extensions for your app that let you direct merchants from key pages in the Shopify admin to contextually relevant pages in your app.

Anchor to RequirementsRequirements

Before starting this tutorial, you'll need:

A scaffolded Shopify app with the write_products permission
An upgraded Shopify CLI on version 3.71 or higher

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

Generate a new admin link extension
Modify the link extension .toml to change the extension's location and target page
Localize your admin link extension
Test your admin link extension's functionality with the CLI
Deploy your extension to all stores that have your app installed

Anchor to Step 1: Generate a new link extension templateStep 1: Generate a new link extension template

To create an admin link extension, generate a new extension from your app's directory.

Terminal

shopify app generate extension --template admin_link --name admin-link-extension

The command creates a new extension template in your app's extensions directory with the following structure:

Link extension structure

extensions/admin-link-extension

├── README.md

├── locales

│ ├── en.default.json // The default locale for the extension

│ └── fr.json // The French language translations for the extension

└── shopify.extension.toml // The config file for the extension

Anchor to Step 2: Modify the link extension tomlStep 2: Modify the link extension toml

After creating the template, you can modify its .toml file to change its behavior.

shopify.extension.toml

[[extensions]]

name = "My admin link extension"

description = "A link from the Shopify admin to my app"

handle = "admin-link"

type = "admin_link"

uid = "8834e3bb-1e59-d6f8-1653-f06442c722a6579bb5da"

[[extensions.targeting]]

target = "admin.product.action.link"

url = "/relative/app/to/path"

The [[extensions]] section defines the extension itself:

Property	Description	Rules
`name` required	The merchant-facing label that's shown for the link in the Shopify admin. Supports localization when the value starts with `t:` and references a key in your translation files, as shown in Step 3.
`description` optional	A merchant-facing description of the extension.
`handle` required	A unique identifier for the extension. It's used to reference the extension in configuration, APIs, and the Dev Dashboard.	- Must be unique across your app's extensions. - Can only contain alphanumeric characters and hyphens. - Can't be changed after you run `dev` or `deploy`.
`type` required	The extension type.	- Value must be `admin_link`.
`uid` required	The extension user identifier. An app-scoped identifier that `shopify app deploy` uses to determine whether an extension is being created, updated, or deleted. `uid` is created and managed by Shopify: it's generated automatically when you scaffold the extension with Shopify CLI, so you don't need to set or edit it manually.	- Must be unique within the app.

The [[extensions.targeting]] section defines where the link appears and where it points:

Property	Description	Rules
`target` required	The location in the Shopify admin where the link appears. For the full list of supported locations, refer to the admin extension targets.
`url` required	The relative path to a page in your app that the link opens.

Anchor to Step 3: Translate your extensionStep 3: Translate your extension

To translate your extension, you can use a localization key for the extension's title and add translation files with the corresponding key in the locales folder.

File

[[extensions]]

name = "t:name"

handle = "admin-link"

type = "admin_link"

uid = "8834e3bb-1e59-d6f8-1653-f06442c722a6579bb5da"

[[extensions.targeting]]

target = "admin.product.action.link"

url = "/relative/app/path"

{

"name": "My link title"

}

{

"name": "Mon titre de lien"

}

shopify.extension.toml

[[extensions]]
name = "t:name"
handle = "admin-link"
type = "admin_link"
uid = "8834e3bb-1e59-d6f8-1653-f06442c722a6579bb5da"

[[extensions.targeting]]
target = "admin.product.action.link"
url = "/relative/app/path"

locales/en.default.json

{
  "name": "My link title"
}

locales/fr.json

{
  "name": "Mon titre de lien"
}

Anchor to Step 4: Test your link extension on a dev storeStep 4: Test your link extension on a dev store

To test your admin link extension, try running your app locally.

Terminal

shopify app dev

Once your app is running, navigate to the target location and verify that the link takes you to the correct page of your app when it is clicked.

Anchor to Step 5: Deploy your link extensionsStep 5: Deploy your link extensions

After you've tested your admin link extension, you can release the changes to users by deploying a new app version.

To deploy a new version run the following command:

Terminal

shopify app deploy

Releasing an app version replaces the current active version provided to stores that have your app installed.

Was this page helpful?