{"id":13725153,"url":"https://github.com/typesense/gatsby-plugin-typesense","last_synced_at":"2025-09-25T11:43:13.547Z","repository":{"id":43098102,"uuid":"304501279","full_name":"typesense/gatsby-plugin-typesense","owner":"typesense","description":"A Gatsby plugin to automatically index content to Typesense post-build","archived":false,"fork":false,"pushed_at":"2022-08-04T00:46:00.000Z","size":847,"stargazers_count":34,"open_issues_count":6,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-17T03:44:00.152Z","etag":null,"topics":["gatsby","gatsby-plugin","gatsby-plugin-typesense","instantsearch-js","search-interface","typesense"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/typesense.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-16T02:42:44.000Z","updated_at":"2024-10-15T15:03:10.000Z","dependencies_parsed_at":"2022-08-29T08:50:30.001Z","dependency_job_id":null,"html_url":"https://github.com/typesense/gatsby-plugin-typesense","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typesense%2Fgatsby-plugin-typesense","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typesense%2Fgatsby-plugin-typesense/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typesense%2Fgatsby-plugin-typesense/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typesense%2Fgatsby-plugin-typesense/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/typesense","download_url":"https://codeload.github.com/typesense/gatsby-plugin-typesense/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250285650,"owners_count":21405296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gatsby","gatsby-plugin","gatsby-plugin-typesense","instantsearch-js","search-interface","typesense"],"created_at":"2024-08-03T01:02:14.434Z","updated_at":"2025-09-25T11:43:08.510Z","avatar_url":"https://github.com/typesense.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# gatsby-plugin-typesense [![NPM version][npm-image]][npm-url] [![CircleCI](https://circleci.com/gh/typesense/gatsby-plugin-typesense.svg?style=shield)](https://circleci.com/gh/typesense/gatsby-plugin-typesense)\n\nA Gatsby plugin to build typo-tolerant Instant Search experiences on [Gatsby](https://www.gatsbyjs.com/)-powered sites using [Typesense](http://typesense.org/). \n\nThis plugin runs post-build and indexes content from your site to Typesense. The search UI is then built with the [Typesense-InstantSearch.js](https://github.com/typesense/typesense-instantsearch-adapter) library.\n\nThis plugin works for both static and dynamic Gatsby sites. It does not depend on you using Markdown, Frontmatter, or any particular Gatsby plugin. It does not even depend on React. So you can use it with really any type of Gatsby site. \n\n#### What is Typesense? \n\nIf you're new to Typesense, it is an **open source** search engine that is simple to use, run and scale, with clean APIs and documentation. Think of it as an open source alternative to Algolia and an easier-to-use, batteries-included alternative to ElasticSearch. Get a quick overview from [this guide](https://typesense.org/guide/).\n\n## ✨ How it works\n\nOn post build, this plugin scans Gatsby's public directory looking for HTML files. Within each HTML file, it looks for HTML elements that have a data attribute called `data-typesense-field` and creates a Typesense `Document` with the value of that data attribute as the key, and the text content of that HTML element as the value. \n\nHere's an example: if you have the following HTML snippet in a file:\n\n```html\n\u003c!-- ./public/about/index.html --\u003e\n\n...\n\n\u003ch1 data-typesense-field=\"title\"\u003eAbout Us\u003c/h1\u003e\n\u003cp data-typesense-field=\"description\"\u003e\n  Hello, we are Stark Industries.\n\u003c/p\u003e\n\u003cdiv\u003e\n  \u003cspan data-typesense-field=\"tags\"\u003eabout\u003c/span\u003e\n  \u003cspan data-typesense-field=\"tags\"\u003emisc\u003c/span\u003e\n\u003c/div\u003e\n\n...\n\n```\n\nWhen you build your site, this plugin will index this page as the following structured document in Typesense:\n\n```json\n{\n  \"title\": \"About Us\",\n  \"description\": \"Hello, we are Stark Industries.\",\n  \"tags\": [\"about\", \"misc\"],\n  \"page_path\": \"/about/\",\n  \"page_priority_score\": 10\n}\n```\n\nYou'll then be able to query this collection of documents (pages) from Typesense, via your Search UI components from [Typesense-InstantSearch.js](https://github.com/typesense/typesense-instantsearch-adapter).\n\nYou can also add any arbitrary fields to the document, by adding the `data-typesense-field` data attribute to any HTML element.\n\n## ⌨️ How to install\n\n```bash\nnpm install gatsby-plugin-typesense\n```\n\nAlso install peer dependencies:\n\n```bash\nnpm install @babel/runtime\n```\n\n## 🛠️ How to use\n\n### 1️⃣ Start a Typesense server\n\nThe simplest way to run a Typesense server is using Docker:\n\n```\nmkdir /tmp/typesense-server-data\ndocker run -i -p 8108:8108 -v/tmp/typesense-server-data/:/data typesense/typesense:0.22.0.rcu7 --data-dir /data --api-key=xyz --listen-port 8108 --enable-cors\n```\n\nYou can also download native binaries [here](https://typesense.org/downloads/).\n\nIf you'd prefer a hosted version of Typesense, you can also spin up a cluster on [Typesense Cloud](https://cloud.typesense.org/). \n\n### 2️⃣ Configure the plugin\n\n```javascript\n// gatsby-config.js\n\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-typesense`,\n      options: {\n        rootDir: `${__dirname}/public`, // Required\n        collectionSchema: { // Required\n          name: \"pages_v1\",\n          fields: [\n            {\n              name: \"title\",\n              type: \"string\",\n            },\n            {\n              name: \"description\",\n              type: \"string\",\n            },\n            {\n              name: \"tags\",\n              type: \"string[]\",\n              optional: true,\n              facet: true,\n            },\n            {\n              name: \"page_path\", // Required\n              type: \"string\",\n            },\n            {\n              name: \"page_priority_score\", // Required\n              type: \"int32\",\n            },\n          ],\n          default_sorting_field: \"page_priority_score\", // Required\n        },\n        server: { // Required\n          apiKey: \"xyz\",\n          nodes: [\n            {\n              host: \"localhost\",\n              port: \"8108\",\n              protocol: \"http\",\n            },\n          ],\n        },\n      },\n    },\n  ],\n}\n```\n\n#### Here's what the options mean:\n\n##### `rootDir`\n\nThe directory that the plugin will scan for HTML files to index. \n\nThis is the directory where Gatsby usually places your build files when you run `gatsby build`. This is almost always `./public` relative to your repo root, unless you've changed it.\n\nNote: This parameter was renamed from `publicDir` to `rootDir` recently. \n\n##### `collectionSchema`\n\nThe schema that will be used to create the collection in Typesense. \n\nA quick recap of Typesense terminology, if you haven't already read [the guide](https://typesense.org/guide/): A `Collection` contains many `Documents`. You create a `Collection` with a specific schema and then all `Documents` that are added to that `Collection` will be validated against that schema. You issue search queries against a `Collection` of `Documents`.\n\nWhile the schema in the example above is a great starting point, you can choose to customize the schema to your needs. For eg: when you need to index more structured data from your pages like price, category, tags, etc you can add these as fields to the schema and add the corresponding `data-typesense-field` to your markup. You'll find the list of data types supported [here](https://typesense.org/docs/0.16.0/api/#create-collection).\n\n⚠️ This plugin expects these two fields to be present in the schema:\n\n- `page_path` - this is automatically set by the plugin based on the directory structure of `rootDir`\n- `page_priority_score` - this is set to `10` by default for all pages, but you can override this value for any page like this: `\u003cdiv data-typesense-field=\"page_priority_score\" style=\"display: none;\"\u003e5\u003c/div\u003e`\n\n##### `server`\nConfiguration details of your Typesense Cluster. \n\nThis config object is passed straight to the [typesense-js](https://github.com/typesense/typesense-js) client. So any option you'd use to configure the JS client can be used here.\n\n#### Adding more than one collection\n\nTo add more than one collection to Typesense (for example, if you have two search UIs, one for blog posts and another for authors... or if you have multilingual site and wish to separate the contents so that searching in one language would return only results from that collection), simply call `gatsby-plugin-typesense` multiple times:\n\n```jsx\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-typesense`,\n      options: {\n        rootDir: `${__dirname}/public/posts`,\n        collectionSchema: {\n          name: \"posts\",\n          ...\n        },\n        server: { ... },\n      },\n    },\n    {\n      resolve: `gatsby-plugin-typesense`,\n      options: {\n        rootDir: `${__dirname}/public/authors`,\n        collectionSchema: {\n          name: \"authors\",\n          ...\n        },\n        server: { ... },\n      },\n    },\n    ...\n  ]\n  ...\n}\n```\n\nBe sure to specify which collection you're querying from your search UI.\n\n#### Adding exclude directories\n\nSometimes you migth want to exclude some directories\n  (for example, if you're creating a bilingual website and want to create two collections,\n  one for each language, so that a search from English part would only return\n  results from the English collection.)\nIn this case, you can specify a regular expression of what directories should be excluded:\n\n```jsx\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-typesense`,\n      options: {\n        rootDir: `${__dirname}/public`,\n        exclude: /^\\/ko/, // exclude sub-directories that begins with /ko\n        ...\n      },\n    },\n    ...\n  ]\n  ...\n}\n```\n\n### 3️⃣ Markup your content\n\nAdd a data attribute in this format to any HTML elements that contain the data you want to be indexed for that page:\n\n```html\n\u003c... data-typesense-field=\"field_name_defined_in_schema\"\u003eContent to be indexed\u003c/...\u003e\n```\n\nWhen the plugin runs, it looks for this data attribute and will add a field with the following format to the document:\n\n```\n{\n  ...,\n  \"field_name_defined_in_schema\": \"Content to be indexed\",\n  ...,\n}\n```\n\nIf you have an array data type defined in the schema (useful when you need to index multiple sections on the same page to the same field), you can add the same `data-typesense-field=\"X\"` attribute to multiple elements. \n\nFor example: let's say you have a `string[]` field called `array_field_defined_in_schema` in your schema.\n\nIf you have the following in your markup:\n\n```html\n\u003cp data-typesense-field=\"array_field_defined_in_schema\"\u003ePara 1\u003c/p\u003e\n\u003cp data-typesense-field=\"array_field_defined_in_schema\"\u003ePara 2\u003c/p\u003e\n```\n\nWhen the plugin runs, it looks for this data attribute and will add a field with the following format to the document:\n\n```\n{\n  ...,\n  \"array_field_defined_in_schema\": [\"Para 1\", \"Para 2\"],\n  ...,\n}\n```\n\n### 4️⃣ Build your site\n\nThis plugin runs automatically post-build. So you want to run:\n\n```bash\ngatsby build\n```\n\nThis will index your content to your Typesense search cluster.\n\n## 🔍 How to build a Search UI\n\nThe good folks over at Algolia have built and open-sourced [Instantsearch.js](https://github.com/algolia/instantsearch.js) which is a powerful collection of out-of-the-box UI components that you can use to compose interactive search experiences quickly.\n\nTypesense has an integration with InstantSearch.js (and its [React cousin](https://github.com/algolia/react-instantsearch)), that lets you use a Typesense cluster with InstantSearch.js. \n\nInstall InstantSearch and the Typesense Adapter in your Gatsby project:\n\n```bash\nnpm install typesense-instantsearch-adapter react-instantsearch-dom @babel/runtime\n```\n\nHere's a quick minimal example of a search interface:\n\n```jsx\nimport { InstantSearch, SearchBox, Hits, Stats } from \"react-instantsearch-dom\"\nimport TypesenseInstantSearchAdapter from \"typesense-instantsearch-adapter\"\n\nconst typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({\n  server: {\n    apiKey: \"xyz\", // Be sure to use the search-only-api-key\n    nodes: [\n      {\n        host: \"localhost\",\n        port: \"8108\",\n        protocol: \"http\",\n      },\n    ],\n  },\n  // The following parameters are directly passed to Typesense's search API endpoint.\n  //  So you can pass any parameters supported by the search endpoint below.\n  //  queryBy is required.\n  additionalSearchParameters: {\n    queryBy: \"title,description,tags\",\n  },\n})\nconst searchClient = typesenseInstantsearchAdapter.searchClient\n\nexport default function SearchInterface() {\n  const Hit = ({ hit }) =\u003e (\n    \u003cp\u003e\n      {hit.title} - {hit.description}\n    \u003c/p\u003e\n  )\n\n  return (\n      \u003cInstantSearch searchClient={searchClient} indexName=\"pages_v1\"\u003e\n        \u003cSearchBox /\u003e\n        \u003cStats /\u003e\n        \u003cHits hitComponent={Hit} /\u003e\n      \u003c/InstantSearch\u003e\n  )\n}\n```\n\nInstantSearch.js supports a variety of additional [search widgets](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/react/). Read more about how to use them in their documentation [here](https://www.algolia.com/doc/guides/building-search-ui/getting-started/react/).\n\nRead more on how to use the Typesense adapter [here](https://github.com/typesense/typesense-instantsearch-adapter#quick-start).\n\n## 🏗️ Local Development Workflow\n\nThis section **only** applies if you're developing the plugin itself. \n\n```bash\n\n# Start a local typesense server (uses Docker)\nnpm run typesenseServer\n\n# Build the gatsby project under ./test/support/testground, which will also trigger this plugin\nnpm run testground:build\n\n```\n\n### Running tests\n\n```bash\nnpm test\n```\n\n### Releasing a new version\n\nTo release a new version, we use the np package:\n\n```bash\nnpm install --global np\nnp \n\n# Follow instructions that np shows you\n```\n\n## 🤗 How to contribute\n\nIf you find any issues, have questions or have a feature suggestion please open an issue on Github: http://github.com/typesense/gatsby-plugin-typesense/issues\n\n---\n\u0026copy; 2016-2020 Typesense Inc.\n\n[npm-image]: https://badge.fury.io/js/gatsby-plugin-typesense.svg\n[npm-url]: https://npmjs.org/package/gatsby-plugin-typesense\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypesense%2Fgatsby-plugin-typesense","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypesense%2Fgatsby-plugin-typesense","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypesense%2Fgatsby-plugin-typesense/lists"}