React Boilerplate for Custom Demos

Get started
Structure
Features Config
Dependencies
- State Manager
- Router
- Slider
- Select Menus
- Style
- Debounce
- Lazy Loading
- React i18
Develop on this project
- Before use please install

Pre-requisites

Before proceeding, please make sure you have the following:

Node v16.0.0+ installed
Yarn installed

⭐️ Get started

There are more visual step by step guides here

Clone this repo under a new name for your own demo. You can use the main branch that has some features turned off for easier integration
Run yarn in the root directory and yarn start to view your project on http://localhost:5173
Visit src/config and adjust algoliaEnvConfig to point to your own app, indices and API keys. If you do not need an index which is present in that file i.e. for articles, please do not remove it, just leave it as is, and you can turn off the relevant feature in the next step.
Visit src/config and adjust featuresConfig to activate/deactivate the features you would like to see in the app.
Go through the other files in src/config and adjust them according to your own data and requirements, each file describes itself.
In src/config , pay particular attention to hitsConfig as this is where we map your own attribute names to those used in the app. You should never adjust the attributes used in the app itself, only this map.
Run and test your app locally, if you have any questions or find any issues please raise an issue with us here https://github.com/algolia/algolia-react-boilerplate/issues.
In the src/scss folder, adjust any styling you need to based on what you see.
Preferrably you can use Netlify to deploy your project, but you can use other deployment tools.
Log into Netlify on the Algolia Demos team (again ask #help-demos if you don't have access) and deploy your demo from Github, making sure to password protect it!

⭐️ Structure

Index.jsx

entry point to the application
renders App.js into #root element in DOM
#root is defined in index.html

App.jsx

called by Index.jsx
wraps child components with key functionality including:
calls Main.jsx

Main.jsx

contains static elements like header and footer (found in ./components)
contains routes for each page (found in ./pages)
wraps pages in AnimatePresence from Framer Motion, which helps animate loading of pages
it loads a single route (page), depending on the current URL

Homepage.jsx

if federated search is true in configuration, loads federated search
loads a banners component from ./components
maps over carousels from configuration and renders each carousel
wraps all components in animations from framer-motion
Recommend components
- Trending Products

SearchResultsPage.jsx

called by Main.jsx for route /search
loads components related to results
Recommend components
- Trending Products
- Trending Facet Values

ProductDetails.jsx

Display attributes of an individual product
- Image
- Brand
- Name
- Colour
- Size
- Price
  - The price should display correctly according to the currency. Please check the price component file where you can change the decimals as well.

You can define whether you want each attribute shown by adjusting PDPHitSections in /config/hitsConfig

Recommend components
- Related Products
- Frequently Bought Together

🗳 Features Config

👀 Demo Tour

This app offers the ability to present a guided tour to the user, highlighting different elements and explaining them. The feature is currently in BETA, and is subject to change. It is on by default; it can be turned off by going to config/demoTourConfig and setting the default value of shouldShowDemoTour to false.

You can configure your tour by adjusting the steps const, also found in config/demoTourConfig.

👀 Network Error Messages

This feature will guide you to see what in the configuration is failing. We render the InstantSearch api errors in a modal.

You can turn this feature off by switching showNetworkErorrs default value to false in config/demoGuideConfig.

👀 Insights

On the product details page, if you have chosen not to show the size filter, you will see an add to cart button. By clicking this button, an event will be sent to algolia using the Insights API and an alert will be shown to the user.

👀 Redirects

Redirects are already activated in the application. In order to trigger one, simply create a rule in the dashboard where the consequence is:

{
 "isRedirected": true,
 "redirect": "URL TO REDIRECT TO GOES HERE"
}

You can find an example redirect rule by searching for qr-1634733813616 in rules/example-rules.json

👀 Federated Search

You can turn on federated search in config/featuresConfig by setting the default value of shouldHaveFederatedSearch to true. You can then define which sections are shown by going to config/federatedConfig.

👀 Voice Search

You can turn on voice search by going to config/featuresConfig and setting the default value of shouldHaveVoiceSearch to true.

👀 Sorts

You can turn on sorts by going to config/featuresConfig and setting the default value of shouldHaveSorts to true.

You can then define your sorts by going to config/sortByConfig and adjusting the values in the export called sortBy.

To sort by Price ascending or descending please configure the dashboard by creating a new virtual replica and name it exactly like the main index name and add _price_asc or _price_desc. Please see config/sortByConfig

👀 Carousels

You can turn on sorts by going to config/featuresConfig and setting the default value of shouldHaveCarousels to true.

Carousels are configured using rule contexts. You can configure your carousels by going to config/carouselConfig and adjusting the values for each context. You must ensure you have a rule in the algolia dashboard for each context, which pins products as this is what powers the carousels.

You can find an example carousel rule by searching for qr-1651497727816 in rules/example-rules.json.

👀 Recommend

Use FIG to generate the CSVs needed for Recommend, which you can then upload to the dashboard, and following this, enable FBT and Related in the appropriate config of this application.

We wrote a Gdoc to detail how use FIG. You can find it here.

Recommend is present in this app on the homepage, search results page, product details page, and also on the NoResultsPage.

Homepage: Trending products Results Page: Trending products and trending facet values PDP: Related and FBT NRP: Related

👀 Styling

You can adjust all of the styling of this application by adjusting anything found in the scss folder. It is recommended to start with the mixin folder.

👀 Demo Guide

The demo guide is opened by clicking on the three dots in the top right of the application and serves to guide the user through the features available in the app.

It is all defined and adjusted in config/demoGuideConfig and is self described.

🧱 Rules Applied Mode

In order to turn on this feature, go to config/demoGuideConfig and set shouldShowAppliedRulesSwitcher to true.

If turn to true you will find this feature in the Demo Guide panel. Switch on, you will find at the bottom of your screen information about the rules that are applied live while you are browsing the app. Switch off, no information will be disclosed. You can change description of the rules directly in the dashboard under the rule description input.

You might notice config/appliedRulesConfig file, please ignore it.

👀 Languages

In order to turn on this feature, go to config/featuresConfig and set shouldHaveLanguages to true.

Use it by making sure you have an index per language, and that the attribute names are always in the default language, but the values change in each index according to the local language.

Then, go to config/languagesConfig and adjust each export to what you need. Specifically, in languageSwitchConfig you must make sure each node has an index defined, and this index will be used when that language is selected.

👀 Banners

https://www.algolia.com/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/add-banners/

There are two types of banners in this demo - Homepage banners and Search Result Page banners. Check out the existing examples on the flagship fashion index to see some examples.

How Configure it 👇

In rules Section in the Dashboard, you have 2 'HomeBanner' rules without query conditions.
You can edit or duplicate one of these, and personalise the differrent fields:
- Images (For the background, or for the thumbnails)
- Link or Text for the buttons
- Titles and Subtitles
In the code you have a condition, actually they are called together, but you can keep by type :
- HomeBannerOne or HomeBannerTwo
The Search Result Page banners are generally set to queries (eg 'shoes'). It'll contain:
- type: set this to "bannersrp"
- title
- banner: this is an image url

You can find an example of a bannersrp rule by searching for qr-1634719042792 in rules/example-rules.json.

You can find an example of a homeBannerTwo rule by searching for qr-1645197289062 in rules/example-rules.json.

👀 Segments

You can add segments to the application to represent algolia being told that the current user has certain characteristics. It is not 1:1 personalisation and would be fed in by an external system such as Dynamic Yield.

These "segments" are sent to Algolia as optional filters, which are used to boost hits that match those filters.

Use this feature by adjusting config/segmentConfig and turn on or off this feature in config/featuresConfig.

👀 Badges

You can dynamically add badges based on any condition for an attribute returned in a hit.

There are two examples already defined in /config/badgesConfig, please follow the same example by adjusting that file.

When two triggers are matched, the one found first in the configuration array will be the one which is shown, more than one badge is not currently supported.

👀 Facet Display

Facet Display

The ability to control the facets which get displayed including their order. When adding your facets inside this app via config/refinementsConfig, you must ensure those facets are also added in the dashboard not just in the Facets section, but also in the Facet Display section, otherwise they will not show.

👀 Category Pages

In order to configure Category Pages, go to config/navigationConfig.

Edit the value for categoryPageFilterAttribute. This represents the attribute you will filter on to create your individual category pages.

Then you can adjust the linksHeader atom. The value for filter must match the value of the category you are filtering on to create the resulting page.

👀 Collection Pages

In order to configure Collection Pages, go in config/headerConfig. From there you can add links to the Navigation tab. Collection pages are powered by rule contexts. In order for this to work, you must set the type to context and make sure that you have a rule set up in the Algolia dashboard matching the context trigger which you define as the value of context.

You can find an example of a collection page rule by searching for qr-1651145630794 in rules/example-rules.json.

👀 No Results Page

To have the best UI, we defined the no results page with 3 parts:

First we just display the wrong query ex: yellow pant nike with an apologize message.
Secondly we incorporate the query suggestions to help the customer on navigation behaviour.
Third we stored, if the person already go on our website, his previous articles see. Them if he types a wrong query, we use Recommend and Related product with his last article seen, to create a carousel.

👩‍💼🧑‍💼 Personas

Personalization

To configure personalisation please first make sure you have the Personalization feature enabled on your plan, and that you have the correct strategy created. For example, if you want to boost colour: blue for a persona, you need to make sure that colour is in your strategy as a facet.

Then, you can visit config/personaConfig and update the values to match the user tokens you need to send, and update the personalizationFilters array to contain the attributes and values you want to boost for each persona. The description will also show up in the demo guide component.

You can also adjust the personalizationImpact number in config/personaConfig to control how much personalization applies to the results where personalization is turned on.

Personalization is currently active by default in the search results page, and in the main section (normally products) of the federated search.

The current user stories are:

Younger male 'Stephen James', likes Basketball and he lives in NYC. -Likes Sneakers, size 24, also likes tracksuit
Older female: 'Elizabeth Aniston', likes fashion and she lives in Paris. -Likes black dresses, size M, also likes blue jeans

💉 Injected Content

We use the Magazine Layout

There are two kinds of injected content:

Using rules in the main index
Using a seperate index

From Main Index

We have two kinds of rules. If you want to trigger these rules for your own demo, please use the given JSON source for the rules which you must add as a consequence (please edit the values as you see fit):

Free returns (always displayed)

You can edit the displayed hit by going to /components/hits/NoCtaCard.js

You can find an example of this injected content rule by searching for qr-1644582034227 in rules/example-rules.json.

Sales card ('nike' trigger)

You can edit the displayed hit by going to /components/hits/SalesCard.js

You can find an example of this injected content rule by searching for qr-1649055462539 in rules/example-rules.json.

From Seperate Index

You can edit the displayed hit by going to /components/hits/InfluencerCard.js

For this we define a new index in algoliaEnvConfig.js called injectedContentIndex and if there is a result in this index, we inject it as a result into the Hits.

Here is a sample record structure which is expected for records in the index to inject:

{
  "name": "Curry Stephen Under Armour",
  "gender": "Man",
  "influencer": {
    "name": "Stephen Curry",
    "slug": "steph_curry",
    "image": "https://about.underarmour.com/sites/default/files/styles/1600xauto/public/2020-11/SC_Curry%20Brand%20FW20%20%284%29.jpg?itok=Rx555Up8"
  },
  "category": "Shoes",
  "sku": "M0E20000000EL70",
  "objectID": "fab81fae69624_dashboard_generated_id"
}

Icons

This project comes with fontawesome added by default so you can adjust or add icons at will. It has been installed by being added in /src/assets/fontawesome/js/all.js and linked in the head tag of index.html

It is then as simple as adding in your HTML the correct fontawesome tags i.e. <i className="fa-solid fa-shopping-cart"></i>

🛒 Cart

This project comes with Cart feature based on what you'll put into it and it stores in Local Storage to have always your cart. It's linked to event sending Insights

⭐️ Dependencies

The Utility of this package is to wait before action, for example on the SearchBox, onChange wait some time before send query.

⏰ Lazy Loading

We use the React library Suspense and lazy to load components when needed, and a wrapper called lazily because the default react library doesn't support named exports.

⭐️ Translation

We use the React library React i18n, to translate all the content code part like Button, Title,.... And you have the Select option to switch between the languages. To start it's by default in english if you don't have any other language,you can just put false in the Translation Config option.

You have to use this feature configure your others language index, and make sure you have the correct facet translation for example

First Step: Go into the translation file and configure languages expected by default you are in english. If no other language is expected let just english be the default, or modify the content.
Second Step: Define the content translated in each language.
Third Step: In the selector file don't forget to define the i18 language for example actually, we have only ger fr and en, but add for example jap for japanese :
case 'Japanese': ... i18n.changeLanguage('jap');

⌨️ Develop on this project

To run this project locally, install the dependencies and run the local server:

👊 Before use please install

GitFlow

On Mac 👇

brew install git-flow-avh
git flow init

The repository is working around 3 branches :

main branch, this branch is created for you to be able to fork the project with features turned off
develop branch, this branch is our feature branch where we're adding new feature before pushing it into production
productionbranch, this branch is our stable production branch

Husky 🐶

npx husky install

maxhr / algolia-react-boilerplate Goto Github PK

algolia-react-boilerplate's Introduction