---
title: Create admin link extensions
description: Create admin link extensions to direct users to relevant pages of your app.
source_url:
  html: 'https://shopify.dev/docs/apps/build/admin/admin-links/create-admin-links'
  md: 'https://shopify.dev/docs/apps/build/admin/admin-links/create-admin-links.md'
api_name: admin-extensions
---

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

***

## Requirements

Before starting this tutorial, you'll need:

* A [scaffolded Shopify app](https://shopify.dev/docs/apps/build/scaffold-app) with the `write_products` [access scope](https://shopify.dev/docs/api/usage/access-scopes#write_products)
* An upgraded [Shopify CLI on version 3.71 or higher](https://shopify.dev/docs/api/shopify-cli#upgrade)

***

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

***

## Step 1: Generate a new link extension template

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

## Terminal

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

```text
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
```

***

## Step 2: Modify the link extension toml

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

## shopify.extension.toml

```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](#step-3-translate-your-extension). | |
| `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](https://shopify.dev/docs/api/admin-extensions/latest/targets). | |
| `url` required | The relative path to a page in your app that the link opens. | |

***

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

##### shopify.extension.toml

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

```json
{
  "name": "My link title"
}
```

##### locales/fr.json

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

***

## Step 4: Test your link extension on a dev store

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

## Terminal

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

***

## Step 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](https://shopify.dev/docs/apps/launch/deployment/deploy-app-versions).

To deploy a new version run the following command:

## Terminal

```terminal
shopify app deploy
```

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

***