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 (deleted — content recycled to this issue and smartem-devtools PR #160)
• Analysis date: October 2025
• Re-evaluation date: January 2026

[vredchenko]

Tier 3 code examples (recycled from enhancements.md before deletion)

The original enhancements.md analysis is being deleted from repo root — the content below adds useful detail to the tier 3 one-liners already in this issue.

Bundle analysis setup

// vite.config.ts
import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig(({ mode }) => ({
  plugins: [
    // ...existing plugins
    mode === 'analyze' &&
      visualizer({
        open: true,
        filename: 'bundle-analysis.html',
        gzipSize: true,
        brotliSize: true,
      }),
  ].filter(Boolean),
}))

// package.json
{
  "scripts": {
    "analyze": "vite build --mode analyze"
  }
}

Env var validation with Zod

// src/config/env.ts
import { z } from 'zod'

const envSchema = z.object({
  VITE_API_ENDPOINT: z.string().url().optional(),
  VITE_ENABLE_MOCKS: z
    .string()
    .transform((val) => val === 'true')
    .optional(),
  VITE_KEYCLOAK_URL: z.string().url().optional(),
  VITE_KEYCLOAK_REALM: z.string().optional(),
  VITE_KEYCLOAK_CLIENT_ID: z.string().optional(),
  VITE_AUTH_ENABLED: z
    .string()
    .transform((val) => val === 'true')
    .optional(),
  MODE: z.enum(['development', 'production', 'test']),
  DEV: z.boolean(),
  PROD: z.boolean(),
})

export const env = envSchema.parse({
  VITE_API_ENDPOINT: import.meta.env.VITE_API_ENDPOINT,
  VITE_ENABLE_MOCKS: import.meta.env.VITE_ENABLE_MOCKS,
  VITE_KEYCLOAK_URL: import.meta.env.VITE_KEYCLOAK_URL,
  VITE_KEYCLOAK_REALM: import.meta.env.VITE_KEYCLOAK_REALM,
  VITE_KEYCLOAK_CLIENT_ID: import.meta.env.VITE_KEYCLOAK_CLIENT_ID,
  VITE_AUTH_ENABLED: import.meta.env.VITE_AUTH_ENABLED,
  MODE: import.meta.env.MODE,
  DEV: import.meta.env.DEV,
  PROD: import.meta.env.PROD,
})

Fails fast on misconfiguration, gives type-safe access to env vars throughout the app.

TanStack Query prefetching on hover

import { useQueryClient } from '@tanstack/react-query'

function AcquisitionTable() {
  const queryClient = useQueryClient()
  const { data: acquisitions } = useGetAcquisitionsAcquisitionsGet()

  const handleRowHover = (acqId: string) => {
    queryClient.prefetchQuery({
      queryKey: getGetAcquisitionGridsQueryKey(acqId),
      queryFn: () => getAcquisitionGrids(acqId),
    })
  }

  return (
    <TableRow onMouseEnter={() => handleRowHover(acq.uuid)}>
      {/* ... */}
    </TableRow>
  )
}

Prefetches the next likely navigation target so the transition feels instant.

[vredchenko]

Re-evaluation against dashboard concept (March 2026)

The original triage of enhancements.md and the tier assignments in this issue were made when the new apps/smartem app was an empty skeleton. Now that the dashboard concept has landed (#73) with 7400+ lines of UI code, several items have escalated in priority.

Items that escalated

Item	Was	Now	Why
Custom hooks extraction	Tier 1 (abstract)	Tier 1 (urgent)	8 components exceed 250 lines with embedded state logic. Zero use*.ts files exist. AtlasMap (430 lines), SquareMap (392), PredictionsView (356) are prime candidates.
Code splitting / lazy loading	Tier 3	Tier 2	index.tsx is 1441 lines — the entire dashboard is a single component. No React.lazy or Suspense boundaries anywhere.
Loading/error state abstraction	Tier 3	Tier 2	Dashboard currently uses static mock data with zero error/loading paths. These patterns are needed before real API integration begins.
React.memo	Tier 3	Tier 2	AtlasMap, SquareMap, and PredictionsView do heavy rendering with useMemo internally but aren't memoised at the component level.

Items still correctly skipped

• Feature-based structure (TanStack Router's flat-file routing makes this unnatural)
• Storybook, PWA/offline, dark mode, Web Vitals (still premature)
• Barrel exports (still over-engineering at current scale)

New finding not in the original analysis

Mock-to-API migration: The dashboard imports static data from ~/data/mock-dashboard.ts and ~/data/mock-session-detail.ts directly — zero useQuery/useMutation calls exist. The transition to real API calls will be the forcing function for hooks extraction, error handling, and loading states. This should be treated as a prerequisite to or concurrent with tier 1/2 work.

What's going well

• TypeScript: Zero any, zero @ts-ignore, proper import type usage throughout
• Styling: Consistent MUI sx props, zero inline style={} attributes
• Performance hooks: Strategic useMemo/useCallback usage in the right places
• Accessibility: SVG icons have aria-label and role="img" attributes
• Tooling: Biome + Lefthook + OSV scanner all in place