fix(instantsearch): warn deprecated usage of searchParameters (#4151)

Author: francoischalifour

.storybook/decorators.ts

@@ -28,12 +28,6 @@ export const withHits = (
   const search = instantsearch({
     indexName,
     searchClient: algoliasearch(appId, apiKey),
-    searchParameters: {
-      hitsPerPage: 4,
-      attributesToSnippet: ['description:15'],
-      snippetEllipsisText: '[…]',
-      ...searchParameters,
-    },
     routing: {
       router: {
         write: (routeState: object) => {
@@ -47,6 +41,15 @@ export const withHits = (
     ...instantsearchOptions,
   });
 
+  search.addWidget(
+    instantsearch.widgets.configure({
+      hitsPerPage: 4,
+      attributesToSnippet: ['description:15'],
+      snippetEllipsisText: '[…]',
+      ...searchParameters,
+    })
+  );
+
   const containerElement = document.createElement('div');
 
   // Add the preview container to add the stories in

src/lib/InstantSearch.js

@@ -7,10 +7,12 @@ import version from './version';
 import createHelpers from './createHelpers';
 import {
   createDocumentationMessageGenerator,
+  createDocumentationLink,
   findIndex,
   isPlainObject,
   mergeDeep,
   noop,
+  warning,
 } from './utils';
 
 const withUsage = createDocumentationMessageGenerator({
@@ -48,7 +50,7 @@ class InstantSearch extends EventEmitter {
     const {
       indexName = null,
       numberLocale,
-      searchParameters = {},
+      searchParameters,
       routing = null,
       searchFunction,
       stalledSearchDelay = 200,
@@ -88,6 +90,23 @@ See: https://www.algolia.com/doc/guides/building-search-ui/going-further/backend
       throw new Error('The provided `insightsClient` must be a function.');
     }
 
+    warning(
+      !searchParameters,
+      `The \`searchParameters\` option is deprecated and will not be supported in InstantSearch.js 4.x.
+
+You can replace it with the \`configure\` widget:
+
+\`\`\`
+search.addWidgets([
+  configure(${JSON.stringify(searchParameters, null, 2)})
+]);
+\`\`\`
+
+See ${createDocumentationLink({
+        name: 'configure',
+      })}`
+    );
+
     this.client = searchClient;
     this.insightsClient = insightsClient;
     this.helper = null;

src/lib/__tests__/InstantSearch-test.js

@@ -1,6 +1,7 @@
 import algoliaSearchHelper from 'algoliasearch-helper';
 import InstantSearch from '../InstantSearch';
 import version from '../version';
+import { warning } from '../utils';
 
 jest.mock('algoliasearch-helper', () => {
   const module = require.requireActual('algoliasearch-helper');
@@ -217,6 +218,44 @@ describe('InstantSearch lifecycle', () => {
     expect(algoliaSearchHelper).not.toHaveBeenCalled();
   });
 
+  it('warns deprecated usage of `searchParameters`', () => {
+    warning.cache = {};
+
+    expect(() => {
+      // eslint-disable-next-line no-new
+      new InstantSearch({
+        indexName,
+        searchClient: algoliasearch(appId, apiKey),
+        searchParameters: {
+          disjunctiveFacets: ['brand'],
+          disjunctiveFacetsRefinements: {
+            brand: ['Samsung'],
+          },
+        },
+      });
+    })
+      .toWarnDev(`[InstantSearch.js]: The \`searchParameters\` option is deprecated and will not be supported in InstantSearch.js 4.x.
+
+You can replace it with the \`configure\` widget:
+
+\`\`\`
+search.addWidgets([
+  configure({
+  "disjunctiveFacets": [
+    "brand"
+  ],
+  "disjunctiveFacetsRefinements": {
+    "brand": [
+      "Samsung"
+    ]
+  }
+})
+]);
+\`\`\`
+
+See https://www.algolia.com/doc/api-reference/widgets/configure/js/`);
+  });
+
   it('does not fail when passing same references inside multiple searchParameters props', () => {
     const disjunctiveFacetsRefinements = { fruits: ['apple'] };
     const facetsRefinements = disjunctiveFacetsRefinements;