Skip to main content

local-search-will-not-work-in-dev

Disallow assuming configured local-search providers will produce a reliable search experience during docusaurus start.

Targeted pattern scopeโ€‹

This rule focuses on docusaurus.config.* files.

It reports known local-search provider entries such as:

  • @cmfcmf/docusaurus-search-local
  • @easyops-cn/docusaurus-search-local
  • docusaurus-plugin-search-local

What this rule reportsโ€‹

This rule reports local-search provider configuration so maintainers remember that these plugins build a static search index and are not meant to be tested through the normal dev-server search experience.

Why this rule existsโ€‹

Local-search plugins are attractive because they avoid external search services, but they usually index content during a production-style build.

That means maintainers can easily assume search is broken when testing with docusaurus start, even though the real issue is the runtime expectation.

โŒ Incorrectโ€‹

export default {
    themes: ["@easyops-cn/docusaurus-search-local"],
};

โœ… Correctโ€‹

export default {
    themes: ["@easyops-cn/docusaurus-search-local"],
};

with the expectation that search should be validated after docusaurus build and docusaurus serve, not through docusaurus start.

Behavior and migration notesโ€‹

This rule is intentionally report-only and informational.

It does not remove the plugin or rewrite the config.

Live runtime expectation demoโ€‹

function LocalSearchRuntimeHint() {
    const [mode, setMode] = useState("start");
    const isStaticMode = mode === "serve";

    return (
        <div
            style={{
                border: "1px solid rgb(37 194 160 / 45%)",
                borderRadius: 12,
                padding: 16,
            }}
        >
            <button
                type="button"
                onClick={() => setMode(isStaticMode ? "start" : "serve")}
            >
                Toggle runtime ({mode})
            </button>
            <p style={{ margin: "0.85rem 0 0" }}>
                {isStaticMode
                    ? "The statically built site is being served, so a local-search index can be available."
                    : "The dev server is running, so local-search indexing may not reflect the real built search experience yet."}
            </p>
        </div>
    );
}

render(<LocalSearchRuntimeHint />);

ESLint flat config exampleโ€‹

import docusaurus2 from "eslint-plugin-docusaurus-2";

export default [
    {
        rules: {
            "docusaurus-2/local-search-will-not-work-in-dev": "warn",
        },
    },
];

This rule is intentionally opt-in only and is not included in any shipped preset.

When not to use itโ€‹

Do not use this rule if your team already understands the build-only runtime expectation of local-search providers and you do not want linting to repeat that reminder.

Rule catalog ID: R104

Further readingโ€‹