Skip to main content

JTI Docusaurus Template – Project Health Report

Last updated: 2026-03-04

1) Project Summary​

This repository is a Docusaurus v3 template customized for JTI with:

  • React + TypeScript based site customization.
  • Optional Azure AD authentication and group-based authorization through MSAL.
  • Optional Azure Static Web Apps (SWA) route-level protection.
  • Optional Azure Application Insights integration.
  • Local search indexing via @easyops-cn/docusaurus-search-local.

2) Architecture Overview​

Core runtime flow​

  • src/theme/Root.tsx is the integration entry point for:
    • Content Security Policy header injection.
    • MSAL bootstrap and provider wiring.
    • AuthN/AuthZ gating and conditional rendering.
    • App Insights initialization and user context setup.

Authentication modules​

  • src/authentication/authConfig.ts
    • Defines shared MSAL runtime configuration and logger behavior.
  • src/authentication/auth.ts
    • Creates the MSAL public client app.
    • Handles login redirect lifecycle.
    • Resolves user identity from MSAL and/or SWA /.auth/me.
    • Implements group authorization checks.
    • Exposes acquireAccessToken() for future API integrations.

Observability​

  • src/services/appInsights.ts
    • Lazy-loads ApplicationInsights singleton.
    • Applies authenticated user context once available.

3) Configuration Surface​

Build/runtime config​

  • docusaurus.config.ts
    • Controls Docusaurus settings, i18n, navbar/footer, search plugin, and auth feature flags.
    • Uses environment values via dotenv in customFields.

Azure SWA security​

  • staticwebapp.config.json
    • Restricts all routes to authenticated role.
    • Redirects unauthorized requests to Azure AD login.

NPM scripts (operational)​

  • npm run start – local development (runs lint + dev server)
  • npm run lint – ESLint auto-fix across src
  • npm run build – production build (includes prebuild lint)
  • npm run serve – serves built output for validation/search testing

4) React Doctor Analysis​

Command used​

npx -y react-doctor@latest . --verbose --diff

Result snapshot​

  • Score: 94/100 (Great)
  • Findings: 1 error, 16 warnings, across 9/14 scanned files
  • Scan context: full scan (no diff/feature branch context detected)

High-priority finding (Error)​

  1. Missing image alt attribute
    • File: src/components/HomepageFeatures/index.tsx
    • Impact: accessibility violation and lint failure risk
    • Recommendation: add alt text (or alt="" if decorative)

Notable warnings​

  1. Array index used as React key

    • File: src/components/HomepageFeatures/index.tsx
    • Recommendation: use stable key based on item identity (e.g., title/slug/id).

  2. Large component size

    • File: src/pages/token-test.tsx (~363 lines)
    • Recommendation: split into focused presentational subcomponents (TokenHeader, TokenResult, TroubleshootingPanel, etc.).

  3. useEffect complexity and state updates

    • File: src/theme/Root.tsx
    • Recommendation: reduce effect branching and consider a reducer/state-machine style for auth init transitions.

  4. Unused-file warnings likely influenced by framework conventions

    • Reported files include:
      • src/theme/Root.tsx
      • src/components/Loading/index.tsx
      • src/services/appInsights.ts
    • Note: In Docusaurus, theme override files can be resolved by convention and may appear “unused” to generic static analyzers.

5) Risk & Quality Notes​

  • Accessibility: one concrete gap (img alt attribute) should be fixed immediately.
  • Maintainability: auth orchestration in Root.tsx is functional but dense; medium-term simplification would lower regression risk.
  • Performance/readability: token test page is currently a useful diagnostics tool but would benefit from decomposition.
  • Tooling interpretation: treat “unused” findings carefully where framework-level auto-discovery applies.

6) Prioritized Remediation Plan​

  1. Immediate (today)

    • Add missing alt attribute in HomepageFeatures.
    • Replace index-based list key with stable key.

  2. Short term (this sprint)

    • Refactor token-test.tsx into smaller components without changing behavior.
    • Simplify Root.tsx auth initialization path; reduce side-effect branching.

  3. Medium term (next sprint)

    • Add a lightweight architectural note for auth flow transitions.
    • Add targeted tests around auth-init and authorization-gate rendering behavior.

7) Operational Guidance​

  • Re-run quality scan after each significant React/auth change:
npx -y react-doctor@latest . --verbose --diff
  • For build confidence before release:
npm run lint
npm run build
npm run serve

8) Conclusion​

The template is in a strong state overall (94/100) with one clear accessibility defect and a small set of maintainability opportunities. The authentication foundation is robust and supports multiple deployment/auth strategies; the next quality gains come from targeted cleanup in UI accessibility and auth/page component structure.