Installation Guide

Complete installation instructions for Reef Search across different environments, frameworks, and deployment scenarios.

Prerequisites

Before installing Reef Search, ensure your site meets these requirements:

RequirementDetails
HTTPS Recommended Required for most CDNs and for sitemap fetch to work on many static hosts
Sitemap Recommended but not required: sitemap.xml at your site root for full indexing
Modern Browser ES6+ support required (Chrome 60+, Firefox 55+, Safari 12+, Edge 79+)

Quick Installation

The fastest way to add Reef Search to any static site:

<script src="https://unpkg.com/reef-search/dist/reef.min.js"></script>

This single script tag is all that's required. Reef Search will automatically:

✓ Minimal Setup

This method works for pure HTML sites, documentation, blogs, and marketing sites. No build step or configuration needed.

Installation Methods

1. CDN (Recommended for most users)

Load directly from a CDN without hosting the file yourself:

<!-- jsDelivr (automatic latest version) -->
<script src="https://cdn.jsdelivr.net/npm/reef-search/dist/reef.min.js"></script>

<!-- unpkg (explicit version recommended) -->
<script src="https://unpkg.com/reef-search@latest/dist/reef.min.js"></script>

2. Self-hosted (Download the bundle)

For complete control over the script location:

# Download the latest release
curl -L https://github.com/reef-search/reef-search/releases/latest/download/reef.min.js -o dist/reef.min.js

# Or build from source
npm install
npm run build

Then include in your HTML:

<script src="/dist/reef.min.js"></script>

3. NPM Package (For bundlers)

Install as a dependency in your project:

npm install reef-search

Then in your JavaScript entry point:

// ESM import
import { ReefSearch } from 'reef-search';
const reef = new ReefSearch();

// Or attach to window for global access
(window as any).Reef = reef;

// CommonJS
const { ReefSearch } = require('reef-search');
const reef = new ReefSearch();

Framework Integration

React

Add Reef Search to any React application:

// In your main App.tsx or index.tsx
import { useEffect } from 'react';

useEffect(() => {
  const script = document.createElement('script');
  script.src = '/dist/reef.min.js';
  script.setAttribute('data-sitemap', '/sitemap.xml');
  document.head.appendChild(script);
  return () => document.head.removeChild(script);
}, []);

// Or use a custom hook
function useReef() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = '/dist/reef.min.js';
    script.async = true;
    document.head.appendChild(script);
    return () => document.head.removeChild(script);
  }, []);
}

Vue

For Vue 3 applications:

// In main.js or a plugin file
const script = document.createElement('script');
script.src = '/dist/reef.min.js';
script.setAttribute('data-sitemap', '/sitemap.xml');
document.head.appendChild(script);

// In a Vue component
import { onMounted, onUnmounted } from 'vue';

export default {
  setup() {
    onMounted(() => {
      const script = document.createElement('script');
      script.src = '/dist/reef.min.js';
      document.head.appendChild(script);
    });
    onUnmounted(() => {
      document.querySelectorAll('script[src*="reef.min.js"]').forEach(s => s.remove());
    });
  }
}

Svelte / SvelteKit

For Svelte applications, add to +layout.svelte:

<script>
  import { onMount } from 'svelte';
  onMount(() => {
    const script = document.createElement('script');
    script.src = '/dist/reef.min.js';
    document.head.appendChild(script);
    return () => script.remove();
  });
</script>

Next.js / Remix

For React-based frameworks with SSR, add to _document.tsx or root.tsx:

// _document.tsx (Next.js)
import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
        <script 
          src="/dist/reef.min.js" 
          data-sitemap="/sitemap.xml" 
        />
      </body>
    </Html>
  );
}

Static Site Generators

Jekyll / GitHub Pages

Copy reef.min.js to your _includes directory and include in your layout:

{# _includes/head.html #}
<script src="{{ '/dist/reef.min.js' | relative_url }}"></script>

VitePress / VuePress

Configure in config.js or add to your theme:

// config.js
export default {
  head: [
    ['script', { src: '/reef.min.js', attrs: { 'data-sitemap': '/sitemap.xml' } }]
  ]
}

Nuxt / Astro

Add to your layout or nuxt.config.js:

// astro.config.mjs or in a layout
<script is:inline src="/reef.min.js" data-sitemap="/sitemap.xml"></script>

Gatsby

Use gatsby-ssr.js to inject the script:

// gatsby-ssr.js
export const onRenderBody = ({ setPostBodyComponents }) => {
  setPostBodyComponents([
    <script 
      key="reef"
      src="/reef.min.js"
      data-sitemap="/sitemap.xml"
    />
  ]);
};

Sitemap Configuration

Standard Sitemap Location

Place sitemap.xml at your site root (e.g., https://example.com/sitemap.xml). The sitemap format must follow the standard protocol:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
    <lastmod>2024-01-15</lastmod>
    <changefreq>monthly</changefreq>
  </url>
  <url>
    <loc>https://example.com/docs/install.html</loc>
    <lastmod>2024-01-10</lastmod>
  </url>
</urlset>

Custom Sitemap Path

If your sitemap is at a different location, specify it explicitly:

<script 
  src="/reef.min.js" 
  data-sitemap="/sitemap-index.xml">
</script>

⚠️ Sitemap Requirements

Reef Search only indexes pages from the sitemap if they are on the same origin. Cross-origin URLs are skipped for security reasons.

Sitemap Index Files

Reef Search supports sitemap index files (one level of nesting):

<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>https://example.com/sitemap-docs.xml</loc>
  </sitemap>
  <sitemap>
    <loc>https://example.com/sitemap-blog.xml</loc>
  </sitemap>
</sitemapindex>

Generating Sitemaps

Most static site generators have plugins:

GeneratorPlugin
VitePress@vuepress/plugin-sitemap
Next.jsnext-sitemap
Gatsbygatsby-plugin-sitemap
Astro@astrojs/sitemap
JekyllBuilt-in jekyll-sitemap

Troubleshooting

Search doesn't open

No pages are indexed

Only current page is indexed

This typically means Reef couldn't fetch the sitemap. Verify:

// Check your sitemap URL manually
fetch('/sitemap.xml')
  .then(r => r.text())
  .then(console.log)

Cross-Origin Issues

Reef Search enforces same-origin policy for security. If your sitemap contains:

Console Errors

ErrorCauseSolution
[reef] sitemap fetch failed Sitemap not found or CORS blocked Check sitemap path and server configuration
[reef] current page indexing failed Page fetch failed Verify the page is accessible
Failed to execute action Element selector not found Page structure changed or dynamic content

Next Steps

After installation, configure Reef Search to match your needs: