svelte-algolia - npm Package Compare versions

Comparing version 0.1.7 to 0.2.0

package.json

 {
   "name": "svelte-algolia",
-  "version": "0.1.7",
-  "description": "Algolia plugin for Svelte",
+  "description": "Algolia server-side index updater and client-side search component for Svelte projects",
+  "author": "Janosh Riebesell <[e-mail]>",
+  "homepage": "https://github.com/janosh/svelte-algolia#readme",
   "repository": "https://github.com/janosh/svelte-algolia",
-  "homepage": "https://github.com/janosh/svelte-algolia#readme",
   "bugs": {
     "url": "https://github.com/janosh/svelte-algolia/issues"
   },
-  "author": "Janosh Riebesell",
   "license": "MIT",
+  "version": "0.2.0",
   "type": "module",
-  "module": "src/main.js",
-  "dependencies": {
-    "algoliasearch": "^4.9.1"
-  },
-  "devDependencies": {
-    "ava": "^3.15.0",
-    "dotenv": "^8.5.0",
-    "eslint": "^7.25.0",
-    "prettier": "^2.2.1"
-  },
+  "svelte": "src/Search.svelte",
   "scripts": {
@@ -27,13 +18,18 @@ "test": "ava --node-arguments='--experimental-json-modules' --timeout=2m",
   },
-  "files": [
-    "src"
-  ],
   "keywords": [
+    "svelte",
     "algolia",
-    "plugin"
+    "plugin",
+    "search",
+    "server-side",
+    "client-side"
   ],
-  "prettier": {
-    "semi": false,
-    "singleQuote": true
+  "devDependencies": {
+    "algoliasearch": "^4.9.1",
+    "ava": "^3.15.0",
+    "svelte": "^3.38.2"
+  },
+  "publishConfig": {
+    "access": "public"
   }
-}
+}

readme.md

@@ -0,40 +1,66 @@
+<div class="hide-in-demo">
+
 <p align="center">
-  <img src="assets/banner.svg" alt="Banner" height=150>
+  <img src="site/static/banner.svg" alt="Svelte Algolia" height=150>
 </p>
 
-# svelte-algolia &nbsp; [![Test Status](https://github.com/janosh/svelte-algolia/workflows/Tests/badge.svg)](https://github.com/janosh/svelte-algolia/actions) ![NPM version](https://img.shields.io/npm/v/svelte-algolia?color=blue&logo=NPM) ![GitHub](https://img.shields.io/github/license/janosh/svelte-algolia)
+# Svelte Algolia
 
-This package was inspired by [`gatsby-plugin-algolia`](https://github.com/algolia/gatsby-plugin-algolia).
+[![Test Status](https://github.com/janosh/svelte-algolia/workflows/Tests/badge.svg)](https://github.com/janosh/svelte-algolia/actions)
+[![NPM version](https://img.shields.io/npm/v/svelte-algolia?color=blue&logo=NPM)](https://www.npmjs.com/package/svelte-algolia)
+[![Netlify Status](https://api.netlify.com/api/v1/badges/496f6094-b6b2-4929-ab16-ba2fdc61d57e/deploy-status)](https://app.netlify.com/sites/svelte-algolia/deploys)
 
+Utility for server-side Algolia index updates plus a client-side search component for Svelte apps. Only adds a single dependency on client and server: [`algoliasearch`](https://npmjs.com/package/algoliasearch).
+
+> The server-side part of this package was inspired by [`gatsby-plugin-algolia`](https://github.com/algolia/gatsby-plugin-algolia).
+
+</div>
+
 ## Usage
 
-1. Install with `yarn` or `npm`
+There are three steps to setting up `svelte-algolia`. First, get it from NPM, then setup your server-side index updates and finally integrate the client-side search component into your UI.
 
-   ```sh
-   yarn add -D svelte-algolia
-   ```
+### Installation
 
-   ```sh
-   npm i -D svelte-algolia
-   ```
+Install with `yarn` or `(p)npm`
 
-2. Create an `algoliaConfig` object:
+```sh
+yarn add -D svelte-algolia
+```
 
+```sh
+npm i -D svelte-algolia
+```
+
+### Server Side
+
+1. Create an `algoliaConfig` object:
+
    ```js
    import 'dotenv/config' // optional
 
+   function loadPokedex() {
+     const json = fs.readFileSync(`../package/tests/fixtures/pokedex.json`, `utf8`)
+     return JSON.parse(json).map(el => ({ ...el, id: el.someUniqAttribute }))
+   }
+
    const algoliaConfig = {
-     appId: process.env.algoliaAppId,
-     apiKey: process.env.algoliaAdminKey,
+     appId: process.env.ALGOLIA_APP_ID,
+     apiKey: process.env.ALGOLIA_ADMIN_KEY,
      indices: [
-       { name: `pokedex`, getData: pokemonDataLoader },
-       { name: `hitchHikersGuide`, getData: guideGetter },
+       { name: `Pokedex`, getData: loadPokedex },
+       { name: `Hitchhiker's Guide`, getData: guideLoader },
      ],
+    settings: {
+      attributesToHighlight: [`name`],
+    },
    }
    ```
 
-   The `getData` function is expected to return an array of objects containing the data you wish to index (a product catalog, blog posts, documentation pages, pokémons or whatever). Each object in the data array should have a key named `id` or `objectID` for Algolia to recognize it and overwrite existing data where appropriate.
+   The `getData` function is expected to return an array of objects containing the data you wish to index (a product catalog, blog posts, documentation pages, pokémons or whatever). Each object in the data array should have a key named `id`, `_id` or `objectID` for Algolia to recognize it and overwrite existing data where appropriate.
 
-3. Pass your config to `indexAlgolia`:
+   The settings object applies to all indices. You can also pass a settings object to each index individually which overrides the general one.
 
+2. Pass your config to `indexAlgolia`:
+
    ```js
@@ -48,3 +74,3 @@ import { indexAlgolia } from 'svelte-algolia'
 
-## Config Options
+#### Config Options
 
@@ -57,6 +83,6 @@ ```js
   // overwrites each index on every call to indexAlgolia()
-  matchFields: [], // (only used when partialUpdates is true) keys of fields to
-  // check for whether an item has changed; could e.g. be a timestamp, hash or
-  // an ID that's updated every time the item has changed; if not provided, items
-  // are checked for deep-equality to discover changes
+  matchFields: [], // (only used when partialUpdates is true) keys of fields to check
+  // for whether an item has changed; could e.g. be a timestamp, hash or an ID that's
+  // updated every time the item has changed; if not provided, items are checked for
+  // deep-equality to discover changes which can become slow for thousands of items
   settings: {}, // an object of Algolia index settings that applies to all indices
@@ -69,8 +95,8 @@ // see https://algolia.com/doc/api-reference/settings-api-parameters for available options
 
-## As a `rollup` plugin
+#### Auto-update Indices during Builds
 
-To use this package as part of a `rollup` build (e.g. in a Svelte or Sapper app), simply include it in your `plugins` array:
+To use this package as part of a build process (e.g. in a [SvelteKit](https://kit.svelte.dev) app), simply call `indexAlgolia` in your build config:
 
 ```js
-// rollup.config.js
+// svelte.config.js
 import { indexAlgolia } from 'svelte-algolia'
@@ -82,22 +108,79 @@
 
-// check if running in build or development mode
-const dev = process.env.NODE_ENV === `development`
+// only update Algolia indices on production builds (saves Algolia API quota)
+if (process.env.NODE_ENV === `production`) indexAlgolia(algoliaConfig)
+```
 
-export default {
-  input: './src/index.js',
-  output: {
-    file: './build/bundle.js',
-    format: 'iife',
-    name: 'bundle'
-    plugins: [
-      // to save Algolia indexing operations, you may want to only
-      // update your indices when building your app for production
-      !dev && indexAlgolia(algoliaConfig),
-    ]
+### Client Side
+
+`<Search />` needs your Algolia app's ID and search key to access its search indices as well as a mapping from index to corresponding Svelte-component that should render hits (items matching searches in that index). Each hit component receives a `hit` object as prop with all attributes stored in the Algolia index.
+
+```svelte
+<script>
+  import Search from 'svelte-algolia'
+  import PokemonHit from '../components/PokemonHit.svelte'
+
+  const appId = '0OJ5UL9OJX'
+  const searchKey = '63f563566cdd6de606e2bb0fdc291994'
+</script>
+
+<header>
+  <nav>{...}</nav>
+  <Search
+    {appId}
+    {searchKey}
+    indices={{ Pokedex: PokemonHit }}
+    placeholder="Search Pokedex" />
+</header>
+```
+
+For example, the `PokemonHit.svelte` component on the [demo site](https://svelte-algolia.netlify.app/) looks like this:
+
+```svelte
+<script>
+  export let hit
+</script>
+
+<h2>{@html hit.name}</h2>
+
+<div>
+  <ul>
+    <li>Type: {@html hit.type.join(`, `)}</li>
+    <li>Height: {@html hit.height}</li>
+    <li>Weight: {@html hit.weight}</li>
+    <li>Weaknesses: {@html hit.weaknesses.join(`, `)}</li>
+  </ul>
+  <img src={hit.img} alt={hit.nameOrig} />
+</div>
+
+<style>
+  /* highlights text matching the search string */
+  :global(em) {
+    color: darkcyan;
+    line-height: 1.2em;
+    border-radius: 3pt;
+    font-style: normal;
   }
-}
+  div {
+    display: flex;
+    justify-content: space-between;
+  }
+</style>
 ```
 
-## Contribute
+Substrings in attributes matching the current search string will be wrapped in `<em>` which need the `{@html ...}` tag to be rendered correctly but can then be styled to highlight why a particular hit matches the current search string. The original value (i.e. without `<em>` tags) of every highlighted attribute is available as `hit.[attr]Orig`. See `hit.nameOrig` above.
 
-PRs are welcome but best [open an issue](https://github.com/janosh/svelte-algolia/issues/new/choose) first to discuss changes.
+## Want to contribute?
+
+[PRs](https://github.com/janosh/svelte-algolia/pulls) are welcome but best [open an issue](https://github.com/janosh/svelte-algolia/issues/new) first to discuss changes.
+
+The repo is split into two workspaces, the `package` itself and the demo `site`. The app ID and search key `.env` were intentionally committed so you can clone this repo and work on it without having to create your own index first. To get a dev server running locally so you can try out changes in `package` as you make them, use
+
+```sh
+git clone https://github.com/janosh/svelte-algolia
+cd svelte-algolia/site
+sed -i '' 's/name: `Pokedex`/name: `Pokedex Clone`/' site/svelte.config.js
+yarn
+yarn dev
+```
+
+Note the `sed` command that changes the index name in [`site/svelte.config.js`](site/svelte.config.js) from `'Pokedex'` to `'Pokedex Clone'` so you don't accidentally mess up the search index for this demo site while developing.

src/main.js

@@ -72,3 +72,3 @@ /* eslint-disable no-console */
   results.forEach((obj) => {
-    if (!obj.objectID && !obj.id)
+    if (!obj.objectID && !obj.id && !obj._id)
       console.error(
@@ -79,3 +79,3 @@ `failed to index to svelte-algolia: ${JSON.stringify(obj, null, 2)}` +
     // convert to string to prevent processing items with integer IDs as new in partialUpdate
-    obj.objectID = `${obj.objectID || obj.id}`
+    obj.objectID = `${obj.objectID || obj.id || obj._id}`
   })
@@ -82,0 +82,0 @@ return results

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

105088

increased by826.13%

Dependency count

0

decreased by-100%

Dev dependency count

3

decreased by-25%

Number of package files

8

increased by100%

Lines of code

4829

increased by3015.48%

Number of lines in readme file

183

increased by83%

Worsened metrics

Number of low supply chain risk alerts

2

increased by100%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• - Removedalgoliasearch@^4.9.1

• - Removed@algolia/cache-browser-local-storage@4.24.0(transitive)

• - Removed@algolia/cache-common@4.24.0(transitive)

• - Removed@algolia/cache-in-memory@4.24.0(transitive)

• - Removed@algolia/client-account@4.24.0(transitive)

• - Removed@algolia/client-analytics@4.24.0(transitive)

• - Removed@algolia/client-common@4.24.0(transitive)

• - Removed@algolia/client-personalization@4.24.0(transitive)

• - Removed@algolia/client-search@4.24.0(transitive)

• - Removed@algolia/logger-common@4.24.0(transitive)

• - Removed@algolia/logger-console@4.24.0(transitive)

• - Removed@algolia/recommend@4.24.0(transitive)

• - Removed@algolia/requester-browser-xhr@4.24.0(transitive)

• - Removed@algolia/requester-common@4.24.0(transitive)

• - Removed@algolia/requester-node-http@4.24.0(transitive)

• - Removed@algolia/transporter@4.24.0(transitive)

• - Removedalgoliasearch@4.24.0(transitive)