Merge pull request #130 from nuxt-modules/feat/useAsyncAlgoliaSearch

Feat/use async algolia search

Author: Baroshem

README.md

@@ -15,16 +15,14 @@
 
 ## Features
 
-- Nuxt 3 ready
 - Easy integration with Algolia
-- Handy composables like useAlgolia, useSearch, etc
+- Handy composables like useAlgoliaSearch, useAsyncAlgoliaSearch
 - Support for Vue Instantsearch components
 - Support for Algolia Recommend
 - Support for Docsearch
 - Support for Automatic Indexing
 - Support for caching the requests and responses
 - Support for SSR requests
-- TypeScript support
 
 [📖  Read the documentation](https://algolia.nuxtjs.org)
 
@@ -43,38 +41,37 @@ npm i @nuxtjs/algolia # npm
 
 Firstly, you need to add `@nuxtjs/algolia` to your Nuxt config.
 
-```javascript
-// nuxt.config.js
-
-{
-    modules: [
-        "@nuxtjs/algolia",
-    ],
-    algolia: {
-        apiKey: "<YOUR_SEARCH_API_KEY>",
-        applicationId: "<YOUR_APPLICATION_ID>",
-    }
-}
+```js
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/algolia']
+})
+```
+
+Furthermore, add `ALGOLIA_API_KEY` and `ALGOLIA_APPLICATION_ID` environment variables to .env file.
+
+```env
+ALGOLIA_API_KEY="0fd1c4eba2d831788333e77c9d855f1d"
+ALGOLIA_APPLICATION_ID="AGN9HEEKF3"
 ```
 
-Then you can start using `@nuxtjs/algolia` in your setup function!
+Now you can start using `@nuxtjs/algolia` in your app!
 
 ```vue
-<script setup>
-const { result, search } = useAlgoliaSearch("test_index"); // pass your index as param
+<script setup lang="ts">
+// Client side
+const { result: data, search } = useAlgoliaSearch('test_index')
 
 onMounted(async () => {
-  await search({ query: "Samsung" });
-});
-
-// Or SSR
-onServerPrefetch(async () => {
   await search({ query: 'Samsung' })
 })
 
-// Or by using useAsyncData
-const { data } = await useAsyncData('ssr-search-results', () => search({ query: 'Samsung' }))
+// Or SSR
+const { data } = await useAsyncAlgoliaSearch({ indexName: 'test_index', query: 'Samsung' })
 </script>
+
+<template>
+  <div>{{ data.value.hits }}</div>
+</template>
 ```
 
 ## Development

docs/content/1.getting-started/1.quick-start.md

@@ -28,7 +28,7 @@ export default defineNuxtConfig({
 You can find more about configuring `@nuxtjs/algolia` [here](/getting-started/configuration).
 ::
 
-3. **Lastly, add [ALGOLIA_API_KEY](https://www.algolia.com/doc/guides/security/api-keys/) and [ALGOLIA_APPLICATION_ID](https://www.algolia.com/account/api-keys/) to the .env**
+3. **Add [ALGOLIA_API_KEY](https://www.algolia.com/doc/guides/security/api-keys/) and [ALGOLIA_APPLICATION_ID](https://www.algolia.com/account/api-keys/) to the .env**
 
 ```env
 ALGOLIA_API_KEY="0fd1c4eba2d831788333e77c9d855f1d"
@@ -38,22 +38,31 @@ ALGOLIA_APPLICATION_ID="AGN9HEEKF3"
 4. **Use Algolia in your application**
 
 ```vue
-<template>
-  <div>{{ result }}</div>
-</template>
-
-<script setup>
-const { result, search } = useAlgoliaSearch('test_index') // pass your index name as param
+<script setup lang="ts">
+// Client side
+const { result: data, search } = useAlgoliaSearch('test_index')
 
 onMounted(async () => {
-  await search({ query: 'Samsung' });
+  await search({ query: 'Samsung' })
 })
 
-// Or SSR by using useAsyncData
-const { data } = await useAsyncData('ssr-search-results', () => search({ query: 'Samsung' }))
+// Or SSR
+const { data } = await useAsyncAlgoliaSearch({ indexName: 'test_index', query: 'Samsung' })
 </script>
+
+<template>
+  <div>{{ data.value.hits }}</div>
+</template>
 ```
 
-5. **You're good to go!**
+::alert{type="success"}
+
+That's it! You can now use Algolia in your Nuxt app ✨
+
+::
+
+::alert{type="info"}
 
 Check out [how to use Algolia module further](/getting-started/usage){ .text-primary-500 }.
+
+::

docs/content/1.getting-started/2.configuration.md

@@ -8,27 +8,21 @@ description: ''
 You can add custom configuration to the module like following:
 
 ```js{}[nuxt.config.js]
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   modules: ['@nuxtjs/algolia'],
   algolia: {
-    apiKey: 'MY_API_KEY',
-    applicationId: 'MY_APPLICATION_ID'
+    // options
   }
 })
 ```
 
 Or
 
 ```js{}[nuxt.config.js]
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   modules: [
     ['@nuxtjs/algolia', {
-      apiKey: 'MY_API_KEY',
-      applicationId: 'MY_APPLICATION_ID'
+      // options
     }]
   ]
 })

docs/content/1.getting-started/3.usage.md

@@ -27,13 +27,7 @@ This composable works also for SSR applications and requests like this:
 <script setup lang="ts">
 const { result, search } = useAlgoliaSearch('test_index') // pass your index name as param
 
-onServerPrefetch(async () => {
-  await search({ query: 'Samsung' })
-})
-
-// Or by using useAsyncData
 const { data } = await useAsyncData('ssr-search-results', () => search({ query: 'Samsung' }))
-// You can access the search result by either `result` or `data`
 </script>
 ```
 
@@ -42,6 +36,26 @@ const { data } = await useAsyncData('ssr-search-results', () => search({ query:
 
 For more details check out the official documentation of this method [here](https://www.algolia.com/doc/api-client/methods/search/)
 
+## `useAsyncAlgoliaSearch`
+
+Async wrapper around `useAlgoliaSearch` composable that decreases the number of steps needed to use Algolia with `useAsyncData` while maintaining the same functionality. The response will have a form described [here](https://www.algolia.com/doc/api-reference/api-methods/search/#response) and will be wrapped around `useAsyncData` so you will have access to `data`, `error`, and other properties.
+
+```vue
+<script setup lang="ts">
+const { data, error } = await useAsyncAlgoliaSearch({ indexName: 'test_index', query: 'Samsung' })
+</script>
+
+<template>
+  <div>{{ data.value.hits }}</div>
+</template>
+```
+
+This composable accepts an object as a param with following properties:
+
+* `indexName` - the name of you index in Algolia dashboard. For more details about initializing index check out the official documentation [here](https://www.algolia.com/doc/api-client/getting-started/instantiate-client-index/javascript/?client=javascript#initialize-an-index). If you passed a global index in your module configuration, this property can be skipped.
+* `query` - a keywoard, sentence, or text that you want to search the index with.
+* `requestOptions` optional object with options for the request like filters. You can check more about is [here](https://www.algolia.com/doc/api-reference/api-methods/search/#method-param-requestoptions)
+
 ## `useAlgoliaFacetedSearch`
 
 Use this composable to search using facet values like `category`, `phone`.

docs/content/1.index.md

@@ -24,15 +24,12 @@ Nuxt module for first class integration with [Algolia](https://algolia.com).
 
 #extra
   ::list
-  - Nuxt 3 ready
-  - Easy integration with Algolia
-  - Handy composables like useAlgolia, useSearch
+  - Handy composables like useAlgoliaSearch, useAsyncAlgoliaSearch
   - Support for Vue Instantsearch components
   - Support for Algolia Recommend
   - Support for Docsearch
-  - Support for Automatic Indexing
+  - Support for Automatic Indexing with Storyblok
   - Support for caching the requests and responses
   - Support for SSR requests
-  - TypeScript support
   ::
 ::

playground/pages/index.vue

@@ -27,6 +27,9 @@ const { algolia: { docSearch } } = useRuntimeConfig()
 // Used to try the refresh of the component on options changes
 const indexName = ref('test_index')
 
+// AlgoliaSearch wrapped in useAsyncData
+const asyncResult = await useAsyncAlgoliaSearch({ query: 'Samsung', indexName: indexName.value })
+
 const { result, search } = useAlgoliaSearch(indexName.value)
 const { result: searchForFacetValuesResult, search: searchForFacetValues } = useAlgoliaFacetedSearch(indexName.value)
 const algolia = useAlgoliaRef()

src/runtime/composables/useAsyncAlgoliaSearch.ts

@@ -0,0 +1,25 @@
+/* eslint-disable no-redeclare */
+import type { RequestOptionsObject } from '../../types'
+import { useAlgoliaInitIndex } from './useAlgoliaInitIndex'
+import { useNuxtApp, useAsyncData, useRuntimeConfig } from '#imports'
+
+export type SearchParams = { query: string, indexName?: string } & RequestOptionsObject;
+
+export async function useAsyncAlgoliaSearch ({ query, requestOptions, indexName }: SearchParams) {
+  const config = useRuntimeConfig();
+  const index = indexName || config.algolia.globalIndex
+
+  if (!index) throw new Error('`[@nuxtjs/algolia]` Cannot search in Algolia without `indexName`')
+
+  const algoliaIndex = useAlgoliaInitIndex(index)
+
+  const result = await useAsyncData(`${index}-async-search-result`, async () => {
+    if (process.server) {
+      const nuxtApp = useNuxtApp()
+      nuxtApp.$algolia.transporter.requester = (await import('@algolia/requester-node-http').then(lib => lib.default || lib)).createNodeHttpRequester()
+    }
+    return await algoliaIndex.search(query, requestOptions)
+  })
+
+  return result
+}