Skip to main content

​
Overview

Interface X is a Vue.js component library for building powerful commerce search and discovery experiences. This guide will walk you through installing and configuring Interface X in your project.

​
Requirements

Interface X requires Node.js 22+ and npm 10+ to run.
Before installing Interface X, ensure your development environment meets these requirements:
  • Node.js: Version 22 or higher
  • Package Manager: npm 10+, pnpm 9.15.9+, or yarn
  • Vue.js: Version 3.5.28 or compatible

​
Installation

Install the core X Components package using your preferred package manager: 
npm install @empathyco/x-components

​
Peer Dependencies

Interface X requires the following peer dependencies to be installed in your project:
package.json
{
  "dependencies": {
    "vue": "^3.5.28",
    "vuex": "4.0.2"
  }
}
Install them if you haven’t already: 
npm install vue@^3.5.28 [email protected]

​
Optional Packages

Depending on your search backend, you may need additional adapter packages:

​
Search API Adapters

For connecting to the Empathy Platform API:
npm install @empathyco/x-adapter-platform
This adapter is pre-configured to work with Empathy’s search endpoints and provides out-of-the-box integration.
For connecting to any other search API (Elasticsearch, Solr, etc.):
npm install @empathyco/x-adapter
The base adapter package allows you to create custom adapters for any search API. See the adapter documentation for implementation details.

​
Design System (Optional)

The Interface X Design System (XDS) is a Tailwind CSS plugin for styling your components.
npm install @empathyco/x-tailwindcss tailwindcss

​
Basic Setup

Once installed, initialize Interface X in your Vue.js application:
1

Import and configure XInstaller

Create a new file for your Interface X setup (e.g., src/x-setup.ts):
src/x-setup.ts
import { XInstaller } from '@empathyco/x-components';
import { platformAdapter } from '@empathyco/x-adapter-platform';
import { createStore } from 'vuex';
import { XPlugin } from '@empathyco/x-components';

// Create the installer with your configuration
const installer = new XInstaller({
  adapter: platformAdapter,
  store: createStore({}),
});

export default installer;
2

Initialize with snippet configuration

Initialize Interface X with your search configuration:
src/main.ts
import { createApp } from 'vue';
import App from './App.vue';
import installer from './x-setup';

// Initialize with your configuration
installer.init({
  instance: 'your-instance-name',
  lang: 'en',
  env: 'production',
  scope: 'your-scope',
});

const app = createApp(App);
app.mount('#app');
3

Alternative: Global initialization

You can also set up automatic initialization via a global initX function:
// Define configuration globally
window.initX = {
  instance: 'your-instance-name',
  lang: 'en',
  env: 'production',
  scope: 'your-scope',
  currency: 'USD',
  consent: true,
};
The installer will automatically use this configuration when it detects window.initX.

​
Configuration Options

The SnippetConfig object accepts the following parameters:
ParameterTypeRequiredDescription
instancestringYesYour search instance identifier
langstringYesLanguage code (e.g., ‘en’, ‘es’, ‘fr’)
envstringYesEnvironment (‘production’, ‘staging’, ‘development’)
scopestringYesSearch scope or catalog identifier
currencystringNoCurrency code (e.g., ‘USD’, ‘EUR’)
consentbooleanNoUser consent for tracking
uiLangstringNoUI language (if different from search language)
documentDirection'ltr' | 'rtl'NoDocument text direction

​
Verify Installation

To verify Interface X is properly installed and configured, check your browser console for the global Interface X API: 
console.log(window.InterfaceX);
You should see the Interface X API object with methods like init(), setSnippetConfig(), and event bus functionality.

​
Next Steps

Quickstart Guide

Build your first search interface in minutes

Component Reference

Explore all available X Components

API Adapters

Configure your search backend connection

Design System

Customize the look and feel with XDS

​
Troubleshooting

If you encounter module resolution errors:
  1. Ensure all peer dependencies are installed
  2. Clear your node_modules and lock file
  3. Reinstall dependencies: npm install (or pnpm install --frozen-lockfile)
  4. Check that your Node.js version is 22 or higher
Interface X requires Vue 3.5.28+. If you have an older version:
npm install vue@^3.5.28
Ensure no other packages in your project are depending on Vue 2.x.
If you’re using TypeScript, ensure your tsconfig.json includes:
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}
Need help? Check out the GitHub repository or the full documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us