Create a Custom Products Catalog App with the CLI (2024)

In This Article

Before you begin
Step 1 | Initialize the app
Step 2 | Set up the dashboard page
Step 3 | Add permissions
Step 4 | Set up Wix Stores
Step 5 | Install dependencies
Step 6 | Set up wrappers for our dashboard page component
Step 7 | Create hooks for our SDK calls
Step 8 | Create a "Create Product" component that defines both a modal and a button
Step 9 | Create an error message SVG
Step 10 | Create a dashboard page component
Create the Products() component
Step 11 | Test the app
Step 12 | Build and deploy the app

One of the ways that 3rd-party developers can extend the Wix ecosystem is by creating apps that appear in site owners' dashboards. These apps can work with data from the sites they’re installed on, such as Content Management System (CMS) data and business solution data like CRM.

This tutorial explains how to create a React app similar to our Custom Products Catalog template where users can add or remove products from a Wix Stores products catalog through a dashboard page.

We use the following technologies to create the app:

Wix CLI: Used to create, test, and deploy the app.
The Wix JavaScript SDK: Used to retrieve blog post data from the site.
Wix Design System: Used to display data on the dashboard page.

The end result will look like this:

We use the following steps to build the “Custom Products Catalog” app:

Initialize the app
Set up the dashboard page
Add permissions
Set up Wix Stores
Install dependencies
Set up wrappers for our dashboard page component
Create hooks for our SDK calls
Create a "Create Product" component that defines both a modal and a button
Create an error message SVG
Create a dashboard page component
Test the app
Build and deploy the app

Before you begin

Before getting started, make sure that:

You install Node.js (v18.16.0 or higher).
You install npm or yarn.
You're logged into your Wix Developer account. If you don't already have one, sign up for a Wix Developer account.

Step 1 | Initialize the app

We use the Wix CLI to initialize our "Custom Product Catalog" app. In the process of initializing our app, the Wix CLI automatically:

Creates a new app in the Wix Dev Center.
Sets up a new folder for your app in your local file system. The folder includes:
- A src folder containing initial boilerplate code for an app with a dashboard page.
- A package.json file containing your app dependencies.
Creates a local Git repository for your app.
Prompts you to set up a development site for testing your app.

To initialize the app:

Open a terminal and navigate to the folder where you want to create your app.
Run the following command:
Copy
```
1
```
Select A new Wix App.
Enter a name for your app. Let’s name our app Custom Products Catalog.
The CLI prompts you to choose a development site (test site), which you’ll use throughout this tutorial to run and test your app. You can choose an existing Wix site as your development site, or create a new one. Let’s select Create a new Development Site. The newly-created development site is automatically named something like Dev Site 5x2043, and can be found in your Wix account’s list of sites.
Follow the prompts to open the development site on your default browser. If the browser doesn’t open, install your app on your test site manually and skip the next step.
Click Agree & Add to install your app on your development site.
Back in the terminal, press Enter to select the default folder name (custom-products-catalog) for your app in your local file system.

You now have a new app in the Dev Center, a new folder in your local file system, and a local Git repository for developing and testing your app.

Step 2 | Set up the dashboard page

Now that you’ve initialized your app, you can run a local development server to see the app in action, and view local changes as you develop your app. The local development environment runs the app and its initial boilerplate code on the development site that you chose in the previous step.

To run a local development server for your app:

Navigate to your newly-created folder for your app.
Copy
```
1
```
Run the following command:
Copy
```
1
```
Press 1 to open the local environment in your browser. Your development site’s dashboard opens, and you can see your newly-created app’s dashboard page in the left sidebar. We add the content of our app’s dashboard page in the next step.

Your app is now running on your development site. As you develop your app, any changes made to your app’s code are reflected in real time on your development site.

If your changes don’t show up, try refreshing the page, or closing and reopening the development site.

Step 3 | Add permissions

In this step, we'll add permissions for the app. Every SDK API requires specific permissions to use. In this app, we will use the queryProducts(), createProduct(), and deleteProduct() functions in the Wix SDK’s Stores Products API to get a list of all products, and to add and delete them.

To use these functions, we need to give our app permission requirements in the Dev Center. Once we do this, anyone installing the app will be prompted to grant the specified permissions.

You can find the permission scopes you need for each API in the individual function’s page in the JavaScript SDK documentation.

Let’s first look for the permissions that we need in the Permission Scopes section of the queryProducts() function’s page.

The Permission Scopes section indicates that our app must have one of the permission scopes on the list to call the function. Let’s choose the Manage Stores - All Permissions permission scope. It works with createProduct() and deleteProduct() as well.

To add permission requirements for the app:

Go to your app's page in the Dev Center.
ClickPermissions in the left sidebar.
ClickAdd Permissions.
Enter Manage Stores - All Permissions in the Search by name or ID field.
Check the permission scope's checkbox under Choose Permission Scopes.
Click Save.

Step 4 | Set up Wix Stores

Our app integrates with Wix Stores, so we need to set up Wix Stores on our site, then reinstall the app so that our site request the required permissions:

Install the Wix Stores app on your test site. You can create some new products, or use the sample ones provided by Wix.
Note: Make sure to add Wix Stores in both the Dashboard and the Editor.
In your test site dashboard, select Apps > Manage Apps from the sidebar.
Delete your app from the site.
Open your app’s dashboard in the Dev Center.
Select Test Your App > Dashboard. Select your test site in the Site Selector. Follow the prompts to reinstall the app and approve the new permissions.
Note: You'll be prompted to create an extension before testing the app. Ignore this prompt and click Test Your App.

Step 5 | Install dependencies

Before we start coding our app, we need to install some npm packages. In your terminal, run the following commands:

Copy

The purpose of each of these packages will become clear as we progress.

Step 6 | Set up wrappers for our dashboard page component

It’s finally time to start writing some code!

Our plan in this tutorial is to create a React component that defines our dashboard page. We’re going to wrap this component with providers that will manage our data fetching and provide Wix styling for our dashboard page component.

To do this, we’ll create a higher-order component that will accept our dashboard page component and return it wrapped in the necessary providers.

To create the higher-order component:

Create a new file in your app's repo under src > dashboard named withProviders.tsx.
Import the react library, and then QueryClientProvider, QueryClient from @tanstack/react-query:
Copy
```
1
```
QueryClient and QueryClientProvider are parts of the react-query library that allow fetching, caching, synchronizing, and updating server state. QueryClient is a class that stores and manages queries and mutations. We will use it to manage our SDK calls. We make QueryClient available to our dashboard page component through the QueryClientProvider wrapper.
Import WixDesignSystemProvider:
Copy
```
1
```
WixDesignSystemProvider is a component from the @wix/design-system package that provides styling according to Wix's design system.
Create a new instance of QueryClient:
Copy
```
1
```
Write a function named withProviders to wrap our dashboard page component in QueryClientProvider and WixDesignSystemProvider.
Copy
```
1
```

Your complete withProviders.tsx file should look like this:

Copy

Step 7 | Create hooks for our SDK calls

Our dashboard page component will need to make SDK calls to query, create, and delete Wix Stores product data using React hooks. To simplify our component code we define these in a separate TypeScript file.

To create your app’s React hooks:

Create a new folder in your app's repo under src > dashboard named hooks.
Create a new file in src > dashboard > hooks named stores.ts.
Import products from Wix Stores so we can use the Wix Stores Products API:
Copy
See Also
8. Errors and Exceptions About the Consent Policy Web Page Element Not Found: How to Fix it
```
1
```
Import useWixModules:
Copy
```
1
```
This allows us to use the useWixModules() hook which allows us to make authenticated SDK calls in the code for our hooks.
Import useDashboard:
Copy
```
1
```
This is a React hook that provides access to the Dashboard SDK functions.
Import Tanstack Query's useQuery, useMutation, and useQueryClient:
Copy
```
1
```
- useQuery is used to handle our queryProducts() queries.
- useMutation is used to handle creating and deleting the site's products.
- useQueryClient retrieves a QueryClient instance. This instance contains a cache of the site's product data, which we update whenever we create or delete a product.
For more information about any of the above, see Tanstack Query's documentation.
Create a function to query the site's products named useProductsQuery(). Inside this function:
1. Use useWixModules(products) to get the queryProducts() function.
  Copy
```
1
```
2. Use useQuery() to manage queryProducts() calls:
  Copy
```
1
```
Your function should look as follows:
Copy
```
1
```
Create a function to create new products named useCreateProduct(). Inside this function:
1. Use useQueryClient() to get our QueryClient instance which we will use to update the cache of the site's product data:
  Copy
```
1
```
2. Use useDashboard() to get the showToast function so we can show a toast in our dashboard page when a product is created.
  Copy
```
1
```
3. Use useWixModules(products) to get the createProduct() function:
  Copy
```
1
```
4. Use useMutation() to manage our createProduct() call:
  Copy
```
1
```
5. Inside the mutation function, add code to show a toast on error or success.
  Copy
```
1
```
6. On success, we also need to update our cached product data. Add the following to the mutation’s onSuccess function:
  Copy
```
1
```
Your function should look like this:
Copy
```
1
```
Create a function to delete selected products named useDeleteProducts(). This function must accept a set of product IDs to delete, and a parameter called onSuccess which we'll use in our dashboard page code to define a function that runs when products are deleted.
This function is similar to useCreateProduct() except that its mutationFn must use deleteProduct() and its queryClient logic and toast messages must deal with product deletion.
Copy
```
1
```

Your complete stores.ts file should look like this:

Copy

Step 8 | Create a "Create Product" component that defines both a modal and a button

We need a button the user can press to create a product. We want that button to open a modal where the user can enter the name of the new product and confirm or cancel. To create this component, we do the following:

Create a new folder in your app's repo under src > dashboard named components.
Create a new file in src > dashboard > components named create-product.tsx.
Import:
1. React and useState.
2. Import the components of the Wix Design System required to create our modal.
3. Import icons from @wix/wix-ui-icons-common.
Copy
```
1
```
Import our useCreateProduct() function we created earlier:
Copy
```
1
```
Create a CreateProduct component to define the appearance and functionality of the modal. Use the following code:
Copy
```
1
```
Let’s break down the above code:
- Line 2: create a hook for our useCreateProduct() function.
- Lines 3-4: Initialize state variables to manage the product name and the visibility of the modal.
- Lines 6-9: Set up a function to toggle the visibility of the modal and reset the product name input whenever the modal is shown or hidden.
- Lines 13-15: Define a button with an 'Add' icon that toggles the modal's visibility.
- Lines 16-21: Configure the modal to close when it’s toggled or if the site owner clicks outside of it on the page.
- Lines 22-43: Configure the modal’s layout and content with:
  - A primary ‘Save’ button that is visible when a product name has been entered or displays a loader if createProduct is loading. When clicked, it creates a product and closes the modal.
  - A secondary 'Close' button. When clicked, it closes the modal
  - A FormField component that takes an input for the product name.

Your complete create-product.tsx file should look like this:

Copy

Step 9 | Create an error message SVG

If we fail to retrieve the site’s products when loading the dashboard page, we need the page to display an error message. Our error message will be an SVG image:

Create a new folder in your app's repo under src > dashboard named svg.
Create a new file in src > dashboard > svg named EmptyState_ServerError.svg*.
Add the following code for your svg file:
Copy
```
1
```

The svg produces the following image:

Step 10 | Create a dashboard page component

Finally, we have all the pieces in place to set up our dashboard page.

But first, let's rename our page to something more appropriate:

In your app's repo, navigate to src > dashboard > pages.
In the file page.json, change the value of "title" to "Custom Products Catalog".

Now, let's create the dashboard page itself:

Open the page.tsx file.
Delete all the contents - we're starting from scratch.
Add the following import statements:
Copy
```
1
```
Apart from withDashboard, you should be familiar with these from the previous files.
withDashboard is a higher-order component that initializes the Wix React SDK and the Wix Dashboard SDK. Components wrapped with withDashboard() and their children can use React SDK hooks like useWixModules(), and other Dashboard React SDK hooks like useDashboard(). We will be wrapping our dashboard page component with this component, which will allow us to use the hooks we defined in step 7.
Import everything we set up in the previous sections:
Copy
```
1
```
Create a function for our dashboard page component, called Products():
Copy
```
1
```
We will fill this in shortly.
Export Products, wrapped with our withProviders(), and with withDashboard().
Copy
```
1
```

Create the Products() component

It's finally time to make our dashboard page component.

Adding functionality for deleting products.
Creating the columns for our table of products.
Creating the page structure.

Deleting products

Let's start by setting up some functionality for deleting products.

We want to be able to select and delete multiple products at a time. To achieve this we need to do the following:

Use useState to create a new Set called productIdsToDelete to hold the IDs of the selected products:
Copy
```
1
```
Create a function to delete the products with IDs in productIdsToDelete, then empty productIdsToDelete.
Copy
```
1
```
Create a function to handle the selection/deselection of items via their checkboxes. If the product is already selected, remove its ID from productIdsToDelete. Otherwise, add its ID.
Copy
```
1
```
Get a list of the site's products:
Copy
```
1
```

Create the columns for our table of products

Nest, we need to create a table to display the site's products and allow users to delete them.

Our table will include columns for the following items:

Checkboxes for selecting products to delete.
Product images.
Product name and description.
Product price.
Product type.

We start by creating a variable called columns to hold the columns of our table. We use the useMemo hook with productIdsToDelete and addProductToDelete as dependencies so that the table will re-render whenever there is a change.

Copy

Inside the square brackets we add objects that define the layout and functionality of the table's columns. We will later pass this array as a prop to the table component. In each column, we use the render property whose value is a function that defines how the data from a product should be rendered in that column.

Add the following column objects:

Checkboxes - If the product's ID exists in productIdsToDelete, check the checkbox. If the state of the checkbox changes, trigger the addProductToDelete() function with the product's ID.
Copy
```
1
```
Product images - Use the Image component from the Wix Design System and feed it the image URL from the product object's nested media.mainMedia.image.url field.
Copy
```
1
```
Product name and description - Use a Box for layout with direction set to vertical and gap to 3px, indicating vertical stacking with a gap of 3px. Inside this box, add two Text components for the product's name and description.
Copy
```
1
```
Product price - Add the product's price prefixed with a dollar sign.
Copy
```
1
```
Product type - Add the product type.
Copy
```
1
```

Finally, the code for setting up our columns should look like this:

Copy

Create the page structure

We define our page as follows:

Define the Page element
Copy
```
1
```
Inside the Page element add a Page.Header element which contains the title and our CreateProduct component:
Copy
```
1
```
Next, in the Page element, add a Page.Content element.
Copy
```
1
```
Inside Page.Content, add nested conditional statements with the following logic:
Copy
```
1
```
Replace the comments with the following code:
1. Loading message.
  Copy
```
1
```
2. Error message
  Copy
```
1
```
Notice the code for the text button calls products.refetch() on click. This sends a new request to the server using the same query that was initially provided to useQuery when we called useProductsQuery() earlier.
1. Table with columns
  Copy
```
1
```
  This code displays our columns, the number of selected products over the total products, and a Delete button if the number of selected products is greater than 0.
  TableToolbar is a component for adding a toolbar at the top of the table. It contains 2 items. The first displays the number of products selected for deletion, the second is the Delete button.

Your complete code should look like this:

Copy

Step 11 | Test the app

Now that the app’s code is ready, you can test it locally using the Wix CLI.

To test your app, do the following:

Run a local development server for your app using the npm run dev command in your terminal. Your app’s dashboard page will now look like this:
Click the Add Product button and use the modal to add a product.
Select some products and click the Delete button.
If things don’t look right, open your browser’s developer tools and check for errors in the console.

Step 12 | Build and deploy the app

You have now fully developed an app that allows users to add or remove products from a Wix Stores products catalog through a dashboard page.

After testing your app and seeing that it works as expected, you can build and deploy your app.

Was this helpful?

Yes