# Create and install a Custom View

Learn how to create and install a Custom View in the Merchant Center deployed on Vercel.

The Merchant Center includes several built-in applications by default for managing entities such as Products, Categories, and Customers. While these applications offer robust functionality, you may encounter use cases that they do not cover. In such cases, you can extend the Merchant Center using a customization—either a Custom Application or a Custom View.

Custom Applications and Custom Views offer distinct user experiences and are suited for different use cases. We recommend that you read the [Merchant Center Customizations overview](https://docs.commercetools.com/merchant-center-customizations/overview.md) before starting this tutorial to understand how each customization type works within the Merchant Center.

In this tutorial, we'll walk you through how to create a Custom View to extend the functionality of a built-in application in the Merchant Center.

## Learning goal

At the end of this tutorial, you will have a Custom View that is:

- Hosted on Vercel.
- Accessible in the Merchant Center for your specific Organization and team(s).
- Displays Channels from your Project.

To get you there, we'll help you set up your development environment, deploy your Custom View to Vercel, and configure and install it in the Merchant Center. Once installed, you will be able to access your Custom View from inside one of the built-in applications.

## Prerequisites

Before you start, make sure that you have the following:

- A Merchant Center account or an [Identity account](https://docs.commercetools.com/docs/identity/overview.md).

- A Project with a few [Channels](https://docs.commercetools.com/merchant-center/project-settings.md#add-a-channel) added to it

- A [Vercel](https://www.vercel.com) account

- Basic knowledge of [React](https://react.dev) as well as some experience working with web applications

- [Node.js](https://nodejs.org/en/) installed (version `18.x`, recommended `>=20`)

- A Node.js package manager such as [`yarn`](https://yarnpkg.com/), [`pnpm`](https://pnpm.io/), or [`npm`](https://www.npmjs.com/get-npm)

  [Yarn PnP](https://yarnpkg.com/features/pnp) is not supported.

## Instructions

### Create the Custom View

To get started, open your terminal of choice and create a Custom View using the `create-mc-app` package. This package automatically sets up a pre-configured starter template.

```console noPromptLines="2-4"
npx @commercetools-frontend/create-mc-app@latest 
  my-new-custom-view-project 
  --application-type custom-view 
  --template starter
```

To start with a [TypeScript](https://www.typescriptlang.org/) project, use the `--template=starter-typescript` flag. For more information about developing customizations with TypeScript, see [Adding TypeScript](https://docs.commercetools.com/merchant-center-customizations/development/adding-typescript.md).

You may be prompted to install the latest version of the `@commercetools-frontend/create-mc-app` package. If this happens, press the `y` key, then the Enter key to continue.

#### Set configuration values

Next, you will be asked to provide basic information about your Custom View and commercetools Project. Be sure to take note of the values that you provide as you will need them later in the tutorial.

1. For the `initial project key for local development`, enter your unique commercetools Project key, then press Enter.
2. For `cloudIdentifier`, type the [cloud identifier](https://docs.commercetools.com/merchant-center-customizations/concepts/merchant-center-api.md#cloud-identifiers) for the region where your commercetools Project is located, then press Enter.

   By default, the starter template is configured to use the Project hosted in the [Europe (Google Cloud, Belgium) region](https://docs.commercetools.com/api/general-concepts.md#regions). If your Project is hosted in another region, you will need to set the `cloudIdentifier` according to the list of supported [cloud identifiers](https://docs.commercetools.com/merchant-center-customizations/concepts/merchant-center-api.md#cloud-identifiers).

At this point, the starter template will be downloaded and the Custom View will be configured with the values you provided. You may also notice that the package downloads the required dependencies. This can take a few minutes.

After everything is installed and configured, you will see a message in your terminal letting you know that the Custom View has been created.

#### Start the local development server

Now, let's start the local development server which lets you test your Custom View locally without needing to deploy it:

1. Navigate to the folder that contains your Custom View project:

   ```md
   cd my-new-custom-view-project
   ```

2. Start the server by issuing the `start` command:

   ```yarn
   yarn start
   ```

   ```pnpm
   pnpm start
   ```

   ```npm
   npm start 
   ```

Your browser will open a new tab pointing to the local development address of the Custom View at `http://localhost:3001`.

At this point, you will be redirected to the login page. When this happens, enter your account credentials, then click Sign in. Once you're authenticated, you will be brought back to the local development server and shown a page that simulates the rendering of your Custom View as if it was within a page in the Merchant Center.

If you can't log in to the Merchant Center, check the following:

- You provided the correct Project key and cloud identifier for your commercetools Project in the previous step.
- You are an administrator of the given Project.

Here's what the local preview looks like:

Image url: https://docs.commercetools.com/tutorials/images/create-custom-view/custom-view-loader.png Alt text: Custom View template home page

To open your Custom View and see how it is presented, click Open the Custom View.

### Configuration

The configuration file for your Custom View is named `custom-view-config.mjs` and is located in the root directory of your Custom View project.

Inside the configuration file, you can see some of the properties and values that we've previously set, along with some new ones.

On the local preview, you can see that the following settings have been configured:

(a CSV formatted table follows. The first line are the column names.)
Field,Description
Custom View ID,The unique identifier of the Custom View.
Custom View Permissions,The [permissions](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config.md#oauthscopes) granted to your Custom View for accessing your Project.
Custom View Locators,The [location(s)](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config.md#locators) in the user interface where the Custom View link appears.
Custom View Type,The [panel type](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config.md#type) of the Custom View. Currently, only `CustomPanel` is supported.
Custom View Size,The size of the Custom View which determines its layout and screen presence.


Let's go over a few of these fields to better understand them.

#### Permissions

Permissions determine which entities within your Project your Custom View can access. In the configuration file, the `oAuthScopes` field uses the [HTTP API scopes](https://docs.commercetools.com/api/scopes.md) to define permissions. It is best practice to only give the minimum amount of permission needed to accomplish your use case(s).

For this Custom View, we want to view and manage Channels, so we need the `view_products` and `manage_products` scopes. These two scopes are already defined in the starter template so you don't need to do anything else.

You can also set user permissions to determine whether to render components or hide certain user interface functionality. For more information, see [Apply user permissions](https://docs.commercetools.com/merchant-center-customizations/development/permissions.md#apply-user-permissions) in the Merchant Center Customizations documentation.

#### Locators

Locators define where your Custom View should be displayed within one or more built-in applications. In the Custom View configuration file, `locators` contains a list of location identifiers with each one following the pattern `<application>.<view>.<subview>`.

In our case, the `locators` field of the configuration file has the value `['products.product_details.general']`, this means that the Custom View should be displayed in the Products application, on the Product Details page and within the General tab.

To view a complete list of possible locations and their identifiers, see [Locators](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config.md#locators).

#### Size

The size of your Custom View is determined by the `typeSettings.size` field in the configuration file. Depending on your use case, you can modify this setting to provide the appropriate amount of space for your required functionality.

To learn more about panel sizing, see [design guidelines](https://docs.commercetools.com/merchant-center-customizations/concepts/design-guidelines/custom-views.md).

### Registration

At this point, you have a Custom View that you can interact with locally, but the Merchant Center doesn't know about it yet. Let's change that by configuring and adding the Custom View to the Merchant Center.

#### Initial configuration

First, set the initial configuration:

1. Open the Merchant Center and log in using your credentials.
2. Click the profile icon and select Manage organizations & teams.
3. Select the Organization for which you wish to configure a Custom View.
4. Click the Custom Views tab.
5. Click Configure Custom Views.
6. Add a contact email address for the developer or maintainer of the Custom View.

To proceed to the next step, you must first verify your email address. You only have to do this once.

#### Add the Custom View

Next, add the Custom View:

7. Click Add a Custom View.
8. Enter the following details:
   - Custom View name: `My Channels View`
   - Custom View URL: enter a placeholder value like `https://test.com`. We'll update this later after we deploy the Custom View.

#### Set permissions and menu options

The scopes that you define here must match the `oAuthScopes` values in the `custom-view-config.mjs` file. In our case, the template that we used added both the `view_products` and `manage_products` scopes to the configuration file automatically.

Now, let's add these scopes to the Merchant Center, then configure some additional settings:

9. In the Permissions > Default group section, add the scopes to the following fields:

   - OAuth Scopes for View: add the `view_products` scope.
   - OAuth Scopes for Manage: add the `manage_products` scope.

10. In the Custom View Menu section, enter or select the following values:
    - Link label: enter `View Channels`.
    - Entry points: select Product general page.
    - Custom Panel type, select Extended Custom Panel.

11. Click Register Custom View.

After registering your Custom View, you will be shown the Custom View ID. You will need this identifier in the next step when we deploy your Custom View.

### Deployment

Your Custom View is now installed locally on your machine and registered in the Merchant Center, however, it's not yet accessible there. To see it in the Merchant Center, you need to host the Custom View externally. In this section, we will walk you through how to deploy your Custom View to Vercel, a popular cloud hosting platform.

We offer deployment guides for many different hosts. To see a complete list of hosts, see the [Deployments](https://docs.commercetools.com/merchant-center-customizations/deployment/overview.md) page.

#### Configure and deploy using Vercel

To deploy to Vercel, do the following:

1. Create a Git repository and add the files from the `my-new-custom-view-project` folder to the root directory.

   If you created a local repository, you need to push those changes to the remote repository before proceeding to the next step.

2. Visit your Vercel dashboard and click Add New\..., then select Project.

3. Import your Git repository into Vercel and proceed to configure the project settings.

4. In the Build & Output Settings section, make the following changes:

   - Framework Preset: `Create React App`
   - Build Command: `yarn build`
   - Output Directory: `public`

   Image url: https://docs.commercetools.com/tutorials/images/create-custom-view/vercel-build-config.png Alt text: Vercel configuration

5. Click Deploy.

Your Vercel project will now create a deployment. Verify the deployment has the `Ready` status before proceeding.

#### Update the configuration

Next, we need to update the configuration file with information about the Custom View and where it is hosted.

Make the following changes to the `custom-view-config.mjs` file:

1. Add the Custom View ID (that you received after adding the Custom View to the Merchant Center) to the [`env.production.customViewId`](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config.md#envproductioncustomviewid) field.

2. Add the Vercel production URL of your deployed project to the [`env.production.url`](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config.md#envproductionurl) field. Be sure to include `https://` before your URL.

   Don't use the Deployment URL from the Vercel dashboard since this value changes each time your project builds. Instead, use one of the URLs listed under Domains.

   ```json title="Example"
   {
     "env": {
       "production": {
         "customViewId": "hxkhrl1i312sys6rjh1e6n3",
         "url": "https://<project>.vercel.app"
       }
     }
   }
   ```

   The preceding code snippet shows example values. You will need to provide your own values for `customViewId` and `url`.

3. Save the file and then push the changes to your remote repository.

Since Vercel is connected to your repository, it automatically starts a new deployment. Verify that the latest deployment has the `Ready` status before continuing to the next section.

### Install the Custom View in the Merchant Center

In the Merchant Center, your Custom View is in the Draft state. This means that the Custom View is not yet ready to be installed, and you can still make changes.

Once you're ready to install your Custom View in one or more Projects of an Organization where you have administrator rights, you move the Custom View to the Ready state.

Let's move the Custom View to the Ready state and install it:

1. Open the Merchant Center and log in using your Merchant Center credentials.
2. Click the profile icon and select Manage organizations & teams.
3. Select the Organization for which you wish to configure a Custom View.
4. Click the Custom Views tab.
5. Click Configure Custom Views.
6. Select your Custom View.
7. Update the Custom View URL with your Vercel project URL that you previously added to your configuration file.
8. Click Save.
9. Click the State dropdown, select Ready and confirm.
10. Select the Organization where the Custom View should be installed, then click Continue.
11. Scroll to the Projects access section, select Install for selected projects only and choose your desired Project.
12. Click Save.

Your Custom View is now installed in the Merchant Center for the Project that you specified. Let's verify that everything works by opening the Custom View:

1. Click Back to project to return to the Merchant Center homepage.
2. Select your Project from the Project dropdown.
3. From the Merchant Center main menu, go to Products > Product list.
4. Select any product from the list to open the product detail page.
5. Click the Custom View link My Channels View to open the Custom View.

Image url: https://docs.commercetools.com/tutorials/images/create-custom-view/custom-view-link.png Alt text: Custom View link

Here's what the Custom View looks like when opened:
Image url: https://docs.commercetools.com/tutorials/images/create-custom-view/custom-view-opened.png Alt text: Custom View opened

Nice work! You have successfully installed a Custom View in the Merchant Center.

## Summary

In this tutorial, you have learned how to create, deploy, and install a Custom View in the Merchant Center.

To learn more about what you can do with Custom Views, we recommend the following resources within the [Merchant Center Customizations documentation](https://docs.commercetools.com/merchant-center-customizations/):

- [Development overview](https://docs.commercetools.com/merchant-center-customizations/development/) - Learn development concepts for building and working with customizations.

- [Merchant Center API](https://docs.commercetools.com/merchant-center-customizations/concepts/merchant-center-api.md) - Learn about the Merchant Center API and how it helps you connect to commercetools APIs.

- [Integrate with your own API](https://docs.commercetools.com/merchant-center-customizations/concepts/integrate-with-your-own-api.md) - Learn about integration, authentication, and local development when using your own APIs.

## Related pages

- [Section overview page](https://docs.commercetools.com/tutorials.md)
- [Previous page: Create and install a Custom Application](https://docs.commercetools.com/tutorials/create-custom-application.md)