rspress-plugin-typesense 0.0.3 → 0.1.0

package/README.md

@@ -108,12 +108,6 @@ export interface TypesensePluginOptions {
    */
   indexCodeBlocks?: boolean;
 
-  /**
-   * Whether a failed indexing attempt should crash the build process.
-   * Defaults to `true`.
-   */
-  failOnIndexError?: boolean;
-
   /**
    * Whether to automatically filter search results by the active documentation version.
    * Defaults to `true`.
@@ -195,13 +189,6 @@ In the frontend, you could now pass `typesenseSearchParams: { filter_by: 'catego
 
 By default, the plugin only indexes headers (`h1-h6`), paragraphs, lists and tables. Enabling this will also extract text from inside code blocks.
 
-### failOnIndexError
-
-- **Type**: `boolean`
-- **Default**: `true`
-
-By default, if the Typesense indexing step fails (e.g., network timeout), the build process will crash. Set this to `false` if you want your CI/CD deployments to succeed even if search indexing fails.
-
 ### versionedSearch
 
 - **Type**: `boolean`
@@ -265,6 +252,40 @@ import { Search as PluginTypesenseSearch } from 'rspress-plugin-typesense/runtim
 />;
 ```
 
+## Local development
+
+Install dependencies and watch the library for changes:
+
+```bash
+bun install
+bun run dev
+```
+
+In a second terminal, start the example Rspress site:
+
+```bash
+cd docs
+bun install
+bun run dev
+```
+
+If you want to test indexing and search locally, start Typesense as well:
+
+```bash
+docker compose up -d
+```
+
+### Integration tests
+
+Integration tests use Rstest and require a running Typesense instance. Start Typesense and run the suite:
+
+```bash
+docker compose up -d
+bun run test:integration
+```
+
+The suite builds the package, installs the generated bun tarball into a temporary copy of `docs`, builds the Rspress site, and verifies the results from the Typesense Docker instance.
+
 ## License
 
 Licensed under the Apache 2.0 License, Copyright © Typesense.

package/dist/index.d.ts

@@ -30,11 +30,6 @@ export interface TypesensePluginOptions {
      * Defaults to `false` to avoid search noise and bloated index sizes.
      */
     indexCodeBlocks?: boolean;
-    /**
-     * Whether a failed indexing attempt should crash the build process.
-     * Defaults to `true`.
-     */
-    failOnIndexError?: boolean;
     /**
      * Whether to automatically filter search results by the active documentation version.
      * Defaults to `true`.

package/dist/index.js

@@ -72,9 +72,8 @@ function pluginTypesense(options) {
                 } catch (error) {
                     console.error(`\n\x1b[31m✖ [TypesensePlugin] Failed to initialize/create collection:\x1b[0m \x1b[37m${collectionNameTmp}\x1b[0m`);
                     console.error(`  \x1b[31m↳ ${error instanceof Error ? error.message : error}\x1b[0m\n`);
-                    if (false !== options.failOnIndexError) throw error;
-                    console.warn("\x1b[33m⚠ [TypesensePlugin] Skipping group indexing due to failOnIndexError=false.\x1b[0m");
-                    continue;
+                    await helper.discardTmpCollection();
+                    throw error;
                 }
                 let totalRecords = 0;
                 for (const route of routes){
@@ -95,7 +94,8 @@ function pluginTypesense(options) {
                         const fillerLength = Math.max(2, padLength - route.routePath.length);
                         const filler = '\x1b[90m' + '.'.repeat(fillerLength) + '\x1b[0m';
                         console.warn(`  \x1b[33m⚠\x1b[0m \x1b[37m${route.routePath}\x1b[0m ${filler} \x1b[33mskipped\x1b[0m \x1b[90m(HTML not found)\x1b[0m`);
-                        continue;
+                        await helper.discardTmpCollection();
+                        throw new Error(`HTML not found for route ${route.routePath}`);
                     }
                     try {
                         const htmlContent = fs.readFileSync(htmlPath, 'utf-8');
@@ -110,9 +110,9 @@ function pluginTypesense(options) {
                         if (error instanceof ImportError) {
                             console.error("    \x1b[31m↳ Import error\x1b[0m");
                             console.error(error.importResults);
-                            if (false !== options.failOnIndexError) throw error;
-                            console.warn("\x1b[33m⚠ [TypesensePlugin] Skipping failure due to failOnIndexError=false.\x1b[0m");
                         } else console.error(`    \x1b[31m↳ ${error instanceof Error ? error.message : error}\x1b[0m`);
+                        await helper.discardTmpCollection();
+                        throw error;
                     }
                 }
                 try {
@@ -121,8 +121,7 @@ function pluginTypesense(options) {
                 } catch (error) {
                     console.error(`\n\x1b[31m✖ [TypesensePlugin] Failed to commit collection:\x1b[0m \x1b[37m${aliasName}\x1b[0m`);
                     console.error(`  \x1b[31m↳ ${error instanceof Error ? error.message : error}\x1b[0m\n`);
-                    if (false !== options.failOnIndexError) throw error;
-                    console.warn("\x1b[33m⚠ [TypesensePlugin] Skipping failure due to failOnIndexError=false.\x1b[0m");
+                    throw error;
                 }
             }
         }

package/dist/runtime/Search.css

@@ -1,76 +1,9 @@
-[class*="DocSearch"] {
-  --docsearch-searchbox-shadow: inset 0 0 0 2px var(--rp-c-brand);
-  --docsearch-primary-color: var(--rp-c-brand);
-  --docsearch-text-color: var(--rp-c-text-1);
-  --docsearch-secondary-text-color: var(--rp-c-text-2);
-  --docsearch-muted-color: var(--rp-c-text-2);
-  --docsearch-subtle-color: var(--rp-c-divider-light);
-  --docsearch-container-background: #3c3c3c66;
-  --docsearch-modal-background: var(--rp-c-bg);
-  --docsearch-search-button-background: color-mix(in srgb,
-    var(--rp-c-bg) 30%,
-    transparent);
-  --docsearch-search-button-text-color: var(--rp-c-text-2);
-  --docsearch-searchbox-background: color-mix(in srgb,
-    var(--rp-c-bg) 30%,
-    transparent);
-  --docsearch-searchbox-focus-background: color-mix(in srgb,
-    var(--rp-c-bg) 30%,
-    transparent);
-  --docsearch-hit-highlight-color: var(--rp-c-brand-tint);
-  --docsearch-hit-color: var(--rp-c-text-1);
-  --docsearch-hit-background: var(--rp-c-bg-soft);
-  --docsearch-hit-shadow: var(--rp-shadow-2);
-  --docsearch-footer-background: var(--rp-c-bg);
-  --docsearch-key-background: var(--rp-c-bg-mute);
-  --docsearch-key-color: var(--rp-c-text-2);
-  --docsearch-highlight-color: var(--rp-c-brand);
-  --docsearch-icon-color: var(--rp-c-text-1);
-  --docsearch-background-color: var(--rp-c-bg-mute);
-  --docsearch-focus-color: var(--rp-c-brand);
-  --docsearch-dropdown-menu-background: var(--rp-c-bg-soft);
-  --docsearch-dropdown-menu-item-hover-background: var(--rp-c-bg);
-}
-
-html.dark {
-  --docsearch-text-color: #f5f6f7;
-  --docsearch-container-background: #090a11cc;
-  --docsearch-modal-background: #15172a;
-  --docsearch-modal-shadow: inset 1px 1px 0 0 #2c2e40, 0 3px 8px 0 #000309;
-  --docsearch-searchbox-background: #090a11;
-  --docsearch-searchbox-focus-background: #000;
-  --docsearch-hit-color: #bec3c9;
-  --docsearch-hit-shadow: none;
-  --docsearch-hit-background: #090a11;
-  --docsearch-key-gradient: linear-gradient(-26.5deg,
-    #565872 0%,
-    #31355b 100%);
-  --docsearch-key-shadow: inset 0 -2px 0 0 #282d55, inset 0 0 1px 1px #51577d,
-    0 2px 2px 0 #0304094d;
-  --docsearch-footer-background: #1e2136;
-  --docsearch-footer-shadow: inset 0 1px 0 0 #494c6a80, 0 -4px 8px 0 #0003;
-  --docsearch-logo-color: #fff;
-  --docsearch-muted-color: #7f8497;
-}
-
-.DocSearch {
-  border-radius: var(--rp-radius-small);
-}
-
-.DocSearch-Button-Container > .DocSearch-Button-Placeholder {
-  font-size: .825rem;
-}
-
 .DocSearch-Button {
-  border: 1px solid var(--docsearch-subtle-color);
-}
-
-.DocSearch-Button:hover {
-  box-shadow: none;
-  color: var(--docsearch-search-button-text-color);
-}
-
-.DocSearch-Screen-Icon svg {
-  margin: auto;
+  color: var(--docsearch-muted-color);
+  border-color: var(--rp-c-divider-light, #d1d1d1);
+  background-color: var(--docsearch-search-button-background);
+  background-color: color-mix(in srgb,
+    var(--docsearch-search-button-background) 30%,
+    transparent);
 }
 

package/dist/runtime/index.d.ts

@@ -1,3 +1,3 @@
-export { type Locales, RU_LOCALES, ZH_LOCALES, VN_LOCALES } from './locales.js';
+export { type Locales, RU_LOCALES, ZH_LOCALES, VI_LOCALES } from './locales.js';
 export { Search, type SearchProps } from './Search.js';
 export type { TypesenseDocSearchProps } from './RealSearch.js';

package/dist/runtime/index.js

@@ -1,2 +1,2 @@
-export { RU_LOCALES, VN_LOCALES, ZH_LOCALES } from "./locales.js";
+export { RU_LOCALES, VI_LOCALES, ZH_LOCALES } from "./locales.js";
 export { Search } from "./Search.js";

package/dist/runtime/locales.d.ts

@@ -1,8 +1,22 @@
 import type { DocSearchProps } from 'typesense-docsearch-react';
-export type Locales = Record<string, {
-    translations: DocSearchProps['translations'];
+/**
+ * Recursively removes `?` and `undefined` from all nested properties
+ */
+type DeepRequired<T> = T extends (...args: any[]) => any ? T : T extends readonly (infer U)[] ? readonly DeepRequired<NonNullable<U>>[] : T extends object ? {
+    [K in keyof T]-?: DeepRequired<NonNullable<T[K]>>;
+} : NonNullable<T>;
+export type RequiredTranslations = DeepRequired<NonNullable<DocSearchProps['translations']>>;
+export type StrictLocaleConfig = {
     placeholder: string;
-}>;
-export declare const ZH_LOCALES: Locales;
-export declare const RU_LOCALES: Locales;
-export declare const VN_LOCALES: Locales;
+    translations: RequiredTranslations;
+};
+export type LocaleConfig = {
+    placeholder: string;
+    translations?: DocSearchProps['translations'];
+};
+export type StrictLocales = Record<string, StrictLocaleConfig>;
+export type Locales = Record<string, LocaleConfig>;
+export declare const ZH_LOCALES: StrictLocales;
+export declare const RU_LOCALES: StrictLocales;
+export declare const VI_LOCALES: StrictLocales;
+export {};

package/dist/runtime/locales.js

@@ -8,10 +8,13 @@ const ZH_LOCALES = {
             },
             modal: {
                 searchBox: {
-                    resetButtonTitle: '清除查询条件',
-                    resetButtonAriaLabel: '清除查询条件',
-                    cancelButtonText: '取消',
-                    cancelButtonAriaLabel: '取消'
+                    clearButtonTitle: '清除查询条件',
+                    clearButtonAriaLabel: '清除查询条件',
+                    closeButtonText: '取消',
+                    closeButtonAriaLabel: '取消',
+                    placeholderText: '搜索文档',
+                    enterKeyHint: 'search',
+                    searchInputLabel: '搜索'
                 },
                 startScreen: {
                     recentSearchesTitle: '搜索历史',
@@ -27,8 +30,15 @@ const ZH_LOCALES = {
                 },
                 footer: {
                     selectText: '选择',
+                    submitQuestionText: '提交问题',
+                    selectKeyAriaLabel: '回车键',
                     navigateText: '切换',
+                    navigateUpKeyAriaLabel: '向上箭头',
+                    navigateDownKeyAriaLabel: '向下箭头',
                     closeText: '关闭',
+                    backToSearchText: '返回搜索',
+                    closeKeyAriaLabel: 'Esc 键',
+                    poweredByText: '由…提供支持',
                     searchByText: '搜索提供者'
                 },
                 noResultsScreen: {
@@ -36,6 +46,22 @@ const ZH_LOCALES = {
                     suggestedQueryText: '你可以尝试查询',
                     reportMissingResultsText: '你认为该查询应该有结果？',
                     reportMissingResultsLinkText: '点击反馈'
+                },
+                facets: {
+                    defaultValueLabel: '全部',
+                    facetMenuTriggerAriaLabel: '筛选菜单',
+                    clearAllLabel: '清除全部',
+                    facetsAriaLabel: '筛选条件',
+                    selectedFacetsAriaLabel: '已选筛选条件',
+                    clearFacetAriaLabel: '清除筛选'
+                },
+                resultsScreen: {
+                    askAiPlaceholder: '询问 AI：',
+                    noResultsAskAiPlaceholder: '文档里没找到？让 AI 帮忙：',
+                    resultsSectionTitle: '搜索结果',
+                    askAiResultsTitle: 'AI 回答',
+                    resultBadgeLabelText: '分类',
+                    recentConversationTimestampFallback: '刚刚'
                 }
             }
         }
@@ -51,10 +77,13 @@ const RU_LOCALES = {
             },
             modal: {
                 searchBox: {
-                    resetButtonTitle: 'Очистить поиск',
-                    resetButtonAriaLabel: 'Очистить поиск',
-                    cancelButtonText: 'Закрыть',
-                    cancelButtonAriaLabel: 'Закрыть'
+                    clearButtonTitle: 'Очистить поиск',
+                    clearButtonAriaLabel: 'Очистить поиск',
+                    closeButtonText: 'Закрыть',
+                    closeButtonAriaLabel: 'Закрыть',
+                    placeholderText: 'Поиск в документации',
+                    enterKeyHint: 'search',
+                    searchInputLabel: 'Поиск'
                 },
                 startScreen: {
                     recentSearchesTitle: 'История поиска',
@@ -70,8 +99,15 @@ const RU_LOCALES = {
                 },
                 footer: {
                     selectText: 'выбрать',
+                    submitQuestionText: 'Задать вопрос',
+                    selectKeyAriaLabel: 'Клавиша Enter',
                     navigateText: 'перейти',
+                    navigateUpKeyAriaLabel: 'Стрелка вверх',
+                    navigateDownKeyAriaLabel: 'Стрелка вниз',
                     closeText: 'закрыть',
+                    backToSearchText: 'Назад к поиску',
+                    closeKeyAriaLabel: 'Клавиша Escape',
+                    poweredByText: 'При поддержке',
                     searchByText: 'поиск от'
                 },
                 noResultsScreen: {
@@ -79,13 +115,29 @@ const RU_LOCALES = {
                     suggestedQueryText: 'Попробуйте изменить запрос',
                     reportMissingResultsText: 'Считаете, что результаты должны быть?',
                     reportMissingResultsLinkText: 'Сообщите об этом'
+                },
+                facets: {
+                    defaultValueLabel: 'Все',
+                    facetMenuTriggerAriaLabel: 'Меню фильтров',
+                    clearAllLabel: 'Очистить все',
+                    facetsAriaLabel: 'Фильтры',
+                    selectedFacetsAriaLabel: 'Выбранные фильтры',
+                    clearFacetAriaLabel: 'Удалить фильтр'
+                },
+                resultsScreen: {
+                    askAiPlaceholder: 'Спросить AI: ',
+                    noResultsAskAiPlaceholder: 'Не нашли в документации? Спросите AI: ',
+                    resultsSectionTitle: 'Результаты',
+                    askAiResultsTitle: 'Ответ AI',
+                    resultBadgeLabelText: 'Категория',
+                    recentConversationTimestampFallback: 'Недавно'
                 }
             }
         }
     }
 };
-const VN_LOCALES = {
-    vn: {
+const VI_LOCALES = {
+    vi: {
         placeholder: 'Tìm kiếm tài liệu',
         translations: {
             button: {
@@ -94,10 +146,13 @@ const VN_LOCALES = {
             },
             modal: {
                 searchBox: {
-                    resetButtonTitle: 'Xóa truy vấn',
-                    resetButtonAriaLabel: 'Xóa truy vấn',
-                    cancelButtonText: 'Hủy',
-                    cancelButtonAriaLabel: 'Hủy'
+                    clearButtonTitle: 'Xóa truy vấn',
+                    clearButtonAriaLabel: 'Xóa truy vấn',
+                    closeButtonText: 'Hủy',
+                    closeButtonAriaLabel: 'Hủy',
+                    placeholderText: 'Tìm kiếm tài liệu',
+                    enterKeyHint: 'search',
+                    searchInputLabel: 'Tìm kiếm'
                 },
                 startScreen: {
                     recentSearchesTitle: 'Gần đây',
@@ -113,8 +168,15 @@ const VN_LOCALES = {
                 },
                 footer: {
                     selectText: 'để chọn',
+                    submitQuestionText: 'Gửi câu hỏi',
+                    selectKeyAriaLabel: 'Phím Enter',
                     navigateText: 'để di chuyển',
+                    navigateUpKeyAriaLabel: 'Mũi tên lên',
+                    navigateDownKeyAriaLabel: 'Mũi tên xuống',
                     closeText: 'để đóng',
+                    backToSearchText: 'Quay lại tìm kiếm',
+                    closeKeyAriaLabel: 'Phím Escape',
+                    poweredByText: 'Vận hành bởi',
                     searchByText: 'Vận hành bởi'
                 },
                 noResultsScreen: {
@@ -122,9 +184,25 @@ const VN_LOCALES = {
                     suggestedQueryText: 'Hãy thử tìm với từ khóa',
                     reportMissingResultsText: 'Bạn nghĩ truy vấn này nên có kết quả?',
                     reportMissingResultsLinkText: 'Hãy cho chúng tôi biết.'
+                },
+                facets: {
+                    defaultValueLabel: 'Tất cả',
+                    facetMenuTriggerAriaLabel: 'Menu bộ lọc',
+                    clearAllLabel: 'Xóa tất cả',
+                    facetsAriaLabel: 'Bộ lọc',
+                    selectedFacetsAriaLabel: 'Các bộ lọc đã chọn',
+                    clearFacetAriaLabel: 'Xóa bộ lọc'
+                },
+                resultsScreen: {
+                    askAiPlaceholder: 'Hỏi AI: ',
+                    noResultsAskAiPlaceholder: 'Không tìm thấy trong tài liệu? Hỏi AI: ',
+                    resultsSectionTitle: 'Kết quả tìm kiếm',
+                    askAiResultsTitle: 'Câu trả lời từ AI',
+                    resultBadgeLabelText: 'Danh mục',
+                    recentConversationTimestampFallback: 'Vừa xong'
                 }
             }
         }
     }
 };
-export { RU_LOCALES, VN_LOCALES, ZH_LOCALES };
+export { RU_LOCALES, VI_LOCALES, ZH_LOCALES };

package/dist/typesenseHelper.d.ts

@@ -21,6 +21,7 @@ export declare class TypesenseHelper {
     init(): Promise<void>;
     createTmpCollection(): Promise<void>;
     addRecords(records: DocSearchRecord[], fileName: string, fromSitemap: boolean, padLength?: number): Promise<number>;
+    discardTmpCollection(): Promise<void>;
     commitTmpCollection(): Promise<void>;
     static transformRecord(record: DocSearchRecord, isVersioned: boolean): any;
     private getOldCollectionName;

package/dist/typesenseHelper.js

@@ -80,16 +80,42 @@ class TypesenseHelper {
         console.log(`  ${iconColor}✔\x1b[0m \x1b[37m${fileName}\x1b[0m ${filler} \x1b[33m${paddedCount}\x1b[0m \x1b[90mrecords\x1b[0m`);
         return recordCount;
     }
+    async discardTmpCollection() {
+        try {
+            await this.typesenseClient.collections(this.collectionNameTmp).delete();
+        } catch (error) {
+            if (error?.httpStatus !== 404) throw error;
+        }
+    }
     async commitTmpCollection() {
-        const oldCollectionName = await this.getOldCollectionName();
-        if (oldCollectionName) {
-            await this.transferSynonyms(oldCollectionName);
-            await this.transferOverrides(oldCollectionName);
+        let oldCollectionName = null;
+        let aliasUpdated = false;
+        try {
+            oldCollectionName = await this.getOldCollectionName();
+            if (oldCollectionName) {
+                await this.transferSynonyms(oldCollectionName);
+                await this.transferOverrides(oldCollectionName);
+            }
+            await this.typesenseClient.aliases().upsert(this.aliasName, {
+                collection_name: this.collectionNameTmp
+            });
+            aliasUpdated = true;
+            if (oldCollectionName) await this.typesenseClient.collections(oldCollectionName).delete();
+        } catch (error) {
+            try {
+                if (aliasUpdated) if (oldCollectionName) await this.typesenseClient.aliases().upsert(this.aliasName, {
+                    collection_name: oldCollectionName
+                });
+                else await this.typesenseClient.aliases(this.aliasName).delete();
+                await this.discardTmpCollection();
+            } catch (rollbackError) {
+                const message = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
+                throw new Error(`Failed to roll back collection commit for ${this.aliasName}: ${message}`, {
+                    cause: rollbackError
+                });
+            }
+            throw error;
         }
-        await this.typesenseClient.aliases().upsert(this.aliasName, {
-            collection_name: this.collectionNameTmp
-        });
-        if (oldCollectionName) await this.typesenseClient.collections(oldCollectionName).delete();
     }
     static transformRecord(record, isVersioned) {
         const transformedRecord = {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rspress-plugin-typesense",
   "description": "A plugin that adds lightning-fast, typo-tolerant, Typesense-powered search to your Rspress site",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "type": "module",
   "exports": {
     ".": {
@@ -19,10 +19,13 @@
   ],
   "scripts": {
     "build": "rslib build",
-    "dev": "rslib build --watch"
+    "dev": "rslib build --watch",
+    "typecheck": "tsc --noEmit",
+    "test:integration": "rstest"
   },
   "devDependencies": {
     "@rslib/core": "^0.20.1",
+    "@rstest/core": "0.11.11",
     "@types/node": "^24.12.0",
     "rsbuild-plugin-publint": "^0.3.4",
     "typescript": "^6.0.2"
@@ -33,8 +36,8 @@
   "dependencies": {
     "cheerio": "^1.2.0",
     "typesense": "^3.0.6",
-    "typesense-docsearch-css": "^0.4.1",
-    "typesense-docsearch-react": "^3.4.1"
+    "typesense-docsearch-css": "5.0.2-0",
+    "typesense-docsearch-react": "5.0.2-0"
   },
   "keywords": [
     "typesense",