elastic / elastic/docs-builder

chore: Replace npm deps with native browser APIs

Open
#3,568 1 comment 0 reactions 0 assignees View on GitHub
chore needs triage tech-debt
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

## What

Replace npm dependencies in `src/Elastic.Documentation.Site` with native browser APIs or small local utilities, plus one JS behavior CSS already covers. Each dep is used for one narrow purpose the platform already provides.

## Changes

### `ua-parser-js` → `navigator.userAgentData` / regex
- Used only to detect macOS (⌘ vs Ctrl hint) and Chrome (one `` quirk).
- Replace with `navigator.userAgentData?.platform` + `/mac/i.test(navigator.userAgent)` / `/chrome/i.test(navigator.userAgent)`.
- Files: `Assets/main.ts:53,187`, `Assets/open-details-with-anchor.ts`, `Assets/web-components/NavigationSearch/SearchInput.tsx`

### `@uidotdev/usehooks` → local `useDebounce`
- Entire hooks library imported for a single `useDebounce` hook (3 call sites).
- Add an ~8-line local hook (`useState` + `useEffect` + `setTimeout`/`clearTimeout`).
- Files: `Assets/web-components/{ModalSearch,NavigationSearch,FullPageSearch}/use*Query.ts`

### `lodash` + `@types/lodash` → local throttle
- Full lodash imported for one `throttle` call in `Assets/pages-nav.ts:1,91`.
- Add a ~6-line local throttle function or use `import throttle from 'lodash/throttle'` as an intermediate step before dropping the dep entirely.

### `smooth-scroll.ts` → CSS `scroll-behavior`
- The in-page anchor smooth-scroll handler reimplements what CSS ships: `html { scroll-behavior: smooth }` + `scroll-margin-top` on targets (no `scroll-behavior` is currently defined). The browser updates the hash natively on anchor clicks.
- Delete `Assets/smooth-scroll.ts` and its registration. (~17 lines)

### `select-dom` → local `$`/`$$` helpers (optional)
- Thin wrapper over `querySelector`/`querySelectorAll` used across 8 files.
- A 4-line local helper removes the dep: `const $ = (sel, root = document) => root.querySelector(sel)`.
- 21 call sites — more churn than the others; do last or skip if the savings don't justify it.

Part of the broader ponytail over-engineering audit tracked in #3574.

Contributor guide

Open the contributing guide

Research direction

Start with the listed Assets/main.ts, Assets/open-details-with-anchor.ts, Assets/web-components/NavigationSearch/SearchInput.tsx, the three use*Query.ts files, Assets/pages-nav.ts, and Assets/smooth-scroll.ts. Trace each dependency's call sites before replacing it with the specified browser API, local utility, or CSS behavior. Done means the listed replacements work, smooth scrolling remains covered by CSS, and the unnecessary dependencies and registrations are removed.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend, web-dev
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.