Frontend Improvement Roadmap: Testing, Refactoring & DX Enhancements

[vredchenko]

Overview

This issue documents a comprehensive improvement roadmap for the SmartEM frontend, based on an analysis conducted in October 2025 and re-evaluated in January 2026 against the current codebase state.

Current Assessment: 7/10 - Solid foundation with room for modernization and refinement.

---

What's Already Done ✅

Recommendation	Implementation
Linting	Biome 2.2.5 (chose over ESLint - faster, modern)
Git Hooks	Lefthook with pre-commit and pre-push hooks
Dependency Updates	Dependabot (weekly for npm, docker, GitHub Actions)
Security Scanning	OSV scanner workflow

---

Tier 1: Critical (Highest ROI)

1. Testing Infrastructure

Status: 0% test coverage - most critical gap

Current state:

• No Vitest or any test framework
• No test files in codebase
• No test scripts in package.json

Action items:

• Install Vitest + Testing Library + happy-dom
• Create vitest.config.ts
• Add test scripts to package.json
• Create test utilities (src/test/setup.ts, custom render with providers)
• Write tests for mutator.ts and ApiVersionCheck
• Target 70% coverage for shared components and hooks

2. Fix TypeScript Suppressions

Status: 1 @ts-expect-error in src/api/mutator.ts:51

Fix:

type CancellablePromise<T> = Promise<T> & {
  cancel: () => void
}

export const customInstance = <T>(
  config: AxiosRequestConfig,
  options?: AxiosRequestConfig
): CancellablePromise<T> => {
  const source = Axios.CancelToken.source()
  const promise = AXIOS_INSTANCE({
    ...config,
    ...options,
    cancelToken: source.token,
  }).then(({ data }) => data) as CancellablePromise<T>

  promise.cancel = () => {
    source.cancel('Query was cancelled')
  }

  return promise
}

3. Extract Custom Hooks

Status: Route files are monolithic with business logic embedded

Current file sizes:

• atlas.tsx: 411 lines with 15+ useState calls
• squares.$squareId.tsx: 384 lines with 15+ useState calls
• index.tsx: 266 lines
• square.$squareId.predictions.tsx: 261 lines

Action items:

• Create src/hooks/ directory
• Extract usePredictions(gridId) - used in atlas and squares
• Extract useLatentRepresentation(gridId)
• Extract useGridSquares(gridId)
• Reduce route components to <150 lines each

---

Tier 2: High Value

4. Remove React Namespace from Hooks

Status: 50+ instances of React.useState, React.useEffect

Before:

import React from 'react'
const [state, setState] = React.useState(false)

After:

import { useState } from 'react'
const [state, setState] = useState(false)

• Apply codemod or manual refactor across all files

5. Split Large Components

Status: 6 components in flat src/components/ structure

Proposed extractions from atlas route:

• LatentSpacePanel component
• PredictionControls component
• GridSquareOverlay component (shareable)

6. Add TanStack Query DevTools

Status: Dependencies present but not imported

• Add to __root.tsx:

import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

// In component
{import.meta.env.DEV && <ReactQueryDevtools initialIsOpen={false} />}

---

Tier 3: Medium Value (When Time Permits)

Item	Notes
Bundle analysis	Add rollup-plugin-visualizer with analyze script
Env validation	Consider Zod schema for VITE_* vars
Code splitting	lazy() for heavy components like charts
Virtual scrolling	If list performance becomes an issue
VS Code debug config	Quick DX improvement

---

Skip List

These items from the original analysis are not recommended for implementation:

Item	Reason
Feature-based structure	Major refactor, low ROI with TanStack Router's file-based routing
Barrel exports	Over-engineering for current component count (6)
Additional TS strict checks	verbatimModuleSyntax already enabled
Inline styles → sx	Low priority, works fine with MUI
Compound components	Over-engineering for current scale
Storybook	High effort, low value for 6 components
PWA/Offline	Not relevant for this use case
Dark mode	Nice-to-have, not critical

---

Implementation Phases

Phase 1 - Foundation (1-2 weeks)

1. Set up Vitest + Testing Library
2. Fix @ts-expect-error in mutator.ts
3. Add TanStack Query DevTools
4. Write tests for mutator.ts and ApiVersionCheck

Phase 2 - Refactoring (2-3 weeks)

1. Create src/hooks/ and extract shared hooks
2. Remove React. namespace from hooks
3. Split atlas.tsx into smaller components

Phase 3 - Optimization (as needed)

1. Bundle analysis
2. Code splitting for chart components
3. Prefetching on hover

---

References

• Original analysis: enhancements.md in repo root
• Analysis date: October 2025
• Re-evaluation date: January 2026