Connect to Strapi

We provide a plugin for Strapi that allows you to connect your Strapi application to Orama Cloud and index your content in a few simple steps.

Install plugin

To get started, you need to install the Orama Cloud plugin in your Strapi application.

Using the marketplace

Coming soon.

Using a package manager

You can install the plugin using any major Node.js package manager.

npm

npm install @oramacloud/plugin-strapi

Yarn

yarn add @oramacloud/plugin-strapi

pnpm

pnpm install @oramacloud/plugin-strapi

Configuration

To use the plugin, you need to add the following configuration to your config/plugins.js file.

config/plugins.js

module.exports = ({ env }) => ({
"orama-cloud": {
  config: {
    privateApiKey: env('ORAMACLOUD_PRIVATE_API_KEY'),
  },
},
});

You can get the privateApiKey from your Orama Cloud dashboard. It is required to authenticate your Strapi application with Orama Cloud.

Caution

Keep your private API key in a secure place. Do not share it with anyone and do not expose it in your client-side code or public repository.

Creating an index

1. Go to your dashboard and click on “Native Integrations”.

   Then, click on the Strapi logo to create a new index.

2. Add a name to your index. It can be anything.

   Click Create index to continue.

3. In the following screen, you will be presented with the variables you need to set up the plugin.

   Follow the instructions on the dashboard to get your PRIVATE_API_KEY.

Managing your indexes

The Orama Cloud plugin for Strapi allows you to manage one or more indexes directly from your Strapi admin panel.

Directly from the Strapi plugin’s admin panel, you can:

• Add a collection to map your Strapi Content Type to an Orama Cloud index.
• Define the schema of your index.
• Define the update strategy for your index.

Add a collection

Option	Description
Index ID	(required) The index ID you want to connect to. You can find the Index ID in the dashboard.
Content Type	(required) The Strapi Content Type you want to map to your Orama Index.
Include relations	Include Content Type relations as nested objects in your index documents.
Attributes mapping	(required) Define the attributes to be included in your index documents.
Searchable properties	In the attributes mapping section, you can toggle the attributes that should be used in search queries.

Defining the schema

In the collection configuration modal, under the Attributes mapping section, you can select the attributes of your Strapi Content Type that you want to include in your search documents (the records that will be indexed in Orama Cloud).

This is where you also define the Searchable properties of your index. These are the attributes that will be searchable in your index. The searchable properties are also used in the automatic embeddings generation to perform vector and hybrid searches.

Update settings

To define how your index should be updated, you can either enable Live updates or Scheduled updates. Depending on your use case, you can choose to update your index in real-time or at specific intervals.

Live updates

Live updates will automatically update your index whenever a new record is created, updated, or deleted in your Strapi application. This will automatically trigger a reindexing process and a new deployment in Orama Cloud.

This option is useful when you want to keep your index up-to-date with your Strapi application in real-time. However, it may increase the number of deployments in Orama Cloud.

To keep the number of deployments low, you can use the Scheduled updates option.

Scheduled updates

Scheduled updates allow you to define a specific interval for updating your index. You can choose to update your index every 30 minutes, every hour, daily, weekly or monthly.

This option is useful when you want to keep your index up-to-date with your Strapi application but don’t need real-time updates. Scheduled updates can help you reduce the number of deployments in Orama Cloud.

Integrating into your app

Now that you have your index deployed, you can start using it in your application's frontend.

You can install a ready-to-use Web Component to your site, like the Search Box, which is framework agnostic and can be used in any JavaScript environment.

You can also install the JavaScript SDK to build your own searching experience.

UI Components Add a fully featured and highly customizable Search Box component in your application.

JavaScript SDK Learn how to use your Orama Cloud index in a JavaScript application.

React Example Learn how to use your Orama Cloud index in a React application.

Vue Example Learn how to use your Orama Cloud index in a Vue application.

---

Advanced usage

Documents transformation

The scope of the transformation is to modify the document before it is sent to the Orama Cloud API. This can be useful to add, remove or modify fields in the document. A common use case is to refactor a collection (not supported yet by Orama Cloud) into a flat structure.
Here is an example of how to transform a collection of objects to a flat structure:

Note

This will override any setting you have in the Strapi plugin admin panel.
You’ll be warned on the admin panel if you have a transformer function set.

Pre-requisites

• An Orama Cloud index.
• A Strapi collection already created, with relations.

Example document:

{
  "id": 1,
  "owner": "John",
  "cars": [
    {
      "brand": "Toyota",
      "model": "Corolla"
    },
    {
      "brand": "Ford",
      "model": "Focus"
    }
  ]
}

You can insert your transformer function directly inside the plugin configuration under config/plugins.js file:

Caution

Remember that both schema and transformer are mandatory for a correct configuration. If you miss one of them, the plugin will not work as expected.
Also remember that the transformer function must return a transformed document that follows the schema you defined.
All non-matching fields will included in the documents, but ignored as search field.

module.exports = ({ env }) => ({
  "orama-cloud": {
    config: {
      privateApiKey: env("ORAMA_PRIVATE_API_KEY"),
      collectionSettings: {
        "<your_collection_index_id>": {
          /* Mandatory */
          /* Define the schema of your document */
          schema: {
            id: { type: "integer" },
            owner: { type: "string" },
            cars: {
              brands: { type: "string" },
              models: { type: "string" },
            }
          },
          /* Mandatory */
          /* Define the transformer function */
          transformer: entry => {
            return {
              ...entry,
              owner: "Overriding owner",
              cars: {
                source: entry.cars,
                ...entry.cars.reduce((acc, curr) => {
                  acc.brands.push(curr.brand);
                  acc.models.push(curr.model);
                  return acc;
                }, {
                  brands: [],
                  models: []
                })
              }
            }
          }
        }
      }
    }
  }
})

In this way your cars will be transformed to:

{
  "id": 1,
  "owner": "Overriding owner",
  "cars": {
    "brands": ["Toyota", "Ford"],
    "models": ["Corolla", "Focus"]
  }
}

And this will make you car brands and models searchable.