A modern, professional React-based name generator web application with multi-language support, interactive wizard flow, and beautiful dark theme design. Built with Vite for lightning-fast development and optimal performance.
NameCraft is a frontend-only React application that provides a sophisticated name generation experience. The backend and AI API integration will be developed separately by the backend team.
- π Multi-Language Support: 9 languages (English, Arabic, Spanish, French, Russian, German, Japanese, Chinese, Hindi)
- π¨ Professional Dark Theme: Premium glassmorphism design with smooth animations
- π Interactive Wizard Flow: Step-by-step name generation process
- π― Cultural Diversity: 15+ cultural origins and name styles
- π« Modern UI/UX: Responsive design with Framer Motion animations
- π± Mobile-First: Optimized for all devices and screen sizes
- β‘ Performance: Optimized with React Query, Zustand, and Vite
- π Fast Development: Hot Module Replacement (HMR) with Vite
- React 18 with modern hooks
- Vite 6 - Lightning-fast build tool and dev server
- Tailwind CSS for styling
- Framer Motion for animations
- Zustand for state management
- React Query for data fetching
- Headless UI for accessible components
client/
βββ src/
β βββ components/ # UI Components
β β βββ LandingPage.js # Welcome screen with language selection
β β βββ GenderSelection.js # Gender selection wizard step
β β βββ RegionSelection.js # Cultural origin selection
β β βββ FeelingSelection.js # Name feeling/emotion selection
β β βββ NameForm.js # Summary and generation form
β β βββ NameDisplay.js # Results display with loading states
β β βββ NameCard.js # Individual name card component
β β βββ ui/ # Reusable UI components
β βββ store/
β β βββ useNameStore.js # Zustand state management
β βββ hooks/
β β βββ useNameGenerator.js # Data fetching hooks
β βββ data/
β βββ mockNames.js # Mock data for development
βββ index.html # Vite entry point
βββ vite.config.js # Vite configuration
βββ vitest.config.js # Testing configuration
βββ package.json # Dependencies and scripts
- Node.js 20.19+ (required for Vite 6)
- npm, yarn, pnpm, or bun
# Navigate to client directory
cd client
# Install dependencies
npm install
# Start development server
npm run dev
The application will run on http://localhost:3000
with lightning-fast Hot Module Replacement (HMR).
npm run dev # Start development server with HMR
npm run build # Build for production
npm run preview # Preview production build locally
npm run test # Run tests with Vitest
npm run lint # Lint code with ESLint
The frontend expects the following backend API endpoints:
POST /api/generate-names
Content-Type: application/json
{
"gender": "male|female|unisex",
"culture": "arabic|islamic|asian|western|jewish|african|global|latin|north-american|european|slavic|scandinavian|oceanic|korean|japanese",
"count": 1-10,
"feeling": "unique|strong|beautiful|wise|peaceful|brave|gentle|mysterious|joyful|noble|creative|adventurous|loving|spiritual|modern"
}
Response:
{
"success": true,
"names": [
{
"name": "Ahmad",
"meaning": "Most commendable, most praiseworthy",
"origin": "Arabic",
"feeling": "noble"
}
]
}
GET /api/cultures
GET /api/genders
GET /api/feelings
Response:
{
"success": true,
"data": ["arabic", "islamic", "asian", "western", ...]
}
The frontend is configured to connect to:
- Development:
http://localhost:3001/api
(viaVITE_API_URL
environment variable) - Production: Environment variable
VITE_API_URL
# Development environment
VITE_APP_NAME=NameCraft
VITE_APP_VERSION=1.0.0
VITE_API_URL=http://localhost:3001/api
VITE_DEV_MODE=true
VITE_ENABLE_MOCK_DATA=true
Currently, the application uses mock data from client/src/data/mockNames.js
for development and demonstration purposes. Replace this with actual API calls when the backend is ready.
- Primary: Purple gradient (
#7c6ef2
to#8b5cf6
) - Accent: Purple, Pink, Emerald, Orange
- Background: Dark theme (
#0a0f1a
to#1a1f2e
)
- Font: Inter (Google Fonts)
- Responsive: Dynamic font sizing with
clamp()
- Multi-language: Optimized for RTL and LTR languages
- Glassmorphism: Backdrop blur effects
- Animations: Smooth transitions with Framer Motion
- Accessibility: ARIA labels and keyboard navigation
The application supports 9 languages with complete translations:
- English (en)
- Arabic (ar) - RTL support
- Spanish (es)
- French (fr)
- Russian (ru)
- German (de)
- Japanese (ja)
- Chinese (zh)
- Hindi (hi)
All UI text, error messages, and dynamic content are translated.
- Mobile: 320px - 768px
- Tablet: 768px - 1024px
- Desktop: 1024px+
Optimized for touch interactions and various screen sizes.
- Zustand: Global state for user preferences and wizard flow
- React Query: Server state management and caching
- Local Storage: Persistence for user settings
- ESLint: Code linting
- Prettier: Code formatting
- Tailwind: Utility-first CSS
- Vitest: Fast unit testing
- React Testing Library: Component testing
- jsdom: DOM environment for tests
cd client
npm run build
The built files will be in client/dist/
directory.
VITE_API_URL=https://your-api-domain.com/api
- API Design: Follow the expected endpoints above
- CORS: Enable CORS for
http://localhost:3000
- Error Handling: Return consistent error responses
- Validation: Validate all input parameters
- Documentation: Document your API endpoints
- Set up your backend server on port 3001
- Implement the required API endpoints
- Test with the frontend application
- Replace mock data with real API calls
- Deploy both frontend and backend
This project is licensed under the MIT License - see the LICENSE file for details.
Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.
Note: This is a frontend-only repository. The backend and AI API integration will be developed separately and integrated via the specified API endpoints.