KanaDojo かな道場

📖 About KanaDojo

KanaDojo is an engaging web-based Japanese learning platform that makes mastering Hiragana, Katakana, Kanji, and Vocabulary fun and intuitive. Built with a focus on aesthetics, customization, and effective learning, KanaDojo provides an immersive training environment for Japanese language learners at all levels.

Whether you’re just starting with the basic kana syllabaries or preparing for the JLPT exams with advanced kanji and vocabulary, KanaDojo offers a streamlined, distraction-free learning experience that adapts to your preferences and learning style.

✨ Key Features

🎯 Three Training Dojos

• Kana Dojo - Master Hiragana and Katakana syllabaries with base, dakuon, yoon, and foreign sound groups
• Kanji Dojo - Learn essential kanji characters organized by JLPT levels (N5, N4, N3, N2)
• Vocabulary Dojo - Build your Japanese vocabulary with curated word collections by proficiency level

🎮 Four Dynamic Game Modes

Each dojo supports four engaging training modes to reinforce learning:

1. Pick - Multiple choice: Select the correct romanization/translation for the shown character
2. Reverse-Pick - Reverse multiple choice: Select the correct character for the given romanization/translation
3. Input - Text input: Type the correct romanization/translation
4. Reverse-Input - Reverse text input: Type the correct character

🎨 Extensive Customization

• 100+ Themes - Choose from a vast collection of beautiful light and dark themes, or use the random theme feature
• 28 Japanese Fonts - Select from a variety of authentic Japanese typefaces to suit your aesthetic preferences
• Sound Effects - Enjoy satisfying UI feedback sounds that can be toggled on/off
• Display Options - Toggle between Romaji/English and Kana/Kanji displays in selection menus
• Hotkeys - Keyboard shortcuts for efficient training (can be disabled)

📊 Progress Tracking

• Real-time feedback with correct/incorrect counters
• Streak tracking to maintain motivation
• Statistics to monitor your learning progress

🌐 Modern Web Experience

• Fully responsive design that works on desktop, tablet, and mobile
• No installation required - train anywhere with an internet connection
• Clean, minimalist interface that keeps you focused on learning
• Smooth animations and transitions powered by Framer Motion

🖼️ Screenshots

Home Page

Kanji Selection Menu

Training Page

Customization & Themes

🎨 UI & Design Philosophy

KanaDojo embraces a minimalist aesthetic combined with maximum flexibility. The design philosophy centers around:

Minimalism First

• Clean interfaces with minimal distractions
• Focus on the learning content
• Intuitive navigation and clear information hierarchy
• Purposeful use of whitespace

Aesthetic Customization

• Extensive theme library (100+ options) ranging from soft pastels to vibrant neons
• Support for both light and dark modes
• Carefully curated color palettes that are easy on the eyes during extended study sessions
• Seamless theme transitions

User Experience

• Smooth animations and micro-interactions for delightful feedback
• Responsive design that adapts beautifully to any screen size
• Audio feedback for interactions (optional)
• Consistent visual language across all sections

Japanese Typography

• 28 authentic Japanese fonts covering various styles
• Proper rendering of complex kanji characters
• Clear distinction between similar-looking characters
• Font previews with real Japanese text samples

🛠️ Tech Stack

KanaDojo is built with modern web technologies for optimal performance and developer experience:

Core Framework

• Next.js 15 - React framework with App Router for server-side rendering and optimal performance
• React 19 - Latest React with concurrent features
• TypeScript - Type-safe development

Styling & UI

• Tailwind CSS - Utility-first CSS framework
• shadcn/ui - High-quality, accessible component library
• Framer Motion - Smooth animations and transitions
• Lucide React - Beautiful, consistent icon library
• FontAwesome - Additional icon support

State Management

• Zustand - Lightweight state management with minimal boilerplate
• Zustand Persist - Local storage persistence for user preferences

Utilities & Features

• use-sound - Audio feedback system
• canvas-confetti - Celebration effects
• react-timer-hook - Timer functionality
• react-markdown - Markdown rendering for educational content
• random-js - Cryptographically strong random number generation
• clsx + tailwind-merge - Conditional styling utilities

Development Tools

• ESLint - Code linting
• next-sitemap - Automatic sitemap generation

Analytics & Performance

• @vercel/analytics - Web analytics
• @vercel/speed-insights - Performance monitoring

🚀 Getting Started

Prerequisites

• Node.js 18.x or higher
• npm 10.x or higher (comes with Node.js)

Installation

Clone the repository

git clone https://github.com/lingdojo/kanadojo.git
cd kanadojo

Install dependencies

npm install

Run the development server

npm run dev

Open your browser Navigate to http://localhost:3000

Build for Production

# Create an optimized production build
npm run build

# Start the production server
npm start

Other Commands

# Run ESLint
npm run lint

# Generate sitemap (runs automatically after build)
npm run postbuild

Troubleshooting

If you encounter issues during development, try these solutions:

Clear Next.js Cache

macOS/Linux:

rm -rf .next
npm run dev

Windows (PowerShell):

Remove-Item -Recurse -Force .next
npm run dev

Windows (Command Prompt):

rmdir /s /q .next
npm run dev

Clear Node Modules and Reinstall

macOS/Linux:

rm -rf node_modules package-lock.json
npm install

Windows (PowerShell):

Remove-Item -Recurse -Force node_modules, package-lock.json
npm install

Windows (Command Prompt):

rmdir /s /q node_modules
del package-lock.json
npm install

Clear All Caches (Nuclear Option)

macOS/Linux:

rm -rf .next node_modules package-lock.json
npm cache clean --force
npm install
npm run dev

Windows (PowerShell):

Remove-Item -Recurse -Force .next, node_modules, package-lock.json
npm cache clean --force
npm install
npm run dev

Windows (Command Prompt):

rmdir /s /q .next
rmdir /s /q node_modules
del package-lock.json
npm cache clean --force
npm install
npm run dev

Port Already in Use

If port 3000 is already in use:

macOS/Linux:

# Find process using port 3000
lsof -i :3000

# Kill the process (replace PID with actual process ID)
kill -9 PID

Windows (PowerShell/Command Prompt):

# Find process using port 3000
netstat -ano | findstr :3000

# Kill the process (replace PID with actual process ID)
taskkill /PID PID /F

Or simply run on a different port:

# macOS/Linux/Windows
PORT=3001 npm run dev

📁 Project Structure

kanadojo/
├── app/                          # Next.js App Router pages
│   ├── kana/                    # Kana dojo pages
│   │   └── train/[gameMode]/   # Training pages for each game mode
│   ├── kanji/                   # Kanji dojo pages
│   │   └── train/[gameMode]/
│   ├── vocabulary/              # Vocabulary dojo pages
│   │   └── train/[gameMode]/
│   ├── preferences/             # Settings and customization page
│   ├── academy/                 # Educational content
│   ├── layout.tsx               # Root layout with providers
│   └── page.tsx                 # Home page
│
├── components/                   # React components
│   ├── Dojo/                    # Training-specific components
│   │   ├── Kana/               # Kana selection and cards
│   │   ├── Kanji/              # Kanji selection and cards
│   │   └── Vocab/              # Vocabulary selection and cards
│   ├── reusable/                # Shared components
│   │   ├── Menu/               # Navigation and menu components
│   │   └── ...                 # Other reusable components
│   ├── Settings/                # Preference components
│   └── ui/                      # shadcn/ui components
│
├── lib/                         # Utilities and helper functions
│   ├── hooks/                   # Custom React hooks
│   │   ├── useAudio.ts         # Audio feedback hooks
│   │   └── ...
│   ├── interfaces.ts            # TypeScript interfaces
│   └── utils.ts                 # Utility functions
│
├── i18n/                        # Translation management system
│   └── request.ts               # Translated text retrieve helper
│
├── store/                       # Zustand state management
│   ├── useKanaKanjiStore.ts    # Kana/Kanji selection state
│   ├── useVocabStore.ts        # Vocabulary selection state
│   ├── useStatsStore.ts        # Statistics and progress
│   └── useThemeStore.ts        # Theme and preferences
│
├── static/                      # Static data and configuration
│   ├── kana.ts                 # Kana character data
│   ├── kanji/                  # Kanji data by JLPT level
│   ├── vocab/                  # Vocabulary data
│   ├── themes.ts               # Theme definitions
│   ├── fonts.ts                # Font configurations
│   └── info.tsx                # Informational content
│
├── translations/               # Translated text content
│   ├── en.json                 # English text content
│   └── es.json                 # Spanish text content
│
├── public/                      # Static assets
│   ├── sounds/                 # Audio files
│   └── wallpapers/             # Background images
│
├── CLAUDE.md                    # Developer documentation
├── next.config.ts              # Next.js configuration
├── tailwind.config.js          # Tailwind CSS configuration
└── tsconfig.json               # TypeScript configuration

Key Concepts

---

State Management Flow

1. User selects content in menu components
2. Selections stored in Zustand stores (useKanaKanjiStore, useVocabStore)
3. Training components read from stores to generate questions
4. Stats tracked and persisted in useStatsStore
5. User preferences saved in useThemeStore with localStorage persistence

Component Architecture

• Dojo Components: Handle character/word selection for each content type
• Training Components: Render game modes and handle user interactions
• Reusable Components: Shared UI elements (buttons, cards, modals, etc.)
• Menu Components: Navigation, info sections, and dojo selection

Data Organization

• Kana: Organized by type (hiragana/katakana) and groups (base, dakuon, yoon, foreign)
• Kanji: Organized by JLPT level (N5-N2), with readings and meanings
• Vocabulary: Organized by JLPT level and word type (nouns, verbs, etc.)

Game Mode Implementation

Each game mode is a dynamic route (/[contentType]/train/[gameMode]) that:

1. Reads selected content from the appropriate store
2. Generates random questions from the selection
3. Provides immediate feedback
4. Tracks statistics (correct, incorrect, streak)

🤝 Contributing

Contributions are welcome! KanaDojo is an open-source project built by the community, for the community. Check out CONTRIBUTING.md for more detailed information on how to contribute.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Follow the existing code style and conventions
• Use TypeScript for type safety
• Test your changes thoroughly
• Update documentation as needed
• Keep components focused and reusable

📄 License

This project is licensed under the AGPL 3.0 License - see the LICENSE.md file for details.

🙏 Acknowledgments

• Japanese language data and character information
• Open-source community for the amazing tools and libraries
• All contributors who help make KanaDojo better

Translations

KanaDojo is available in multiple languages thanks to community contributions:

• English (default)
• Español
• Français in progress
• Deutsch
• Português
• Türkçe
• 中文（简体）
• 中文（繁體）
• हिन्दी
• العربية

📞 Contact & Links

• Website: kanadojo.com
• Repository: github.com/lingdojo/kanadojo
• Email: lingdojo.dev@gmail.com

---

Made with ❤️ for Japanese language learners worldwide

がんばって！ (Ganbatte! - Do your best!)

⬆ Back to top