A modern full-stack React application that delivers random Chuck Norris facts and provides search functionality by text or category. Built with a GraphQL API backend and Apollo Client for seamless state management and data fetching.
Experience Chuck Norris facts like never before: https://chuck-norris-facts-kwk.vercel.app/
- 🎲 Random Facts: Get entertaining Chuck Norris facts with a single click
- 🔍 Smart Search: Search facts by text content or browse by categories
- 🌙 Persistent Dark Mode: Toggle between light and dark themes with localStorage persistence
- 📱 Fully Responsive: Optimized for all device sizes and screen resolutions
- ⚡ GraphQL Integration: Efficient data fetching with Apollo Client
- 🎨 Modern UI: Clean, intuitive interface built with Tailwind CSS
- 🔧 TypeScript Support: Type-safe development with full TypeScript integration
This project follows a modern full-stack architecture:
- React 18 with TypeScript for type safety
- Apollo Client for GraphQL state management
- Tailwind CSS for responsive styling
- Lucide React for beautiful icons
- Node.js with Express framework
- GraphQL API with express-graphql
- TypeScript for server-side type safety
- Axios for external API integration
- Helmet and CORS for security
| Package | Version | Purpose |
|---|---|---|
| React | ^18.3.1 | UI Library |
| Apollo Client | ^3.10.5 | GraphQL Client |
| TypeScript | ^4.9.5 | Type Safety |
| Tailwind CSS | ^3.4.4 | Styling Framework |
| Lucide React | ^0.539.0 | Icon Library |
| Package | Version | Purpose |
|---|---|---|
| Express | ^4.19.2 | Web Framework |
| GraphQL | ^16.11.0 | Query Language |
| Apollo Server | ^4.0.0 | GraphQL Server |
| Axios | ^1.7.2 | HTTP Client |
| TypeScript | ^5.4.5 | Type Safety |
- Node.js (v16 or higher)
- npm or yarn package manager
# Clone the repository
git clone https://github.com/your-username/chuck-norris-facts.git
cd chuck-norris-facts# Navigate to server directory
cd server
# Install dependencies
npm install
# Create environment file
cp .env.example .env
# Start development server
npm startThe GraphQL server will be available at http://localhost:4000/graphql
# Navigate to client directory (in a new terminal)
cd client
# Install dependencies
npm install
# Start React development server
npm startThe React app will be available at http://localhost:3000
| Command | Description |
|---|---|
npm start |
Runs the React app in development mode |
npm run build |
Builds the app for production |
npm test |
Launches the test runner |
npm run cypress:open |
Opens Cypress for e2e testing |
npm run cypress:run |
Runs Cypress tests in headless mode |
| Command | Description |
|---|---|
npm start |
Starts the GraphQL server with hot reload |
npm test |
Runs server-side tests |
chuck-norris-facts/
├── client/ # Frontend React application
│ ├── public/
│ │ ├── index.html
│ │ └── screenshot.png
│ ├── src/
│ │ ├── components/
│ │ │ ├── DarkModeButton/
│ │ │ ├── DarkModeButton.tsx
│ │ │ └── useDarkModeButton.tsx
│ │ │ ├── Footer/
│ │ │ ├── Footer.tsx
│ │ │ └── useFooter.ts
│ │ │ ├── Header/
│ │ │ ├── Header.tsx
│ │ │ └── useHeader.ts
│ │ │ ├── Modal/
│ │ │ ├── Modal.tsx
│ │ │ └── useModal.ts
│ │ │ └── SearchByCategorySection/
│ │ │ ├── SearchByCategorySection.tsx
│ │ │ └── useSearchByCategorySection.ts
│ │ ├── assets/
│ │ │ └── images/
│ │ ├── pages/
│ │ │ ├── Categories/
│ │ │ ├── Categories.tsx
│ │ │ └── useCategories.ts
│ │ │ ├── FactByFreeText/
│ │ │ ├── FactByFreeText.tsx
│ │ │ └── useFactByFreeText.ts
│ │ │ └── RandomFact/
│ │ │ ├── RandomFact.tsx
│ │ │ └── useRandomFact.ts
│ │ ├── queries/
│ │ │ ├── getChuckNorrisByCategories.ts
│ │ │ ├── getChuckNorrisByText.ts
│ │ │ ├── getChuckNorrisCategories.ts
│ │ │ └── getChuckNorrisFact.ts
│ │ ├── types/
│ │ │ └── types.ts
│ │ ├── utils/
│ │ │ ├── apolloClient.ts
│ │ │ ├── useModal.ts
│ │ ├── App.test.tsx
│ │ ├── App.tsx
│ │ ├── index.css
│ │ ├── index.tsx
│ │ ├── react-app-env.d.ts
│ │ ├── reportWebVitals.ts
│ │ └── setupTests.ts
│ ├── package.json
│ ├── Dockerfile
│ └── tailwind.config.js
├── server/
│ ├── src/
│ │ ├── graphql/
│ │ │ ├── resolvers/
│ │ │ └── index.ts
│ │ │ ├── schema/
│ │ │ └── index.ts
│ │ ├── middlewares/
│ │ │ └── errorHandler.ts
│ │ ├── utils/
│ │ │ ├── apiClient.ts
│ │ │ ├── logger.ts
│ │ │ ├── types.ts
│ │ └── index.ts
│ ├── package.json
│ ├── Dockerfile
│ ├── jest.config.ts
│ └── .env.example
├── docker-compose.yml
└── README.md
Create a .env file in the server directory:
PORT=4000
CHUCK_NORRIS_API_URL=https://api.chucknorris.io
NODE_ENV=developmenttype Fact {
id: ID!
value: String!
url: String!
categories: [String!]!
created_at: String!
updated_at: String!
}
type Query {
randomFact: Fact!
searchFacts(query: String!): [Fact!]!
factsByCategory(category: String!): [Fact!]!
categories: [String!]!
}cd client
# Run unit tests
npm test
# Run e2e tests
npm run cypress:opencd server
# Run server tests
npm testThe frontend is automatically deployed to Vercel on every push to main branch.
Configure your preferred hosting platform with the following settings:
- Build Command:
npm run build - Start Command:
npm start - Node Version: 18+
- Helmet.js: Security headers protection
- CORS: Cross-origin resource sharing configuration
- Input Validation: GraphQL schema validation
- Environment Variables: Sensitive data protection
- Primary Colors: Tailwind's blue and gray palette
- Dark Mode: Persistent theme switching
- Typography: Inter font family
- Spacing: Consistent 8px grid system
- Animations: Smooth transitions and hover effects
We welcome contributions! Please follow these steps:
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
- Use TypeScript for all new code
- Follow ESLint configuration
- Write tests for new features
- Update documentation as needed
This project is licensed under the MIT License - see the LICENSE file for details.
- Chuck Norris API for providing the facts data
- Apollo GraphQL for excellent GraphQL tools
- Tailwind CSS for the utility-first CSS framework
Joseph Kawe
- GitHub: https://github.com/dev-kohako
- LinkedIn: https://www.linkedin.com/in/josephkawe/
- Email: josephkawe000@gmail.com
🥋 Made with ❤️ and a roundhouse kick by Joseph Kawe
⭐ Star this repository if Chuck Norris would approve!
"Chuck Norris doesn't need a README, but his code does."