https://github.com/huextrat/expo-core-spotlight

Expo module implementing iOS Core Spotlight
https://github.com/huextrat/expo-core-spotlight

expo ios react-native spotlight spotlight-search

Last synced: 9 months ago
JSON representation

Expo module implementing iOS Core Spotlight

Host: GitHub
URL: https://github.com/huextrat/expo-core-spotlight
Owner: huextrat
Created: 2025-09-22T11:47:31.000Z (10 months ago)
Default Branch: main
Last Pushed: 2025-09-30T09:35:32.000Z (9 months ago)
Last Synced: 2025-09-30T11:35:31.304Z (9 months ago)
Topics: expo, ios, react-native, spotlight, spotlight-search
Language: TypeScript
Homepage: https://www.npmjs.com/package/expo-core-spotlight
Size: 428 KB
Stars: 2
Watchers: 0
Forks: 0
Open Issues: 3
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md

Awesome Lists containing this project

README

# 🔍 Expo Core Spotlight

**Make your app content discoverable through iOS Spotlight search**

*An Expo module that provides access to iOS Core Spotlight functionality, allowing you to add, update, and remove items from the iOS Spotlight search index. When users tap on search results, your app will be opened with the corresponding deeplink.*

---

## ✨ Features

- Add / Update / Remove items to iOS Spotlight search
- Rich metadata support (title, description, keywords, URLs, dates, location, etc.)
- Automatic deeplink handling when users tap search results

---

## 🚀 Quick Start

### Installation

```bash
# Using npm
npm install expo-core-spotlight

# Using yarn
yarn add expo-core-spotlight

# Using pnpm
pnpm add expo-core-spotlight

# Using Expo CLI
npx expo install expo-core-spotlight
```

## ⚙️ Configuration

### 1. Add the Plugin to Your App Config

Add the plugin to your `app.config.js` or `app.config.ts`:

📄 app.config.js

```javascript
export default {
// ... your existing config
plugins: [
// ... your existing plugins
'expo-core-spotlight',
],
};
```

📄 app.config.ts

```typescript
import { ConfigContext } from 'expo/config';

export default ({ config }: ConfigContext) => ({
...config,
plugins: [
...(config.plugins || []),
'expo-core-spotlight',
],
});
```

### 2. 🔗 Deeplink Configuration

> **⚠️ Important:** The library uses the `uniqueIdentifier` as the deeplink URL.

You must include your app's URL scheme as a prefix in the `uniqueIdentifier` when creating Spotlight items.

| ✅ **Correct** | ❌ **Incorrect** |
|---|---|
| `uniqueIdentifier: 'myapp://document/1'` | `uniqueIdentifier: 'document-1'` |
| `uniqueIdentifier: 'myapp://user/123'` | `uniqueIdentifier: 'user-123'` |

> **ℹ️ Note:**
> Currently, the library uses the `uniqueIdentifier` property as the deeplink URL for Spotlight items.
> **In the future, this should be changed so that the `url` property is used as the deeplink instead of `uniqueIdentifier`.**
> This will better align with iOS Core Spotlight best practices and make the API more intuitive.
> For now, always include your app's URL scheme as a prefix in the `uniqueIdentifier`.

## 📖 Usage

### 🎯 Basic Example

```typescript
import ExpoCoreSpotlight, { CoreSpotlightItem } from 'expo-core-spotlight';

// Check if Core Spotlight is available
const isAvailable = await ExpoCoreSpotlight.isAvailable();
console.log('Core Spotlight available:', isAvailable); // true on iOS, false on Android

// Create a Spotlight item with deeplink in uniqueIdentifier
const item: CoreSpotlightItem = {
uniqueIdentifier: 'myapp://document/1', // Include your app scheme as prefix
title: 'My Important Document',
contentDescription: 'This is a sample document from my app',
keywords: ['document', 'important', 'my-app'],
url: 'myapp://document/1', // Optional: can be the same as uniqueIdentifier
domainIdentifier: 'com.myapp.documents',
};

// Add the item to Spotlight
await ExpoCoreSpotlight.indexItem(item);
```

### 🚀 Advanced Example

```typescript
import ExpoCoreSpotlight, { CoreSpotlightItem } from 'expo-core-spotlight';

// Add multiple items at once
const items: CoreSpotlightItem[] = [
{
uniqueIdentifier: 'myapp://document/1', // Deeplink as uniqueIdentifier
title: 'Document 1',
contentDescription: 'First document',
keywords: ['document', 'first'],
url: 'myapp://document/1',
domainIdentifier: 'com.myapp.documents',
rating: 4.5
},
{
uniqueIdentifier: 'myapp://document/2', // Deeplink as uniqueIdentifier
title: 'Document 2',
contentDescription: 'Second document',
keywords: ['document', 'second'],
url: 'myapp://document/2',
domainIdentifier: 'com.myapp.documents',
rating: 3.8
}
];

await ExpoCoreSpotlight.indexItems(items);

// Remove a specific item
await ExpoCoreSpotlight.removeItem('myapp://document/1');

// Remove multiple items
await ExpoCoreSpotlight.removeItems(['myapp://document/2']);

// Remove all items from a domain
await ExpoCoreSpotlight.removeAllItemsFromDomain('com.myapp.documents');

// Remove all items
await ExpoCoreSpotlight.removeAllItems();
```

## 📚 API Reference

### 🔧 Methods

#### `isAvailable(): Promise`
Check if Core Spotlight is available on the device.
- **Returns**: `true` on iOS, `false` on Android

#### `indexItem(item: CoreSpotlightItem): Promise`
Add or update a single item in the Spotlight index.

#### `indexItems(items: CoreSpotlightItem[]): Promise`
Add or update multiple items in the Spotlight index.

#### `removeItem(uniqueIdentifier: string): Promise`
Remove a single item from the Spotlight index by its unique identifier.

#### `removeItems(uniqueIdentifiers: string[]): Promise`
Remove multiple items from the Spotlight index by their unique identifiers.

#### `removeAllItems(): Promise`
Remove all items from the Spotlight index.

#### `removeAllItemsFromDomain(domainIdentifier: string): Promise`
Remove all items from a specific domain from the Spotlight index.

---

## 📱 Platform Support

**🍎 iOS**
- Full Core Spotlight functionality
- Automatic deeplink handling
- Rich metadata support

**🤖 Android**
- Empty implementations
- Returns successfully but does nothing
- No-op for compatibility

**🌐 Web**
- Not supported
- Will throw errors if used

---

## 🛠️ Troubleshooting

### 🚨 Common Issues

🔗 Deeplinks not working

**Problem**: Tapping search results doesn't open your app.

**Solution**: Make sure your `uniqueIdentifier` includes your app's URL scheme:
```typescript
// ✅ Correct
uniqueIdentifier: 'myapp://document/1'

// ❌ Incorrect
uniqueIdentifier: 'document-1'
```

⚙️ Plugin not working

**Problem**: Plugin changes aren't applied.

**Solution**:
1. Ensure you've added the plugin to your `app.config.js/ts`
2. Run `npx expo prebuild` to regenerate native code
3. Clean and rebuild your project

🔍 Items not appearing in Spotlight

**Problem**: Items don't show up in search results.

**Solutions**:
- ⏰ Wait a few minutes for iOS to index the items
- 🔐 Check that your app has the necessary permissions
- ✅ Verify that items have valid `title` and `uniqueIdentifier` properties
- 🔄 Try removing and re-adding items

---

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

---

## 🤝 Contributing

We welcome contributions! Here's how you can help:

1. 🍴 **Fork** the repository
2. 🌿 **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. 💾 **Commit** your changes (`git commit -m 'Add some amazing feature'`)
4. 📤 **Push** to the branch (`git push origin feature/amazing-feature`)
5. 🔄 **Open** a Pull Request

### 🐛 Found a Bug?

Please open an issue with:
- 📱 Device information
- 📋 Steps to reproduce
- 📸 Screenshots (if applicable)
- 📝 Expected vs actual behavior

### 💡 Have an Idea?

We'd love to hear your suggestions! Open an issue with the `enhancement` label.

---

**⭐ Star this repo if you found it helpful!**

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/huextrat/expo-core-spotlight

Awesome Lists containing this project

README