n8n-nodes-algolia

An n8n community node to interact with Algolia's Search API directly from your n8n workflows.

Table of Contents

• Installation
• Credentials
• Operations
• Development
• Limitations
• Resources
• Contributing

Installation

Prerequisites

• Node.js v22 or higher
• npm
• n8n installed globally (npm install n8n -g)

Development Installation

1. Clone the repository:

git clone https://github.com/emirbelkahia/n8n-nodes-algolia.git
cd n8n-nodes-algolia

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Launch in development mode:

npm run dev

This starts n8n on http://localhost:5678 with the Algolia node loaded and hot-reload enabled.

Production Installation

Once published to npm, users can install this node in three ways:

Option 1: GUI Installation (Recommended)

1. In n8n, go to Settings → Community Nodes
2. Click Install a Community Node
3. Enter n8n-nodes-algolia
4. Click Install
5. Restart n8n

Option 2: Command Line (Global)

npm install -g n8n-nodes-algolia
n8n start

Option 3: Manual Installation

cd ~/.n8n/custom
npm install n8n-nodes-algolia
# Restart n8n

Credentials

Setting up Algolia Credentials

The node requires the following credentials:

1. Application ID: Your Algolia Application ID
2. API Key: Your Algolia API Key

Security Best Practice

Always use an API key with ACLs (Access Control Lists) strictly aligned with your project's needs.

For this node (Search operation only):

• ✅ Recommended: Use a Search-only API Key or create a custom API key with only search permission
• ❌ Not recommended: Avoid using the Admin API Key in production workflows

How to get your credentials:

1. Log in to your Algolia Dashboard
2. Go to Settings → API Keys
3. Copy your Application ID
4. Use the Search-only API Key or create a custom key with minimal required permissions

Configure credentials in n8n:

1. In n8n, go to Credentials → New
2. Search for Algolia API
3. Enter your Application ID and API Key
4. Click Create

Operations

Search

Perform a search query on an Algolia index.

Required Parameters:

• Index Name: The name of the index to search

Optional Parameters:

• Query: The search query text (can be empty to retrieve all results)
• Hits Per Page: Number of results per page (default: 20)
• Page: Page number (starts at 0)
• Attributes to Retrieve: Comma-separated list of attributes to retrieve
• Filters: Algolia filter expression

Usage Examples:

// Simple search
Index Name: "products"
Query: "laptop"

// Search with filters
Index Name: "products"
Query: "laptop"
Filters: "price < 1000 AND brand:Apple"
Hits Per Page: 10

// Retrieve all products from a category
Index Name: "products"
Query: ""
Filters: "category:electronics"
Attributes to Retrieve: "name,price,image"

Response Format:

The node returns each result (hit) as a separate item in the n8n workflow. Each item contains all attributes of the Algolia object.

Development

Project Structure

n8n-nodes-algolia/
├── credentials/
│   └── AlgoliaApi.credentials.ts    # Credentials definition
├── nodes/
│   └── Algolia/
│       ├── Algolia.node.ts          # Node logic
│       └── Algolia.node.json        # Node metadata
├── icons/
│   └── algolia.svg                  # Node icon
├── dist/                            # Compiled files (generated)
├── package.json                     # npm configuration
└── tsconfig.json                    # TypeScript configuration

Available Scripts

Script	Description
npm run dev	Launch n8n in development mode with hot-reload
npm run build	Compile TypeScript to JavaScript
npm run build:watch	Compile in watch mode
npm run lint	Check code with n8n linter
npm run lint:fix	Automatically fix linting issues

Development Workflow

1. Modify the code in nodes/Algolia/Algolia.node.ts or credentials/AlgoliaApi.credentials.ts
2. Code is automatically recompiled (if npm run dev is running)
3. Refresh the browser (F5) to see changes in n8n
4. Test the node in a workflow

Technical Architecture

Implementation Approach

This node uses n8n's programmatic approach rather than the declarative approach for more control over execution logic.

Why No External Dependencies?

The node does not use the Algolia SDK (algoliasearch) but makes direct HTTP calls via this.helpers.httpRequest for the following reasons:

1. n8n Cloud Compatibility: n8n Cloud doesn't allow community nodes with external npm dependencies for security reasons
2. Package Size: Reduces final package size
3. Simplicity: Algolia's REST API is straightforward and well-documented

Communication with Algolia API

All requests use:

• URL: https://{appId}-dsn.algolia.net/1/...
• Headers:
  • X-Algolia-Application-Id: Application ID
  • X-Algolia-API-Key: API Key
  • Content-Type: application/json

Limitations

Current Limitations

1. Single Operation: Currently only the Search operation is implemented
2. No Advanced Management:
   • No Rules management
   • No Synonyms management
   • No Replicas management
3. No Batch Operations: Batch operations are not yet supported

n8n Cloud Compatibility

If you wish to publish this node on n8n Cloud:

• ✅ Compatible: No external npm dependencies
• ✅ Compatible: Uses only this.helpers.httpRequest
• ⚠️ To verify: Icon must be in the correct format
• ⚠️ To verify: Linter must pass without errors

Roadmap

Operations planned for future versions:

• Object Operations: Add, Update, Partial Update, Delete, Get, Batch
• Index Operations: List, Create, Delete, Clear, Copy, Move
• Settings Operations: Get Settings, Set Settings
• Synonyms: Manage synonyms
• Rules: Manage rules
• API Keys: List, Create, Update, Delete API keys

Troubleshooting

Node doesn't appear in n8n

1. Check that npm run dev is running
2. Verify the build succeeded (npm run build)
3. Refresh the browser page (F5)
4. Check the console for errors

Credentials error

1. Verify you created the Algolia credentials in n8n
2. Check that Application ID and API Key are correct
3. Verify the API Key has necessary permissions

Search error

1. Check that the index exists in Algolia
2. Verify the index name (case-sensitive)
3. Check filters (Algolia syntax)
4. Consult n8n logs for more details

Resources

Algolia Documentation

• Algolia REST API
• Search API Parameters
• Filtering
• API Keys

n8n Documentation

• Creating Nodes
• Node Development Environment
• Testing Nodes
• Publishing Community Nodes

Tools

• @n8n/node-cli - CLI for developing n8n nodes
• n8n Creator Portal - Submit your node for review

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a branch for your feature (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT

Author

Emir Belkahia Customer Success Manager @ Algolia

• Website: emirbelkahia.com
• LinkedIn: linkedin.com/in/emirbelkahia
• GitHub: @emirbelkahia

Support

For questions or issues:

• Open an issue
• Consult the n8n documentation
• Join the n8n community