Skip to main content
You can automate the generation of InstantSearch apps using a JSON configuration file.

​
Using a Config File

Create a configuration file and pass it with the --config flag: 
npx create-instantsearch-app my-app --config config.json

​
Configuration Format

Create a JSON file with your app configuration:
config.json
{
  "name": "my-app",
  "template": "InstantSearch.js",
  "libraryVersion": "4.0.0",
  "appId": "MY_APP_ID",
  "apiKey": "MY_SEARCH_API_KEY",
  "indexName": "products",
  "searchPlaceholder": "Search for products",
  "attributesToDisplay": ["name", "description", "price"],
  "imageAttribute": "image_url",
  "attributesForFaceting": ["brand", "category", "color"],
  "enableInsights": true
}

​
Configuration Options

​
Required Options

​
name
string
required
The name of your applicationExample: "my-search-app"
​
template
string
required
The InstantSearch template to useOptions: "InstantSearch.js", "React InstantSearch", "Vue InstantSearch", etc.See Templates for full list

​
Library Configuration

​
libraryVersion
string
Specific version of the InstantSearch libraryExample: "4.0.0"If omitted, you’ll be prompted to select a version

​
Algolia Connection

​
appId
string
Your Algolia application IDDefault: "latency" (demo app)
​
apiKey
string
Your Algolia search API key (public, search-only)Default: "6be0576ff61c053d5f9a3225e2a90f76" (demo key)
Never use your Admin API key in client-side code
​
indexName
string
The name of your Algolia indexDefault: "instant_search"

​
Search UI Configuration

​
searchPlaceholder
string
Placeholder text for the search boxDefault: "Search"
​
attributesToDisplay
string[]
Array of attribute names to show in search resultsExample: ["name", "description", "price"]
​
imageAttribute
string
Attribute name containing image URLs for result thumbnailsExample: "image_url"
​
attributesForFaceting
string[]
Array of attributes to use as filtersExample: ["brand", "category", "color"]Use "ais.dynamicWidgets" to enable dynamic widgets (auto-generated filters)

​
Advanced Options

​
enableInsights
boolean
Enable Algolia Insights for event trackingDefault: falseRequires InstantSearch.js >= 4.55, React InstantSearch >= 7.0, or Vue InstantSearch >= 4.9.0
​
searchInputType
string
Type of search input to useOptions: "autocomplete" or "searchbox"Only available for InstantSearch.js >= 4.52
​
querySuggestionsIndexName
string
Index name for Query Suggestions (required when using autocomplete)Example: "products_query_suggestions"
​
autocompleteLibraryVersion
string
Version of Autocomplete.js to use (when searchInputType is “autocomplete”)Example: "1.11.0"

​
Configuration Examples

​
React App with Insights

{
  "name": "ecommerce-search",
  "template": "React InstantSearch",
  "libraryVersion": "7.0.0",
  "appId": "YOUR_APP_ID",
  "apiKey": "YOUR_SEARCH_KEY",
  "indexName": "products",
  "attributesToDisplay": ["name", "brand", "price"],
  "imageAttribute": "image",
  "attributesForFaceting": ["brand", "category", "rating"],
  "enableInsights": true
}

​
Vue App with Dynamic Widgets

{
  "name": "product-finder",
  "template": "Vue InstantSearch",
  "libraryVersion": "4.5.0",
  "appId": "YOUR_APP_ID",
  "apiKey": "YOUR_SEARCH_KEY",
  "indexName": "inventory",
  "attributesToDisplay": ["title", "description"],
  "attributesForFaceting": ["ais.dynamicWidgets"],
  "enableInsights": true
}

​
InstantSearch.js with Autocomplete

{
  "name": "search-demo",
  "template": "InstantSearch.js",
  "libraryVersion": "4.60.0",
  "appId": "latency",
  "apiKey": "6be0576ff61c053d5f9a3225e2a90f76",
  "indexName": "instant_search",
  "searchInputType": "autocomplete",
  "querySuggestionsIndexName": "instant_search_demo_query_suggestions",
  "autocompleteLibraryVersion": "1.11.0",
  "attributesToDisplay": ["name", "description"],
  "imageAttribute": "image",
  "attributesForFaceting": ["brand", "type"]
}

​
Widget Development

{
  "name": "my-custom-widget",
  "template": "InstantSearch.js widget",
  "organization": "my-company",
  "description": "A custom InstantSearch widget for advanced filtering"
}

​
Programmatic API

You can also use create-instantsearch-app programmatically: 
const createInstantSearchApp = require('create-instantsearch-app');

const app = createInstantSearchApp('~/projects/my-app', {
  template: 'InstantSearch.js',
  libraryVersion: '4.0.0',
  appId: 'latency',
  apiKey: '6be0576ff61c053d5f9a3225e2a90f76',
  indexName: 'instant_search',
  attributesToDisplay: ['name', 'description'],
  imageAttribute: 'image',
  attributesForFaceting: ['brand', 'category'],
  enableInsights: true,
});

app.create().then(() => console.log('App generated!'));

​
Best Practices

Use version control

Store configuration files in your repository to ensure consistent app generation across teams

Separate configs for environments

Create different config files for development, staging, and production
npx create-instantsearch-app dev-app --config config.dev.json
npx create-instantsearch-app prod-app --config config.prod.json

Start with demo credentials

Use Algolia’s demo app (latency) to test templates before connecting your own index

Use semantic versioning

Pin library versions in config files to ensure reproducible builds

​
Troubleshooting

Ensure the path to your config file is correct. Use absolute paths or paths relative to your current directory.
npx create-instantsearch-app my-app --config ./configs/config.json
Validate your JSON using a linter or online validator. Common issues:
  • Trailing commas
  • Missing quotes around strings
  • Invalid escape characters
Check the supported version range for your chosen template in the Templates documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us