Tutorial | Build a Locations App Using the Wix CLI

This tutorial demonstrates how to use the Wix CLI to build a Locations app on the Wix Platform. The Locations app allows site owners to easily manage their business locations and hours of operation. The app will contain a dashboard page with a list of the site owner’s business locations, and a button to edit the hours for each location.

The end result will look like this:

We use the following steps to build the Locations app:

1. Initialize the app.
2. Run a local development server for the app.
3. Develop the app using the Wix SDK.
4. Test the app on your development site.
5. Build and deploy the app.

Before you begin

Before getting started, make sure that:

• You have Node.js (v18.16.0 or higher).
• 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 Locations app. In the process of initializing our app, the Wix CLI automatically:

• Creates a new app in the Custom Apps page of your Wix Studio workspace.
• 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:

1. Open a terminal and navigate to the folder where you want to create your app.

2. Run the following command using npm or yarn:

   npm

   Copy

   yarn

   Copy

   If prompted, press y to install the @wix/create-app package.

3. Select Create a new Wix App.

4. Select Create a basic app.

5. Enter a name for your app. Let’s name our app My Locations App.

6. Back in the terminal, press Enter to select the default folder name ("my-locations-app") for your app in your local file system.

You now have a new app in the Custom Apps page, a new folder in your local file system, and a local git repository for developing and testing your app.

Step 2 | Run a local development server

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:

1. Navigate to your newly created folder for your app.

   Copy

2. Run the following command using npm or yarn:

   npm

   Copy

   yarn

   Copy

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

4. Follow the prompt 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.

5. Click Agree & Add to install your app on your development site.

6. Follow the prompt in your terminal to open the development site in your browser.

   

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.

Step 3 | Develop the app

In this step, we show how we develop our app further by coding our dashboard page. We use the queryLocations() function in the Wix SDK’s Locations API to get a list of our site’s business locations. Then we use React code to display the locations on our dashboard page.

Add API Permissions

Before we can use queryLocations() in our app, we need to add the appropriate permissions to our app. In the JavaScript SDK documentation, each API contains a Permission Scopes section with a list of all permission scopes that the API requires. In our example, we choose the Manage Locations permission scope.

1. Open the Custom Apps page and click your newly-created app.

2. Click Permissions in the left sidebar.

3. Click Add Permissions and search for Manage Locations. Note that you must type this manually as pasting the text doesn't work.

4. Check the Manage Locations permission box and click Save.

   

Install packages

We use the following packages for coding and designing our app’s dashboard page:

• @wix/business-tools: Business tools module for working with the Wix SDK Locations API.
• @wix/dashboard: Dashboard SDK for interacting with the site dashboard.
• @wix/design-system: The Wix Design System for designing our dashboard page using several design components.

The @wix/dashboard and @wix/design-system packages come pre-installed with the generated template, so you don’t need to install them. However, you do need to install the @wix/business-tools package. To do so, open your terminal and run the following command using npm or yarn:

npm

yarn

Write the code

We'll now write code to create a dashboard page for our app. We want the dashboard page to display a list of all the business locations in our site, and a button for editing each location’s hours of operation.

1. Open your app’s folder in your IDE. Then open the page.tsx file located in the src/dashboard/pages folder.

2. Delete the existing code in the file.

3. Add the following import statements to your file:

   Copy

4. Next, use React and components from the Wix Design System to create a display table for the list of locations in the dashboard, or an empty state message with an option to add a location if there is no location data. The useEffect hook fetches the location data using the queryLocations() function and updates the component's state accordingly. If the data is still loading, it displays a loading spinner. You can see the complete code for this example below.

Full Example Code

You now have a fully developed app with a dashboard page for site owners to manage their business locations and hours of operation.

Step 4 | Test the app

In the previous step, we wrote code for displaying a site’s business locations in the dashboard. However, our development site doesn’t yet have any business location content for the app to display. We need to add business locations to our development site, and test our app to see whether the table with our business locations appears.

To add business locations to your site:

1. Run a local development server for your app. Your app’s dashboard page will now look like this:

   

2. Click Add Location. This takes you to the Business Info Settings to add locations to your development site.

3. Add business locations to your development site.

4. Navigate back to your app’s dashboard page in the left sidebar. The page should now display a table with a list of the business locations that you just added.

You now have a working app with a dashboard page that lists your site’s business locations, and a button for editing the hours of operation.

Step 5 | Build and deploy the app

After testing your app and seeing that it works as expected, you can create a preview of your app, build your app, create and manage app versions, and publish your app.