@nativescript-community/algolia

NativeScript plugin for Algolia search. This plugin is designed to mirror, as closely as possible, the structure of Algolia’s JavaScript client.

Table of Contents

• Installation
• Initialize the client
• Push Data
• Simple Search
• Advanced Search
• Configure
• Breaking Changes in Version 2
• Demos and Development
  • Repo Setup
  • Build
  • Demos
• Contributing
  • Update repo
  • Update readme
  • Update doc
  • Publish
• Questions

Installation

Run the following command from the root of your project:

ns plugin add @nativescript-community/algolia

Initialize the client

You first need to initialize the client. For that, you will need your Application ID and API Key. You can find both of them on your Algolia account.

import { Algolia } from "@nativescript-community/algolia";

const client = new Algolia('APP_ID', 'API_KEY');
const index = client.initIndex('items');

Push Data

Add or replace an existing object in your index with an updated set of attributes.

const contacts = [
    { 
        objectID: "1234567890",
        firstname: "John", 
        lastname: "Smith",
        zip_code: 78787
    },
    { 
        objectID: "987654321",
        firstname: "Billy", 
        lastname: "Bob",
        zip_code: 54321
    },
];

index.addObjects(contacts)
  .then(result => {
      console.log(result);
  })
  .catch(error => {
      console.log("ERROR!", error);
  });

Simple Search

With objects added to your index, you can now utilize the searching capabilities.

index.search("bob")
  .then(content => {
      console.log(content.hits)
  })
  .catch(error => {
      console.log("ERROR", error)
  });

Advanced Search

There is also the ability to pass in search parameters for more advanced searching such as geolocation. See available search parameters here.

index.search("", {
    aroundLatLng: "38.846693, -104.861354",
    aroundRadius: 200000 // meters
})
  .then(content => {
      console.log(content.hits);
  })
  .catch(error => {
      console.log("ERROR", error);
  });

Configure

Settings can be customized to tune the search behavior. For example, you can add a custom sort by number of followers to the already great built-in relevance:

index.setSettings({
  customRanking: ['desc(firstname)']
})
  .then(result => {
      console.log("Setting saved", result);
  })
  .catch(error => {
      console.log("ERROR", error);
  });

You can also configure the list of attributes you want to index by order of importance (ex: firstname = most important):

Note: Since the engine is designed to suggest results as you type, you'll generally search by prefix. In this case the order of attributes is very important to decide which hit is the best:

index.setSettings({
  searchableAttributes: [
    'lastname',
    'firstname',
    'company',
    'email',
    'city',
    'address'
  ]
})
  .then(result => {
      console.log("Setting saved", result);
  })
  .catch(error => {
      console.log("ERROR", error);
  });

Breaking Changes in Version 2

Switched to Promise based method calls instead of callbacks.

Before:

index.search('bob', function(content, err) {
  console.log(content.hits);
});

After:

index.search("bob")
  .then(content => {
      console.log(content.hits)
  })
  .catch(error => {
      console.log("ERROR", error)
  });

The method addObjects is now deprecated and has been removed and replaced with saveObjects.

Demos and Development

Repo Setup

The repo uses submodules. If you did not clone with --recursive then you need to call

git submodule update --init

The package manager used to install and link dependencies must be pnpm or yarn. npm wont work.

To develop and test: if you use yarn then run yarn if you use pnpm then run pnpm i

Interactive Menu:

To start the interactive menu, run npm start (or yarn start or pnpm start). This will list all of the commonly used scripts.

Build

npm run build.all

Demos

npm run demo.[ng|react|svelte|vue].[ios|android]

npm run demo.svelte.ios # Example

Contributing

Update repo

You can update the repo files quite easily

First update the submodules

npm run update

Then commit the changes Then update common files

npm run sync

Then you can run yarn|pnpm, commit changed files if any

Update readme

npm run readme

Update doc

npm run doc

Publish

The publishing is completely handled by lerna (you can add -- --bump major to force a major release) Simply run

npm run publish

Questions

If you have any questions/issues/comments please feel free to create an issue or start a conversation in the NativeScript Community Discord.