Skip to content

Getting started

Jump to bottom
Sarah Dayan edited this page May 7, 2020 · 5 revisions

Follow the few steps below to start using Unified InstantSearch E-Commerce.

  1. Push your data to Algolia (following the required data schema),
  2. Fork this GitHub repository to your own,
  3. Replace the values in src/config/index.js to better match your needs,
  4. Run npm run export (or yarn export) to build the JS and CSS files,
  5. Host and include the generated JS and CSS files on your front-end and start using!

Instructions

Prerequisites

To run and build the project, you need:

We use Yarn and recommend you use it too to install and manage dependencies. If you prefer using npm CLI (built-in with Node.js), make sure to delete yarn.lock to avoid having conflicting lock files.

Once you've picked either npm CLI or Yarn, we recommend you stick to this choice. Both tools generate different, incompatible lock files, which define what exact version of each dependency the project should use. Using both tools could break your final JavaScript file.

Forking and installing the project

We provide Unified InstantSearch E-Commerce as a repository that you can fork and run on your own.

To do so, you need to navigate to the original repository and click Fork at the top-right corner of the page. It creates a tracked copy of the repository on your GitHub account. Go to the fork and click the Clone or download to clone the project on your machine. We recommend you clone instead of downloading a ZIP archive so you can later easily update the project.

Once you've cloned the fork on your machine, you can add the original upstream repository to facilitate updates.

git remote add upstream https://github.com/algolia/ecomm-unified.git

When you clone the project for the first time, or when you update it with the latest changes, you need to install dependencies. It must happen before using any of the provided commands.

yarn # or `npm install`

Running the project locally

If you're customizing the project, you may want to test it out and see if it works before building it and adding it to your production website. We provide a fake e-commerce website in which you can run the project locally. It's useful to see your changes live while you're developing, and test them out before going to production.

yarn start # or `npm run start`

Previewing the project in production conditions

When running the project locally (with the start command), you're in a development environment that comes with tooling to help you code and debug more quickly. It has an impact on performance, which doesn't give you a realistic idea of how fast and fluid the final experience is. For this reason, we provide a way for you to preview the project in the same way as with the start command, but in production conditions.

yarn preview # or `npm run preview`
npx serve --port 5000 preview
open http://localhost:5000/

Exporting the project

Once you've customized the project and made sure it works properly, you need to export it into a JavaScript file that you then must include on your production website.

yarn export # or `npm run export`

Then, include the generated search.js and search.css files in your project.

Updating the project

Whenever we change the project, you can sync the latest changes in your fork.

git fetch upstream
git checkout master
git merge upstream/master

You need to test any change to your project to make sure it still works correctly in every environment where you intend to serve it. We're versioning the project using the Semantic Versioning convention, using tags for each release. Before syncing your fork, make sure whether the changes are breaking or not, and whether they are compatible with your changes.

Browser support

We support the last two versions of major browsers (Chrome, Edge, Firefox, Safari).

To support Internet Explorer 11, we recommend using polyfill.io. Add this script to your page to conditionally load polyfills:

<script src="https://polyfill.io/v3/polyfill.min.js?features=default,Array.prototype.find,Array.prototype.includes,Promise,Object.assign,Object.entries,Object.values,IntersectionObserver"></script>

Commands

You have access to a handful of command-line scripts to test your project during customization and build it once done.

You can run each command with npm or Yarn. For example, to run the start command, you can run either npm run start or yarn start.

Command Name Comments
start Run the project in development mode, within a fake e-commerce website.
preview Build the project for previewing in the context of a fake e-commerce website.
export Export the production JavaScript file to include in your website.
lint Look for linting issues (useful when customizing the project).
lint:js Look for linting issues in the JavaScript code.
lint:css Look for linting issues in the CSS/Sass code.
Clone this wiki locally