Fix theme hydration warnings caused by mismatched server/client theme state

[grantfox-oss]

Description

Theme pages are currently emitting hydration warnings because the theme state differs between server render and client render. This is caused by an incomplete next-themes configuration in theme-provider.tsx, which allows the client to rehydrate with a different theme value than the server initially rendered.

This issue should stabilize theme initialization so the app renders the same theme on the server and client, and avoid a visible flash of theme change during hydration.

---

Tasks

• Update theme-provider.tsx
• Configure next-themes with:
  • defaultTheme
  • enableSystem
  • attribute="class"
  • disableTransitionOnChange or equivalent transition suppression
• Ensure the provider uses a consistent initial theme value for both server and client
• Apply the theme preference as early as possible on first client render
• Verify the theme provider is wrapped around all theme pages and not rendered conditionally
• If needed, add a safe mount guard or hydration-safe rendering pattern to keep theme DOM stable until the client theme is resolved

---

Implementation details

The provider should stop relying on implicit defaults and explicitly define the initial theme strategy. For example:

'use client'

import { ThemeProvider as NextThemesProvider } from 'next-themes'
import type { ThemeProviderProps } from 'next-themes/dist/types'

export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
  return (
    <NextThemesProvider
      {...props}
      attribute="class"
      defaultTheme="system"
      enableSystem
      disableTransitionOnChange
    >
      {children}
    </NextThemesProvider>
  )
}

Key behavior to lock in

• attribute="class" ensures theme is controlled via CSS class rather than inline styles
• defaultTheme defines a stable initial server-side theme
• enableSystem lets the browser preference apply consistently
• disableTransitionOnChange prevents a flash when the theme switches after hydration
• If defaultTheme="system" is used, the provider must still avoid theme mismatch flash by applying the preference in a hydration-safe way

---

Acceptance criteria

• next-themes is explicitly configured with defaultTheme and enableSystem
• Theme rendering is stable across server and client
• No hydration warnings appear in the browser console on theme pages
• The visible theme does not flash or jump during first render
• Theme pages render the same initial theme class before and after hydration
• The provider is implemented in theme-provider.tsx with a consistent theme initialization strategy

---

Why this matters

• Hydration warnings indicate a mismatch between server-generated HTML and client-side React state
• Theme mismatch can cause a visible flash and degrade perceived quality
• A stable theme provider improves user experience and prevents inconsistent appearance across renders

[mubking]

Please I would like to work on this issue

[mubking]

Please I would like to work on this issue

[mubking]

Please I would like to work on this issue

[adelekevictor12]

I will love to handle this issue

[EbukaMoses]

Hello Maintainer,

I’d like to apply to work on this issue.

I’m Ebuka Moses, a full-stack and blockchain developer with experience building, testing, and maintaining smart contracts, particularly using Rust and blockchain-based architectures. I’m comfortable working with contract logic, validation, access control, persistent storage, and event handling, and I always pay close attention to correctness, security, and edge cases.

I take time to fully understand the issue requirements before implementing a solution, and I ensure my work follows the project’s coding standards. I also write clear, well-tested code and submit clean pull requests with meaningful commits.

I’m confident I can deliver a solid solution that meets the acceptance criteria and adds value to the project.

Thank you for your consideration, and I look forward to contributing.

[DevSolex]

Hi Maintainer,

I’m a smart contract and full-stack developer and would love to contribute to this issue. I’m an experienced contributor with hands-on expertise in Rust, Soroban, Cairo, and TypeScript.

I’m passionate about building secure, scalable blockchain solutions, with a strong emphasis on writing clean and maintainable code. Based on the scope of this issue, I’m confident I can deliver a complete solution within 24 hours of assignment.

I’d greatly appreciate the opportunity to contribute and help move this forward.

[Menjay7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[jaynomyaro]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[elizabetheonoja-art]

Hi maintainer, i am a fullstack developer with experience years of experience. Kindly assign me this issue, i can deliver the pr in 2hrs

[grantfox-oss]

🦊 GrantFox — @elizabetheonoja-art has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #79)
2. Your PR will be reviewed by the aid-linkk maintainers

Good luck! Track your progress on GrantFox.