Nimbus App Template

Introduction

This is a template for creating apps for Nuvemshop/Tiendanube ecosystem using Nimbus Design System and the Nuvemshop/Tiendanube API. It functions as a monorepo, as it includes all the necessary code to start and maintain the front-end and back-end of the application.

This template provides a starter project for building standalone apps using the follwing technologies:

• React for the frontend, with Vite as a framework
• Node.js for backend, with Typescript

Prerequisites

Before getting started, make sure you have the following dependencies installed in your development environment:

• Node.js (version 14 or higher)
• This project runs with yarn modern (v3+)
• The created application always has permission to Write products. However, if the permission is changed on the Partner Portal, it is necessary to set Write products in order for the template to work. (Learn more about permissions)

Limitations and Considerations

• If you install the app in a demo store, it will only be possible to add a maximum of 10 products.
• Webehooks have not been implemented.
• The packages/app-template-node/config.json file simply stores the credentials of a store, and when the installation process is repeated, the old object is replaced by the new one.
• If you don't change the redirect URL in the Partners Portal to the port where the project is running, it won't be possible to authenticate the app or access the Product API.
• For the Product API to work, the app must have Write products permission.

App Template Flow

• To help you better understand the process, refer to the following App Template Flow.

How to use the App Template

1. Create a partner's account

• Please visit Partners Portal - Portuguese or Partners Portal - Spanish, access to create an account in case you haven't done so already. (Learn how to create an account - Portuguese or Learn how to create an account - Spanish)

2. Create an app

• If you haven't created an app on the Partners Portal yet, create one. (Learn how to create an app - Portuguese or Learn how to create an app - Spanish)

3. Clone this repository

• Clone this repository:

  git clone https://github.com/TiendaNube/nimbus-app-template-react.git

• Open the project in your code editor (e.g., Visual Studio Code, Eclipse, etc.).

4. Check yarn version

• This project will only work with yarn modern, specifically 3.6.0 or higher.

• In the terminal, check yarn version using the following command:

  yarn --version

• The image below represents the version of Yarn that should be the same or higher on your machine:

  

5. Install dependencies

• Go to the root file and in the terminal, install the project dependencies using the following command:

  yarn install

5. Install dependencies at node project

• Go to the packages/app-template-node file and in the terminal, install the project dependencies using the following command:

  yarn install

6. Install dependencies at vite project

• Go to the packages/app-template-vite file and in the terminal, install the project dependencies using the following command:

  yarn install

7. Get credentials from the Partners Portal

• Go back to the Partners Portal and navigate to the details page of your app.
• Then, copy the App ID and Client Secret, which are the authorization keys, in order to install your app on the stores.

8. Rename .env-example to .env and set environment variables

• Go back to your code editor:
  • Rename the .env-example file to .env.
  • Paste the credentials copied in the previous step into the .env file:
    • PORT=3400 (Port where the backend will run)
    • CLIENT_ID="App ID"
    • CLIENT_SECRET="Client Secret"
    • USER_EMAIL="Your Partners Portal account email"
    • APP_NAME="Your app name"
    • VITE_APP_TEMPLATE_API="http://localhost:3400"

9. Run applications

• At the root of the project to start both app-template-vite and app-template-node, run the following command:

  yarn dev

  

10. Change redirect URL at the Partners Portal

• After install app at store, go back to the Partner Portal:
  • Navigate to the details page of your app:
    • On the Edit app section go to Data Basics and click on Edit Data
  • Navigate to the update page of your app.
    • Change the Redirect URL to http://localhost:8000

11. Access the store and install the app

• Log in to your store (if you're not already logged in).
• To install the app, add admin/apps/:app-id/authorize to your store URL and confirm the installation. Here are the steps to follow:
  • Append admin/apps/:app-id/authorize to the URL, replacing :app-id with the App Id of your app:
    • Can be obtained from the .env file. Look for the file named .env and locate the value assigned to the variable CLIENT_ID inside that file;
    • Can be obtained from Partners Portal:
      • Navigate to the details page of your app.
      • Then, copy the App ID
  • With the modified URL, you will see a page similar to the image below:
    • Follow the prompts to confirm the installation of the app;

12. Test the app

• Now, your app is ready to use by following the steps below:
  • Create 5 products;
  • View the list of store products;

Support & Help

We are here to provide you with the support and assistance you need. If you have any questions or require further assistance, please don’t hesitate to reach out to us. Here are a few ways you can get in touch:

• Help Section: Visit Partners Portal help section for comprehensive resources and guidance.
• Issue Tracker: If you encounter any issues or bugs related to our project, you can create a new issue on our GitHub repository.
• Visit this link to access the issue tracker and provide detailed information about the problem you’re facing.
• Contact by Email: For any additional feedback, inquiries, or specific concerns, feel free to contact us via email. You can reach us at either ecosystem-feedback@nuvemshop.com.br or ecosystem-feedback@tiendanube.com.