docusaurus-plugin-glossary 2.1.0 → 3.0.2

package/README.md

@@ -636,6 +636,10 @@ MIT
 
 Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started.
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
+
 ## Credits
 
 Built for Docusaurus v3.x

package/dist/components/GlossaryPage.js

@@ -29,10 +29,10 @@ function groupTermsByLetter(terms) {
  * GlossaryPage component - displays all glossary terms
  */
 export default function GlossaryPage({ glossaryData }) {
-  const { siteConfig } = useDocusaurusContext();
+  useDocusaurusContext();
   const [searchTerm, setSearchTerm] = useState('');
 
-  const terms = glossaryData?.terms || [];
+  const terms = useMemo(() => glossaryData?.terms || [], [glossaryData?.terms]);
 
   // Filter terms based on search
   const filteredTerms = useMemo(() => {

package/dist/components/GlossaryPage.test.js

@@ -1,5 +1,5 @@
 import React from 'react';
-import { render, screen, within } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import GlossaryPage from './GlossaryPage';
 

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import type { LoadContext, Plugin } from '@docusaurus/types';
+import remarkGlossaryTerms from './remark/glossary-terms.js';
+export interface GlossaryPluginOptions {
+    glossaryPath?: string;
+    routePath?: string;
+    autoLinkTerms?: boolean;
+}
+export interface GlossaryTerm {
+    term: string;
+    definition: string;
+    abbreviation?: string;
+    relatedTerms?: string[];
+    id?: string;
+}
+export interface GlossaryData {
+    terms: GlossaryTerm[];
+}
+/**
+ * Docusaurus Glossary Plugin
+ *
+ * A plugin that provides glossary functionality with:
+ * - Glossary terms defined in a JSON file
+ * - Auto-generated glossary page with term definitions
+ * - GlossaryTerm component for inline definitions with interactive tooltips
+ * - Automatic client-side initialization via getClientModules() (no manual imports needed)
+ * - Optional automatic glossary term detection in markdown files via remark plugin
+ *
+ * ## Basic Usage (Manual Term Markup)
+ *
+ * Just install the plugin - the GlossaryTerm component is automatically available:
+ * ```javascript
+ * module.exports = {
+ *   plugins: [
+ *     ['docusaurus-plugin-glossary', {
+ *       glossaryPath: 'glossary/glossary.json',
+ *       routePath: '/glossary',
+ *     }],
+ *   ],
+ * };
+ * ```
+ *
+ * Then use `<GlossaryTerm>` in your MDX files without importing:
+ * ```mdx
+ * <GlossaryTerm term="API">API</GlossaryTerm>
+ * ```
+ *
+ * ## Advanced Usage (Automatic Term Detection)
+ *
+ * To automatically detect and link glossary terms in markdown, add the remark plugin:
+ * ```javascript
+ * const glossaryPlugin = require('docusaurus-plugin-glossary');
+ *
+ * module.exports = {
+ *   presets: [
+ *     ['@docusaurus/preset-classic', {
+ *       docs: {
+ *         remarkPlugins: [
+ *           glossaryPlugin.getRemarkPlugin({
+ *             glossaryPath: 'glossary/glossary.json',
+ *             routePath: '/glossary',
+ *           }, { siteDir: __dirname }),
+ *         ],
+ *       },
+ *     }],
+ *   ],
+ *   plugins: [
+ *     ['docusaurus-plugin-glossary', {
+ *       glossaryPath: 'glossary/glossary.json',
+ *       routePath: '/glossary',
+ *     }],
+ *   ],
+ * };
+ * ```
+ *
+ * @param context - Docusaurus context
+ * @param options - Plugin options
+ * @param options.glossaryPath - Path to glossary JSON file (default: 'glossary/glossary.json')
+ * @param options.routePath - Route path for glossary page (default: '/glossary')
+ * @param options.autoLinkTerms - Legacy option, kept for compatibility but no longer used (configure remark plugin manually instead)
+ * @returns Plugin object
+ */
+export default function glossaryPlugin(context: LoadContext, options?: GlossaryPluginOptions): Plugin;
+export declare const remarkPlugin: typeof remarkGlossaryTerms;
+export { clearGlossaryCache } from './remark/glossary-terms.js';
+export { validateGlossaryData, GlossaryValidationError, formatValidationErrors, type ValidationError, type ValidationResult, } from './validation.js';
+/**
+ * Helper function to get the configured remark plugin
+ * This can be used in docusaurus.config.js markdown configuration
+ *
+ * @param pluginOptions - Plugin options from docusaurus.config.js
+ * @param context - Context with siteDir
+ * @returns Configured remark plugin
+ */
+export declare function getRemarkPlugin(pluginOptions: GlossaryPluginOptions, context?: {
+    siteDir?: string;
+}): [typeof remarkGlossaryTerms, {
+    glossaryPath: string;
+    routePath: string;
+    siteDir?: string;
+}];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE7D,OAAO,mBAAmB,MAAM,4BAA4B,CAAC;AAU7D,MAAM,WAAW,qBAAqB;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAgGR;AAGD,eAAO,MAAM,YAAY,4BAAsB,CAAC;AAGhD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGhE,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,qBAAqB,EACpC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,CAAC,OAAO,mBAAmB,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAa7F"}

package/dist/index.js

@@ -1,159 +1,14 @@
-var _a, _b;
 import path from 'path';
+import { fileURLToPath } from 'url';
 import fs from 'fs-extra';
-import { createRequire } from 'module';
 import validatePeerDependencies from 'validate-peer-dependencies';
 import remarkGlossaryTerms from './remark/glossary-terms.js';
-// Helper function to compute __dirname lazily when needed
-// This avoids webpack bundling issues by not using fileURLToPath at module load time
-function getDirname() {
-    var _a;
-    // Check if we're in a Node.js environment
-    if (typeof process === 'undefined' || !((_a = process.versions) === null || _a === void 0 ? void 0 : _a.node)) {
-        return '';
-    }
-    // Use cached value if available
-    const global = globalThis;
-    if (global.__dirnameCache) {
-        return global.__dirnameCache;
-    }
-    // Use a lock to prevent race conditions when multiple calls happen concurrently
-    // This ensures only one execution path computes and sets the cache
-    if (global.__dirnameComputing) {
-        // Another call is already computing __dirname, wait and retry
-        // In practice, this should be rare since module initialization is typically sequential
-        let retries = 0;
-        while (global.__dirnameComputing && retries < 10) {
-            retries++;
-            // Busy wait with a small delay (not ideal but works for module init)
-        }
-        // Return cached value if available after waiting
-        if (global.__dirnameCache) {
-            return global.__dirnameCache;
-        }
-        // If still computing after retries, return empty to avoid deadlock
-        return '';
-    }
-    // Set computing flag to prevent concurrent execution
-    global.__dirnameComputing = true;
-    try {
-        // In Jest/Babel transformed environment, __filename is available
-        // @ts-ignore - __filename is available after Babel transforms ES modules to CommonJS
-        if (typeof __filename !== 'undefined') {
-            const computedDirname = path.dirname(__filename);
-            global.__dirnameCache = computedDirname;
-            return computedDirname;
-        }
-        // Check if import.meta.url is available
-        // Use try-catch to handle cases where import.meta is undefined (e.g., in Jest before transform)
-        let hasImportMetaUrl = false;
-        try {
-            hasImportMetaUrl = typeof import.meta.url !== 'undefined';
-        }
-        catch {
-            // import.meta is undefined (e.g., in Jest environment before Babel transform)
-            return '';
-        }
-        if (!hasImportMetaUrl) {
-            return '';
-        }
-        // Try to compute __dirname using fileURLToPath via createRequire
-        // This avoids webpack trying to bundle fileURLToPath at module load time
-        try {
-            const require = createRequire(import.meta.url);
-            const urlModule = require('url');
-            // Check if fileURLToPath is actually a function (webpack may provide a broken polyfill)
-            if (urlModule && typeof urlModule.fileURLToPath === 'function') {
-                const __filename = urlModule.fileURLToPath(import.meta.url);
-                const computedDirname = path.dirname(__filename);
-                global.__dirnameCache = computedDirname;
-                return computedDirname;
-            }
-        }
-        catch (error) {
-            // If webpack provides a broken polyfill or require fails, return empty
-            // __dirname will be computed when the plugin function is called (server-side only)
-            return '';
-        }
-        return '';
-    }
-    finally {
-        // Always clear the computing flag
-        global.__dirnameComputing = false;
-    }
-}
-// Initialize __dirname at module load time, but handle webpack bundling gracefully
-let __dirname = '';
-let peerDepsValidated = false;
-try {
-    // Only compute __dirname if we're in Node.js (not during webpack bundling)
-    if (typeof process !== 'undefined' && ((_a = process.versions) === null || _a === void 0 ? void 0 : _a.node)) {
-        const global = globalThis;
-        // Set lock to prevent concurrent getDirname() calls during module init
-        if (!global.__dirnameComputing) {
-            global.__dirnameComputing = true;
-            try {
-                // In Jest/Babel transformed environment, __filename is available
-                // @ts-ignore - __filename is available after Babel transforms ES modules to CommonJS
-                if (typeof __filename !== 'undefined') {
-                    __dirname = path.dirname(__filename);
-                    global.__dirnameCache = __dirname;
-                    validatePeerDependencies(__dirname);
-                    peerDepsValidated = true;
-                }
-                else {
-                    // Check if import.meta.url is available - use try-catch since import.meta might be undefined
-                    let hasImportMetaUrl = false;
-                    try {
-                        hasImportMetaUrl = typeof import.meta.url !== 'undefined';
-                    }
-                    catch {
-                        // import.meta is undefined (e.g., in Jest environment before Babel transform)
-                        hasImportMetaUrl = false;
-                    }
-                    if (hasImportMetaUrl) {
-                        const require = createRequire(import.meta.url);
-                        const urlModule = require('url');
-                        // Check if fileURLToPath is actually a function (not a webpack polyfill)
-                        if (urlModule && typeof urlModule.fileURLToPath === 'function') {
-                            const __filename = urlModule.fileURLToPath(import.meta.url);
-                            __dirname = path.dirname(__filename);
-                            global.__dirnameCache = __dirname;
-                            validatePeerDependencies(__dirname);
-                            peerDepsValidated = true;
-                        }
-                    }
-                }
-            }
-            finally {
-                global.__dirnameComputing = false;
-            }
-        }
-        else {
-            // Another module init is already computing, use cached value if available
-            if (global.__dirnameCache) {
-                __dirname = global.__dirnameCache;
-            }
-        }
-    }
-}
-catch {
-    // If initialization fails (e.g., during webpack bundling), __dirname will be empty
-    // and will be computed lazily via getDirname() when needed
-}
-// Validate peer dependencies lazily if not already validated
-if (!peerDepsValidated && typeof process !== 'undefined' && ((_b = process.versions) === null || _b === void 0 ? void 0 : _b.node)) {
-    try {
-        const dirname = getDirname();
-        if (dirname) {
-            validatePeerDependencies(dirname);
-            peerDepsValidated = true;
-        }
-    }
-    catch {
-        // Ignore validation errors during webpack bundling
-    }
-}
+import { validateGlossaryData, GlossaryValidationError } from './validation.js';
+// Standard ES module directory resolution
+const currentFilePath = fileURLToPath(import.meta.url);
+const currentDir = path.dirname(currentFilePath);
+// Validate peer dependencies at module load time
+validatePeerDependencies(currentDir);
 /**
  * Docusaurus Glossary Plugin
  *
@@ -219,25 +74,38 @@ if (!peerDepsValidated && typeof process !== 'undefined' && ((_b = process.versi
  * @returns Plugin object
  */
 export default function glossaryPlugin(context, options = {}) {
-    const { glossaryPath = 'glossary/glossary.json', routePath = '/glossary', autoLinkTerms = true, } = options;
-    let glossaryDataCache = { terms: [] };
+    const { glossaryPath = 'glossary/glossary.json', routePath = '/glossary' } = options;
     return {
         name: 'docusaurus-plugin-glossary',
         getClientModules() {
-            // Compute __dirname if not already set (for webpack bundling compatibility)
-            const pluginDirname = __dirname || getDirname();
-            return [path.resolve(pluginDirname, './client/index.js')];
+            return [path.resolve(currentDir, './client/index.js')];
         },
         async loadContent() {
             // Load glossary terms from JSON file
             const glossaryFilePath = path.resolve(context.siteDir, glossaryPath);
             if (await fs.pathExists(glossaryFilePath)) {
-                const glossaryData = (await fs.readJson(glossaryFilePath));
-                glossaryDataCache = glossaryData;
-                return glossaryData;
+                try {
+                    const rawData = await fs.readJson(glossaryFilePath);
+                    // Validate glossary data structure
+                    const validationResult = validateGlossaryData(rawData, { throwOnError: false });
+                    if (!validationResult.valid) {
+                        console.warn(`[glossary-plugin] Glossary file has validation errors at ${glossaryFilePath}:`);
+                        validationResult.errors.forEach(err => {
+                            console.warn(`  - [${err.field}] ${err.message}`);
+                        });
+                        console.warn('[glossary-plugin] Proceeding with valid terms only.');
+                    }
+                    return validationResult.data;
+                }
+                catch (error) {
+                    if (error instanceof GlossaryValidationError) {
+                        throw error;
+                    }
+                    // JSON parsing error
+                    throw new Error(`Failed to parse glossary file at ${glossaryFilePath}: ${error instanceof Error ? error.message : String(error)}`);
+                }
             }
             console.warn(`Glossary file not found at ${glossaryFilePath}. Using empty glossary.`);
-            glossaryDataCache = { terms: [] };
             return { terms: [] };
         },
         async contentLoaded({ content, actions }) {
@@ -246,16 +114,14 @@ export default function glossaryPlugin(context, options = {}) {
             // Create data file that can be imported by components
             const glossaryDataPath = await createData('glossary-data.json', JSON.stringify(glossaryContent));
             // Create a data file for the remark plugin to access glossary terms
-            const remarkGlossaryDataPath = await createData('remark-glossary-data.json', JSON.stringify({
+            await createData('remark-glossary-data.json', JSON.stringify({
                 terms: glossaryContent.terms || [],
                 routePath: routePath,
             }));
             // Add glossary page route
-            // Compute __dirname if not already set (for webpack bundling compatibility)
-            const pluginDirname = __dirname || getDirname();
             addRoute({
                 path: routePath,
-                component: path.join(pluginDirname, 'components/GlossaryPage.js'),
+                component: path.join(currentDir, 'components/GlossaryPage.js'),
                 exact: true,
                 modules: {
                     glossaryData: glossaryDataPath,
@@ -268,14 +134,12 @@ export default function glossaryPlugin(context, options = {}) {
             });
         },
         getThemePath() {
-            // Compute __dirname if not already set (for webpack bundling compatibility)
-            const pluginDirname = __dirname || getDirname();
-            return path.resolve(pluginDirname, './theme');
+            return path.resolve(currentDir, './theme');
         },
         getPathsToWatch() {
             return [path.resolve(context.siteDir, glossaryPath)];
         },
-        async postBuild({ outDir }) {
+        async postBuild() {
             // You can add any post-build steps here if needed
             console.log('Glossary plugin: Build completed');
         },
@@ -285,6 +149,8 @@ export default function glossaryPlugin(context, options = {}) {
 export const remarkPlugin = remarkGlossaryTerms;
 // Export cache clearing utility
 export { clearGlossaryCache } from './remark/glossary-terms.js';
+// Export validation utilities
+export { validateGlossaryData, GlossaryValidationError, formatValidationErrors, } from './validation.js';
 /**
  * Helper function to get the configured remark plugin
  * This can be used in docusaurus.config.js markdown configuration

package/dist/preset.d.ts

@@ -0,0 +1,97 @@
+import type { Preset, LoadContext } from '@docusaurus/types';
+import type { GlossaryPluginOptions } from './index.js';
+/**
+ * Configuration for @docusaurus/plugin-content-docs
+ * Using Record<string, unknown> to allow any valid docs options without coupling to specific version
+ */
+type DocsConfig = Record<string, unknown> & {
+    remarkPlugins?: unknown[];
+};
+/**
+ * Configuration for @docusaurus/plugin-content-blog
+ * Can be false to disable, or configuration object
+ */
+type BlogConfig = false | (Record<string, unknown> & {
+    remarkPlugins?: unknown[];
+});
+/**
+ * Configuration for @docusaurus/plugin-content-pages
+ */
+type PagesConfig = Record<string, unknown> & {
+    remarkPlugins?: unknown[];
+};
+/**
+ * Configuration for @docusaurus/theme-classic
+ */
+type ThemeConfig = Record<string, unknown>;
+/**
+ * Configuration for analytics plugins
+ */
+type AnalyticsConfig = Record<string, unknown>;
+/**
+ * Configuration for @docusaurus/plugin-sitemap
+ * Can be false to disable, or configuration object
+ */
+type SitemapConfig = false | Record<string, unknown>;
+/**
+ * Classic preset options (simplified to avoid direct dependency on @docusaurus/preset-classic)
+ * These mirror the options available in the classic preset
+ */
+export interface ClassicPresetOptions {
+    docs?: DocsConfig;
+    blog?: BlogConfig;
+    pages?: PagesConfig;
+    theme?: ThemeConfig;
+    gtag?: AnalyticsConfig;
+    googleAnalytics?: AnalyticsConfig;
+    googleTagManager?: AnalyticsConfig;
+    sitemap?: SitemapConfig;
+    debug?: boolean;
+}
+export interface GlossaryPresetOptions extends ClassicPresetOptions {
+    glossary?: GlossaryPluginOptions;
+    /** Internal: Docusaurus adds this, we need to exclude it from classic options */
+    id?: string;
+}
+/**
+ * Docusaurus Glossary Preset
+ *
+ * A preset that extends @docusaurus/preset-classic with automatic glossary functionality.
+ * This preset automatically configures the remark plugin for docs and pages, so you don't
+ * need to manually add it to remarkPlugins.
+ *
+ * @example
+ * ```javascript
+ * export default {
+ *   presets: [
+ *     [
+ *       'docusaurus-plugin-glossary/preset',
+ *       {
+ *         // Glossary options
+ *         glossary: {
+ *           glossaryPath: 'glossary/glossary.json',
+ *           routePath: '/glossary',
+ *         },
+ *         // Classic preset options
+ *         docs: {
+ *           sidebarPath: './sidebars.js',
+ *         },
+ *         blog: {
+ *           showReadingTime: true,
+ *         },
+ *         theme: {
+ *           customCss: './src/css/custom.css',
+ *         },
+ *       },
+ *     ],
+ *   ],
+ * };
+ * ```
+ *
+ * @param context - Docusaurus context
+ * @param options - Preset options including glossary and classic preset options
+ * @returns Preset configuration
+ */
+export default function preset(context: LoadContext, options?: GlossaryPresetOptions): Preset;
+export {};
+//# sourceMappingURL=preset.d.ts.map

package/dist/preset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preset.d.ts","sourceRoot":"","sources":["../src/preset.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD;;;GAGG;AACH,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC1C,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,KAAK,UAAU,GACX,KAAK,GACL,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACzB,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;CAC3B,CAAC,CAAC;AAEP;;GAEG;AACH,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC3C,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE3C;;GAEG;AACH,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE/C;;;GAGG;AACH,KAAK,aAAa,GAAG,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,gBAAgB,CAAC,EAAE,eAAe,CAAC;IACnC,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,iFAAiF;IACjF,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAgGhG"}

package/dist/preset.js

@@ -40,9 +40,12 @@ import glossaryPlugin, { getRemarkPlugin } from './index.js';
  */
 export default function preset(context, options = {}) {
     // Explicitly extract glossary and any Docusaurus-added properties that shouldn't go to classic preset
-    const { glossary = {}, id, ...restOptions } = options;
+    const { glossary = {}, id: _id, ...restOptions } = options;
     // Extract only valid classic preset options
-    const { docs, blog, pages, theme, gtag, googleAnalytics, googleTagManager, sitemap, debug, } = restOptions;
+    // Explicitly type blog and sitemap to preserve union types (can be false)
+    const { docs, pages, theme, gtag, googleAnalytics, googleTagManager, debug } = restOptions;
+    const blog = restOptions.blog;
+    const sitemap = restOptions.sitemap;
     // Build classic options object with only defined properties
     const classicOptions = {};
     if (docs !== undefined)
@@ -63,7 +66,7 @@ export default function preset(context, options = {}) {
         classicOptions.sitemap = sitemap;
     if (debug !== undefined)
         classicOptions.debug = debug;
-    const { glossaryPath = 'glossary/glossary.json', routePath = '/glossary', } = glossary;
+    const { glossaryPath = 'glossary/glossary.json', routePath = '/glossary' } = glossary;
     // Get the remark plugin configuration
     const remarkPlugin = getRemarkPlugin({ glossaryPath, routePath }, { siteDir: context.siteDir });
     // Extend docs configuration with glossary remark plugin
@@ -81,17 +84,14 @@ export default function preset(context, options = {}) {
         remarkPlugins: [...pagesRemarkPlugins, remarkPlugin],
     };
     // Extend blog configuration with glossary remark plugin (optional)
-    const blogConfig = classicOptions.blog;
-    let extendedBlogConfig = blogConfig;
-    if (blogConfig && blogConfig !== false) {
-        const blogRemarkPlugins = typeof blogConfig === 'object' ? blogConfig.remarkPlugins || [] : [];
-        extendedBlogConfig =
-            typeof blogConfig === 'object'
-                ? {
-                    ...blogConfig,
-                    remarkPlugins: [...blogRemarkPlugins, remarkPlugin],
-                }
-                : blogConfig;
+    // Use typeof check for proper type narrowing (blog can be false, object, or undefined)
+    let extendedBlogConfig = blog;
+    if (typeof blog === 'object' && blog !== null) {
+        const blogRemarkPlugins = blog.remarkPlugins || [];
+        extendedBlogConfig = {
+            ...blog,
+            remarkPlugins: [...blogRemarkPlugins, remarkPlugin],
+        };
     }
     // Build the final classic preset options
     const finalClassicOptions = {};
@@ -115,14 +115,14 @@ export default function preset(context, options = {}) {
         finalClassicOptions.debug = debug;
     const plugins = [
         // Add the glossary plugin first
-        function glossaryPluginWrapper(context) {
-            return glossaryPlugin(context, glossary);
+        function glossaryPluginWrapper(ctx) {
+            return glossaryPlugin(ctx, glossary);
         },
     ];
     // Add classic preset plugins individually
     if (extendedDocsConfig)
         plugins.push(['@docusaurus/plugin-content-docs', extendedDocsConfig]);
-    if (extendedBlogConfig && extendedBlogConfig !== false)
+    if (typeof extendedBlogConfig === 'object' && extendedBlogConfig !== null)
         plugins.push(['@docusaurus/plugin-content-blog', extendedBlogConfig]);
     if (extendedPagesConfig)
         plugins.push(['@docusaurus/plugin-content-pages', extendedPagesConfig]);
@@ -138,8 +138,8 @@ export default function preset(context, options = {}) {
         plugins.push(['@docusaurus/plugin-debug', {}]);
     return {
         themes: [
-            // Return classic theme - use string instead of require.resolve so it resolves from user's node_modules
-            '@docusaurus/theme-classic',
+            // Pass theme options (including customCss) to theme-classic
+            ['@docusaurus/theme-classic', theme || {}],
         ],
         plugins,
     };

package/dist/remark/glossary-terms.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Creates a remark plugin that automatically detects and replaces glossary terms in markdown
+ *
+ * This plugin transforms plain text terms into <GlossaryTerm> JSX elements.
+ * The GlossaryTerm component is globally available via the MDXComponents theme wrapper,
+ * so no import injection is needed - MDX files can use it without explicit imports.
+ *
+ * @param {object} options - Plugin options
+ * @param {Array} options.terms - Array of glossary term objects with {term, definition}
+ * @param {string} options.glossaryPath - Path to glossary JSON file (optional, if terms not provided)
+ * @param {string} options.routePath - Route path to glossary page (default: '/glossary')
+ * @param {string} options.siteDir - Docusaurus site directory (required if using glossaryPath)
+ * @returns {function} Remark plugin function
+ */
+export default function remarkGlossaryTerms({ terms, glossaryPath, routePath, siteDir, }?: {
+    terms: any[];
+    glossaryPath: string;
+    routePath: string;
+    siteDir: string;
+}): Function;
+/**
+ * Clears the glossary cache
+ * Useful for testing or when you want to force a reload of glossary data
+ *
+ * @param {string} [filePath] - Optional specific file path to clear. If not provided, clears entire cache.
+ */
+export function clearGlossaryCache(filePath?: string): void;
+//# sourceMappingURL=glossary-terms.d.ts.map

package/dist/remark/glossary-terms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glossary-terms.d.ts","sourceRoot":"","sources":["../../src/remark/glossary-terms.js"],"names":[],"mappings":"AA+DA;;;;;;;;;;;;;GAaG;AACH,2FANG;IAAuB,KAAK;IACJ,YAAY,EAA5B,MAAM;IACU,SAAS,EAAzB,MAAM;IACU,OAAO,EAAvB,MAAM;CACd,YA8VF;AAED;;;;;GAKG;AACH,8CAFW,MAAM,QAQhB"}

package/dist/remark/glossary-terms.js

@@ -2,6 +2,60 @@ import { visit } from 'unist-util-visit';
 import path from 'path';
 import fs from 'fs';
 
+/**
+ * Simple validation for glossary terms loaded from file
+ * Returns only valid terms with required fields
+ *
+ * @param {unknown} data - The parsed JSON data
+ * @param {string} filePath - Path to the file (for error messages)
+ * @returns {{ terms: Array<{term: string, definition: string}>, errors: string[] }}
+ */
+function validateGlossaryTerms(data, _filePath) {
+  const errors = [];
+  const validTerms = [];
+
+  if (data === null || data === undefined) {
+    errors.push(`Glossary data is null or undefined`);
+    return { terms: [], errors };
+  }
+
+  if (typeof data !== 'object') {
+    errors.push(`Glossary data must be an object, got ${typeof data}`);
+    return { terms: [], errors };
+  }
+
+  if (!('terms' in data)) {
+    errors.push(`Glossary data must contain a "terms" array`);
+    return { terms: [], errors };
+  }
+
+  if (!Array.isArray(data.terms)) {
+    errors.push(`Field "terms" must be an array, got ${typeof data.terms}`);
+    return { terms: [], errors };
+  }
+
+  data.terms.forEach((term, index) => {
+    if (term === null || term === undefined || typeof term !== 'object') {
+      errors.push(`terms[${index}]: Term must be an object`);
+      return;
+    }
+
+    if (typeof term.term !== 'string' || term.term.trim() === '') {
+      errors.push(`terms[${index}]: Missing or invalid "term" field`);
+      return;
+    }
+
+    if (typeof term.definition !== 'string') {
+      errors.push(`terms[${index}]: Missing or invalid "definition" field`);
+      return;
+    }
+
+    validTerms.push(term);
+  });
+
+  return { terms: validTerms, errors };
+}
+
 // Cache for glossary data to avoid repeated synchronous file reads
 // Key: absolute file path, Value: { terms, loadedAt }
 const glossaryCache = new Map();
@@ -45,8 +99,33 @@ export default function remarkGlossaryTerms({
         // Consider passing terms directly to avoid this
         if (fs.existsSync(glossaryFilePath)) {
           const fileContent = fs.readFileSync(glossaryFilePath, 'utf8');
-          const glossaryData = JSON.parse(fileContent);
-          glossaryTerms = glossaryData.terms || [];
+          let glossaryData;
+          try {
+            glossaryData = JSON.parse(fileContent);
+          } catch (parseError) {
+            console.error(
+              `[glossary-plugin] Failed to parse glossary JSON at ${glossaryPath}:`,
+              parseError.message
+            );
+            glossaryCache.set(glossaryFilePath, {
+              terms: [],
+              loadedAt: now,
+            });
+            return tree => tree;
+          }
+
+          // Validate glossary data
+          const { terms: validTerms, errors } = validateGlossaryTerms(glossaryData, glossaryPath);
+
+          if (errors.length > 0) {
+            console.warn(`[glossary-plugin] Glossary validation errors in ${glossaryPath}:`);
+            errors.forEach(err => console.warn(`  - ${err}`));
+            if (validTerms.length > 0) {
+              console.warn(`[glossary-plugin] Proceeding with ${validTerms.length} valid term(s).`);
+            }
+          }
+
+          glossaryTerms = validTerms;
 
           // Update cache
           glossaryCache.set(glossaryFilePath, {
@@ -109,14 +188,14 @@ export default function remarkGlossaryTerms({
    * Recursively replace glossary terms in text
    * Returns an array of text nodes and MDX components
    */
-  function replaceTermsInText(text, position) {
+  function replaceTermsInText(text) {
     if (!text || !sortedTerms.length) {
       return [{ type: 'text', value: text }];
     }
 
     const result = [];
     let lastIndex = 0;
-    let textLower = text.toLowerCase();
+    const textLower = text.toLowerCase();
 
     // Find all matches
     const matches = [];

package/dist/theme/GlossaryTerm/index.js

@@ -61,12 +61,23 @@ export default function GlossaryTerm({ term, definition, routePath = '/glossary'
 
   useEffect(() => {
     if (!showTooltip) return;
-    updatePosition();
+
+    // Use double requestAnimationFrame to ensure DOM is fully rendered and layout is complete
+    // This ensures tooltipRef.current is available and has proper dimensions
+    let rafId2;
+    const rafId1 = requestAnimationFrame(() => {
+      rafId2 = requestAnimationFrame(() => {
+        updatePosition();
+      });
+    });
+
     const onScroll = () => updatePosition();
     const onResize = () => updatePosition();
     window.addEventListener('scroll', onScroll, true);
     window.addEventListener('resize', onResize);
     return () => {
+      cancelAnimationFrame(rafId1);
+      if (rafId2) cancelAnimationFrame(rafId2);
       window.removeEventListener('scroll', onScroll, true);
       window.removeEventListener('resize', onResize);
     };

package/dist/theme/GlossaryTerm/index.test.js

@@ -1,5 +1,5 @@
 import React from 'react';
-import { render, screen, within } from '@testing-library/react';
+import { render, screen, act } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import GlossaryTerm from './index';
 
@@ -128,6 +128,14 @@ describe('GlossaryTerm', () => {
     const hasPlacement =
       tooltip.classList.contains('tooltipTop') || tooltip.classList.contains('tooltipBottom');
     expect(hasPlacement).toBe(true);
+    // Wait for the double requestAnimationFrame position update to complete
+    await act(async () => {
+      await new Promise(resolve => {
+        requestAnimationFrame(() => {
+          requestAnimationFrame(resolve);
+        });
+      });
+    });
     // Inline style should include computed top/left
     expect(tooltip.style.top).toMatch(/px$/);
     expect(tooltip.style.left).toMatch(/px$/);

package/dist/theme/GlossaryTerm/styles.module.css

@@ -31,6 +31,9 @@
   border-radius: 0.5rem;
   box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
   font-size: 0.875rem;
+  font-weight: normal;
+  font-style: normal;
+  text-decoration: none;
   line-height: 1.4;
   white-space: normal;
   max-width: 300px;

package/dist/validation.d.ts

@@ -0,0 +1,44 @@
+import type { GlossaryData } from './index.js';
+export interface ValidationError {
+    field: string;
+    message: string;
+    value?: unknown;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    data: GlossaryData;
+}
+/**
+ * Validates glossary data structure
+ *
+ * Ensures the glossary data conforms to the expected schema:
+ * - Must be an object with a "terms" array
+ * - Each term must have "term" (string) and "definition" (string)
+ * - Optional fields: abbreviation (string), relatedTerms (string[]), id (string)
+ *
+ * @param data - The data to validate
+ * @param options - Validation options
+ * @param options.throwOnError - If true, throws an error on validation failure (default: true)
+ * @returns Validation result with errors and sanitized data
+ * @throws Error if data is invalid and throwOnError is true
+ */
+export declare function validateGlossaryData(data: unknown, options?: {
+    throwOnError?: boolean;
+}): ValidationResult;
+/**
+ * Custom error class for glossary validation errors
+ * Provides detailed error messages for debugging
+ */
+export declare class GlossaryValidationError extends Error {
+    readonly errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+}
+/**
+ * Formats validation errors into a readable string
+ *
+ * @param errors - Array of validation errors
+ * @returns Formatted error message
+ */
+export declare function formatValidationErrors(errors: ValidationError[]): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,YAAY,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,IAAI,EAAE,YAAY,CAAC;CACpB;AAiHD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,OAAO,EACb,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GACvC,gBAAgB,CAoGlB;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,SAAgB,MAAM,EAAE,eAAe,EAAE,CAAC;gBAE9B,MAAM,EAAE,eAAe,EAAE;CAWtC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAqBxE"}

package/dist/validation.js

@@ -0,0 +1,246 @@
+/**
+ * Validates a single glossary term object
+ *
+ * @param term - The term object to validate
+ * @param index - The index in the terms array (for error messages)
+ * @returns Array of validation errors (empty if valid)
+ */
+function validateTerm(term, index) {
+    const errors = [];
+    const prefix = `terms[${index}]`;
+    if (term === null || term === undefined) {
+        errors.push({
+            field: prefix,
+            message: 'Term cannot be null or undefined',
+            value: term,
+        });
+        return errors;
+    }
+    if (typeof term !== 'object') {
+        errors.push({
+            field: prefix,
+            message: `Term must be an object, got ${typeof term}`,
+            value: term,
+        });
+        return errors;
+    }
+    const termObj = term;
+    // Required: term (string)
+    if (!('term' in termObj)) {
+        errors.push({
+            field: `${prefix}.term`,
+            message: 'Missing required field "term"',
+        });
+    }
+    else if (typeof termObj.term !== 'string') {
+        errors.push({
+            field: `${prefix}.term`,
+            message: `Field "term" must be a string, got ${typeof termObj.term}`,
+            value: termObj.term,
+        });
+    }
+    else if (termObj.term.trim() === '') {
+        errors.push({
+            field: `${prefix}.term`,
+            message: 'Field "term" cannot be empty',
+            value: termObj.term,
+        });
+    }
+    // Required: definition (string)
+    if (!('definition' in termObj)) {
+        errors.push({
+            field: `${prefix}.definition`,
+            message: 'Missing required field "definition"',
+        });
+    }
+    else if (typeof termObj.definition !== 'string') {
+        errors.push({
+            field: `${prefix}.definition`,
+            message: `Field "definition" must be a string, got ${typeof termObj.definition}`,
+            value: termObj.definition,
+        });
+    }
+    // Optional: abbreviation (string)
+    if ('abbreviation' in termObj && termObj.abbreviation !== undefined) {
+        if (typeof termObj.abbreviation !== 'string') {
+            errors.push({
+                field: `${prefix}.abbreviation`,
+                message: `Field "abbreviation" must be a string, got ${typeof termObj.abbreviation}`,
+                value: termObj.abbreviation,
+            });
+        }
+    }
+    // Optional: relatedTerms (string[])
+    if ('relatedTerms' in termObj && termObj.relatedTerms !== undefined) {
+        if (!Array.isArray(termObj.relatedTerms)) {
+            errors.push({
+                field: `${prefix}.relatedTerms`,
+                message: `Field "relatedTerms" must be an array, got ${typeof termObj.relatedTerms}`,
+                value: termObj.relatedTerms,
+            });
+        }
+        else {
+            termObj.relatedTerms.forEach((relatedTerm, relatedIndex) => {
+                if (typeof relatedTerm !== 'string') {
+                    errors.push({
+                        field: `${prefix}.relatedTerms[${relatedIndex}]`,
+                        message: `Related term must be a string, got ${typeof relatedTerm}`,
+                        value: relatedTerm,
+                    });
+                }
+            });
+        }
+    }
+    // Optional: id (string)
+    if ('id' in termObj && termObj.id !== undefined) {
+        if (typeof termObj.id !== 'string') {
+            errors.push({
+                field: `${prefix}.id`,
+                message: `Field "id" must be a string, got ${typeof termObj.id}`,
+                value: termObj.id,
+            });
+        }
+    }
+    return errors;
+}
+/**
+ * Validates glossary data structure
+ *
+ * Ensures the glossary data conforms to the expected schema:
+ * - Must be an object with a "terms" array
+ * - Each term must have "term" (string) and "definition" (string)
+ * - Optional fields: abbreviation (string), relatedTerms (string[]), id (string)
+ *
+ * @param data - The data to validate
+ * @param options - Validation options
+ * @param options.throwOnError - If true, throws an error on validation failure (default: true)
+ * @returns Validation result with errors and sanitized data
+ * @throws Error if data is invalid and throwOnError is true
+ */
+export function validateGlossaryData(data, options = {}) {
+    const { throwOnError = true } = options;
+    const errors = [];
+    // Check if data is null or undefined
+    if (data === null || data === undefined) {
+        errors.push({
+            field: 'root',
+            message: 'Glossary data cannot be null or undefined',
+            value: data,
+        });
+        if (throwOnError && errors.length > 0) {
+            throw new GlossaryValidationError(errors);
+        }
+        return { valid: false, errors, data: { terms: [] } };
+    }
+    // Check if data is an object
+    if (typeof data !== 'object') {
+        errors.push({
+            field: 'root',
+            message: `Glossary data must be an object, got ${typeof data}`,
+            value: data,
+        });
+        if (throwOnError && errors.length > 0) {
+            throw new GlossaryValidationError(errors);
+        }
+        return { valid: false, errors, data: { terms: [] } };
+    }
+    const glossaryData = data;
+    // Check for terms array
+    if (!('terms' in glossaryData)) {
+        errors.push({
+            field: 'terms',
+            message: 'Glossary data must contain a "terms" array',
+        });
+        if (throwOnError && errors.length > 0) {
+            throw new GlossaryValidationError(errors);
+        }
+        return { valid: false, errors, data: { terms: [] } };
+    }
+    if (!Array.isArray(glossaryData.terms)) {
+        errors.push({
+            field: 'terms',
+            message: `Field "terms" must be an array, got ${typeof glossaryData.terms}`,
+            value: glossaryData.terms,
+        });
+        if (throwOnError && errors.length > 0) {
+            throw new GlossaryValidationError(errors);
+        }
+        return { valid: false, errors, data: { terms: [] } };
+    }
+    // Validate each term
+    const validTerms = [];
+    glossaryData.terms.forEach((term, index) => {
+        const termErrors = validateTerm(term, index);
+        if (termErrors.length > 0) {
+            errors.push(...termErrors);
+        }
+        else {
+            // Term is valid, add to valid terms
+            validTerms.push(term);
+        }
+    });
+    // Check for duplicate terms
+    const termNames = new Map();
+    validTerms.forEach((term, index) => {
+        const lowerName = term.term.toLowerCase();
+        if (termNames.has(lowerName)) {
+            errors.push({
+                field: `terms[${index}].term`,
+                message: `Duplicate term "${term.term}" (first occurrence at index ${termNames.get(lowerName)})`,
+                value: term.term,
+            });
+        }
+        else {
+            termNames.set(lowerName, index);
+        }
+    });
+    if (throwOnError && errors.length > 0) {
+        throw new GlossaryValidationError(errors);
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        data: { terms: validTerms },
+    };
+}
+/**
+ * Custom error class for glossary validation errors
+ * Provides detailed error messages for debugging
+ */
+export class GlossaryValidationError extends Error {
+    constructor(errors) {
+        const message = formatValidationErrors(errors);
+        super(message);
+        this.name = 'GlossaryValidationError';
+        this.errors = errors;
+        // Maintains proper stack trace for where error was thrown (V8 engines)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, GlossaryValidationError);
+        }
+    }
+}
+/**
+ * Formats validation errors into a readable string
+ *
+ * @param errors - Array of validation errors
+ * @returns Formatted error message
+ */
+export function formatValidationErrors(errors) {
+    if (errors.length === 0) {
+        return 'No validation errors';
+    }
+    const header = `Glossary validation failed with ${errors.length} error${errors.length > 1 ? 's' : ''}:`;
+    const errorList = errors
+        .map((err, index) => {
+        let msg = `  ${index + 1}. [${err.field}] ${err.message}`;
+        if (err.value !== undefined) {
+            const valueStr = typeof err.value === 'object' ? JSON.stringify(err.value) : String(err.value);
+            // Truncate long values
+            const truncated = valueStr.length > 50 ? valueStr.substring(0, 50) + '...' : valueStr;
+            msg += ` (got: ${truncated})`;
+        }
+        return msg;
+    })
+        .join('\n');
+    return `${header}\n${errorList}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-glossary",
-  "version": "2.1.0",
+  "version": "3.0.2",
   "description": "A Docusaurus plugin for creating and managing glossary terms with auto-generated pages and inline tooltips",
   "type": "module",
   "main": "dist/index.js",
@@ -38,10 +38,13 @@
     "example:build": "npm --prefix examples/docusaurus-v3 run build",
     "example:serve": "npm --prefix examples/docusaurus-v3 run serve",
     "example:clear": "npm --prefix examples/docusaurus-v3 run clear",
+    "prepare": "husky",
     "prepublishOnly": "npm run build && npm test",
     "version": "npm version",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,md}\"",
-    "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,css,md}\""
+    "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,css,md}\"",
+    "lint": "eslint \"src/**/*.{js,jsx,ts,tsx}\" \"__tests__/**/*.js\"",
+    "lint:fix": "eslint \"src/**/*.{js,jsx,ts,tsx}\" \"__tests__/**/*.js\" --fix"
   },
   "keywords": [
     "docusaurus",
@@ -73,12 +76,18 @@
     "validate-peer-dependencies": "^2.2.0"
   },
   "engines": {
-    "node": ">=16.14"
+    "node": ">=18.0"
   },
   "devDependencies": {
     "@babel/preset-env": "^7.28.5",
     "@babel/preset-react": "^7.28.5",
     "@babel/preset-typescript": "^7.28.5",
+    "@eslint/js": "^9.28.0",
+    "@typescript-eslint/eslint-plugin": "^8.33.0",
+    "@typescript-eslint/parser": "^8.33.0",
+    "eslint": "^9.28.0",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^5.2.0",
     "@docusaurus/tsconfig": "^3.9.2",
     "@docusaurus/types": "^3.9.2",
     "@playwright/test": "^1.56.1",
@@ -89,9 +98,20 @@
     "identity-obj-proxy": "^3.0.0",
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.1",
     "prettier": "^3.6.2",
     "typescript": "^5.7.3"
   },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,css,md}": [
+      "prettier --write"
+    ]
+  },
   "browser": {
     "path": false,
     "url": false,