[v1] options for plugins

Summary

How are users supposed to pass options for plugins?

Description

For now, we have only one plugin @algolia/autocomplete-plugin-recent-searches. User might want to customize it by overriding the part of source returned by the plugin, or the templates. We do not have an API at the moment.

There are two approaches.

1. Let plugins handle them

We can have a contract that plugins must accept a prop “source” and it will override the part of sources being returned by the plugin.

For example,

import { createRecentSearchesPlugin } from '@algolia/autocomplete-plugin-recent-searches';

const recentSearches = createRecentSearchesPlugin({
  key: 'recent',
  source: {
    getSuggestionUrl: ...,
    templates: {
      header: ...
    }
  }
});

The burden of merging them are delegated to the plugins, meaning that all the plugins will have the similar code.

2. Let the core handle them

When users add the plugin, they can specify the options.

const recentSearches = createRecentSearchesPlugin({ key: 'recent' });

autocomplete({
  ...
  plugins: [{ plugin: recentSearches, source: { ... } } ]

It’s similar to what Gatsby does:

module.exports = {
  plugins: ['gatsby-plugin-mdx'],
}

// or

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-mdx`,
      options: {
        defaultLayouts: {
          posts: require.resolve("./src/components/posts-layout.js"),
          default: require.resolve("./src/components/default-page-layout.js"),
        },
      },
    },
  ],
}

User can either pass a plugin itself or an object containing the plugin and the source option. And the core will deal with merging the source.

I’m more in favor the second way. What do you think?

[francoischalifour]

I think that we should remove this concern as a whole by moving this responsibility to plugin authors. If they need to support options, they would export a factory:

const plugin = createPlugin({ ...options, source: {} });

Perhaps the problem you had in mind was rather how to leverage the Autocomplete lifecycle in plugins? That’s a harder one because we need to spec that.

Example of spec with a getSources option

// Notice `sources` here which are the original sources from the plugin.
function pluginGetSources({ query, sources }) {
  if (!query) {
    return [];
  }

  return sources.map(transformOriginalSource);
}

const plugin = createPlugin({ ...options, getSources: pluginGetSources });

If that’s what you meant, solutions like Babel accept an array with the first item being the plugin, and the second being the options:

autocomplete({
  // ...
  plugins: [recentSearches, [customPlugin, { getSources: customPluginGetSources }]]
});

[francoischalifour]

Closing this since we went for (1) letting plugins handle options themselves.