Review of website and documentation from ElasticSearch/Algolia newcomer

[indicozy]

Hi there!

I've collected some issues that I got stuck with so other would not get stuck as I did.

Styling

I still did not really understand how styling is working on SearchKit, so I simply injected css into my pages. It would be a killer feature to support tailwindCSS though.

Connection

I'm new on using ElasticSearch, so I found it really hard to connect to ES's official managed service. I would recommend to create a new page on how to connect, get creedentials, set CORS and add API keys.

Hits

This page is confusing on how to create custom hits components. It was hard to create a separate component and adapt component's inputs. Maybe I did not understand properly, but I did in ugly way:

      <Hits
        hitComponent={({ hit }: { hit: any }) => (
          <HitView
            hit={hit}
            mutate={mutate}
            isSuccess={isSuccess}
            isLoading={isLoading}
            isError={isError}
            session={session}
          ></HitView>
        )}
      />

In this case, I could put HitView into parent component, but I'm not sure.

Comparison with other packages

It was hard to find what was the selling point of this library before trying every solution. Reactviesearch has their comparison table which sold me their library. After trying them out, I chose Searchkit due to its simplicity, customization and no third-party State Managers (Redux). We could add this table to Github or Web page.

Initial experience

Some key points on UX:

1. After looking to demo, code in hero and 5-minute tutorial, I thought that it was it. I did not even tried to find examples on header. By adding "Tutorials and Examples" button under video, it would be more intuitive.
2. By having interactive example code (CodeSandbox) in the Hero or other section, it would be easier to understand how it works. Website has example, video, demo and playground, but I think SandPack will improve initial experience.
3. Tutorials & Example page could be added to Docs' sidebar page.

Overall, Searchkit is brilliant solution to integrate ES to React. I'm more than happy to send PRs on updated website and/or docs!
@joemcelroy

[joemcelroy]

Thank you @indicozy

Connection

Would like a section providing an example on creating a read only key via curl and where to copy the ES host from within kibana.

If you're using ES cloud, we need a section detailing as you mentioned:

1. adding CORS (if you're not proxying the connection through node)
2. get ES host
3. create API key (though devtools)

Styling

Because instantsearch docs + community is so extensive with "how to customise", ive left that out. I definitely think a page under guides dedicated to customising instantsearch frontend components, with links to algolia's documentation and examples.

I do plan to get a tailwind demo style as Algolia's default theme is pretty dated. Would love someone to do a tailwind theme for instantsearch hint hint @royquilor 😂

Hits

So it should be:

const HitView = (props) => {
  return (
    <div>
      <h2>
        <Highlight hit={props.hit} attribute="title" />
      </h2>
      <br />
 
      <Highlight hit={props.hit} attribute="actors" />
    </div>
  );
};


export default function Search() {
  return (
    <InstantSearch searchClient={searchClient} indexName="movies">
      <SearchBox />
      <Hits hitComponent={HitView} />
    </InstantSearch>
  );
}

Comparison with other packages

This is a good idea. Theres a few things that other frameworks dont do and really need to shout more about Searchkit. Thanks for suggestion

Initial experience

Yeh I need a better docs entry page (get started should land on an index page full of links to demos, videos, codesandboxes, tutorials and quick starts). The https://www.searchkit.co/demos page is somewhat there.

Thanks for all these suggestions. If you want to help improve the docs, feel free to submit a PR on this!!

Joe

[royquilor]

Hey, I could create a Tailwind CSS version and update the UI

[indicozy]

Styling

I've now understood your target audience - Algolia Instantsearch to Elasticsearch users. Since I was very new on ES and Algolia, I did not know how to style it. I think we should still create basic styling page with link to Instansearch for further reading

[indicozy]

@royquilor I can help with UI update, could you please write your Discord or any other social account on my email: indicozy@gmail.com

[joemcelroy]

Styling

I've now understood your target audience - Algolia Instantsearch to Elasticsearch users. Since I was very new on ES and Algolia, I did not know how to style it. I think we should still create basic styling page with link to Instantsearch for further reading

Agreed. I was planning to do a page per frontend component (RefinementList, MenuFilter) and each page contains how to setup on Searchkit and links to Algolia API docs. Would love someone to help me on that!

[indicozy]

Thanks for reply,

I'm not familiar on some topics with SearchKit, but I can work on connection, demos and simple comparison page. Could you please explain here how to style with tailwind? Does it work outside of plain CSS?

[joemcelroy]

Yep! worth reading about it from algolia themselves https://www.algolia.com/blog/engineering/customizing-algolia-react-components-with-tailwind-classes/