🎯 Vocaply

Master Your Vocabulary, One Word at a Time

Features • Live Demo • Tech Stack • Getting Started • Structure • Contributing

🌟 Overview

Vocaply is a modern, feature-rich vocabulary learning application designed to help users expand their English vocabulary through personalized daily word selections, progress tracking, and interactive learning experiences. Built with React and Firebase, it offers a seamless, responsive experience across all devices.

🌐 Live Demo

Experience Vocaply now! No installation required.

👉 https://vocaply.web.app/

Feature	Description
🔐 Authentication	Sign up/Login with Email or Google
📚 Word Learning	Daily personalized vocabulary selections
📊 Progress Tracking	Track your learning journey with stats
⭐ Favorites	Save words you want to remember
📱 Responsive	Works perfectly on mobile, tablet & desktop

✨ Features

🎯 Core Features

Feature	Description
Daily Words	Get personalized word selections every day
Smart Progress Tracking	Visual stats showing your learning journey
Favorites System	Star and save words for quick review
Streak Counter	Stay motivated with daily learning streaks
Word Details	Meanings, examples, and pronunciations

🔐 Authentication & Security

Feature	Description
Email/Password	Traditional secure authentication
Google Sign-In	One-click Google authentication
Protected Routes	Secure access to user-specific data
Firestore Rules	Server-side data protection

🎨 User Experience

Feature	Description
Modern UI	Clean, premium glassmorphism design
Dark Mode Ready	Easy on the eyes
Micro-animations	Smooth, engaging interactions
Responsive Design	Perfect on any screen size

🛠️ Tech Stack

Frontend

Technology	Purpose
React 18	UI Component Library
Vite	Build Tool & Dev Server
Tailwind CSS	Utility-First Styling
Framer Motion	Animations & Transitions
React Router v6	Client-Side Routing
Lucide React	Modern Icon Library

Backend & Services

Technology	Purpose
Firebase Auth	User Authentication
Cloud Firestore	NoSQL Database
Firebase Hosting	Production Deployment
Cloud Functions	Serverless Backend Logic

Development Tools

Tool	Purpose
ESLint	Code Linting
Prettier	Code Formatting
Git	Version Control

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Check Command
Node.js	18.x or higher	`node --version`
npm	9.x or higher	`npm --version`
Git	Latest	`git --version`

Installation

Step 1: Clone the Repository

git clone https://github.com/mdjameee400/vocaply.git
cd vocaply

Step 2: Install Dependencies

npm install

Step 3: Environment Setup

Create your environment file by copying the example:

# Windows (Command Prompt)
copy .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env

# macOS / Linux
cp .env.example .env

Step 4: Configure Firebase

Go to Firebase Console
Create a new project or use existing one
Enable Authentication (Email/Password & Google)
Create a Firestore Database
Go to Project Settings → General → Your Apps → Web App
Copy the config values to your .env file:

VITE_FIREBASE_API_KEY=your_api_key_here
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id
VITE_FIREBASE_MEASUREMENT_ID=G-XXXXXXXXXX

Step 5: Run Development Server

npm run dev

🎉 Open http://localhost:5173 in your browser!

📁 Project Structure

vocaply/
├── 📂 public/                    # Static assets
│   ├── logo.png                  # App logo
│   └── ...
│
├── 📂 src/                       # Source code
│   ├── 📂 components/            # Reusable UI components
│   │   ├── 📂 Dashboard/         # Dashboard-specific components
│   │   │   ├── TodaysWords.jsx   # Daily word display
│   │   │   ├── WordList.jsx      # Word listing
│   │   │   └── ...
│   │   ├── 📂 Layout/            # Layout components
│   │   │   ├── Navbar.jsx        # Navigation bar
│   │   │   ├── Sidebar.jsx       # Side navigation
│   │   │   └── ...
│   │   └── 📂 ui/                # Base UI components
│   │
│   ├── 📂 context/               # React Context providers
│   │   └── AuthContext.jsx       # Authentication state
│   │
│   ├── 📂 firebase/              # Firebase configuration
│   │   └── config.js             # Firebase initialization
│   │
│   ├── 📂 hooks/                 # Custom React hooks
│   │   └── useVocabulary.js      # Vocabulary data hook
│   │
│   ├── 📂 pages/                 # Page components
│   │   ├── Home.jsx              # Landing page
│   │   ├── Dashboard.jsx         # User dashboard
│   │   ├── Login.jsx             # Authentication page
│   │   ├── Progress.jsx          # Progress tracking
│   │   └── ...
│   │
│   ├── App.jsx                   # Main app component
│   ├── main.jsx                  # App entry point
│   └── index.css                 # Global styles
│
├── 📂 functions/                 # Firebase Cloud Functions
│   └── index.js                  # Serverless functions
│
├── 📄 .env.example               # Environment template
├── 📄 .gitignore                 # Git ignore rules
├── 📄 firebase.json              # Firebase config
├── 📄 firestore.rules            # Database security rules
├── 📄 package.json               # Dependencies
├── 📄 tailwind.config.js         # Tailwind configuration
├── 📄 vite.config.js             # Vite configuration
└── 📄 README.md                  # This file

📜 Available Scripts

Command	Description
`npm run dev`	Start development server at `localhost:5173`
`npm run build`	Create production build in `dist/` folder
`npm run preview`	Preview production build locally
`npm run lint`	Run ESLint for code quality

Firebase Commands

Command	Description
`firebase login`	Authenticate with Firebase CLI
`firebase deploy`	Deploy everything (hosting, rules, functions)
`firebase deploy --only hosting`	Deploy only website changes

💡 Quick Tip: To update your live link manually, always run npm run build first, then firebase deploy --only hosting.

🌍 Continuous Deployment (CI/CD)

To keep your live link automatically updated every time you push code to GitHub, follow these steps:

1. Initialize Firebase GitHub Action

Run this command in your terminal and follow the prompts:

firebase init hosting:github

For "For which GitHub repository?": Enter mdjameee400/vocaply
For "Set up a workflow to run a build script before every deploy?": Yes
For "What script should be run before every deploy?": npm ci && npm run build
For "Set up automatic deployment to your site's live channel when a PR is merged?": Yes
For "What is the name of the GitHub branch associated with your site's live channel?": main

2. How it works

Once set up, Firebase will create a file in .github/workflows/. Now, whenever you run:

git add .
git commit -m "Your changes"
git push origin main

GitHub will automatically build your app and deploy it to https://vocaply.web.app/. You don't have to run the deploy command manually anymore!

🔐 Security

Environment Variables

All sensitive credentials are stored in .env files which are NOT committed to the repository.

File	Purpose	Git Status
`.env`	Your actual credentials	🔐 Ignored
`.env.example`	Template for others	✅ Committed

Firestore Security Rules

Our database is protected with security rules that ensure:

✅ Users can only access their own data
✅ Authentication is required for all operations
✅ Data validation on write operations

// Example rule structure
match /users/{userId} {
  allow read, write: if request.auth != null && request.auth.uid == userId;
}

🤝 Contributing

We welcome contributions! Here's how you can help:

Step 1: Fork the Repository

Click the "Fork" button at the top right of this page.

Step 2: Clone Your Fork

git clone https://github.com/YOUR_USERNAME/vocaply.git
cd vocaply

Step 3: Create a Branch

git checkout -b feature/your-feature-name

Step 4: Make Changes

Make your changes and test them locally.

Step 5: Commit & Push

git add .
git commit -m "Add: your feature description"
git push origin feature/your-feature-name

Step 6: Open a Pull Request

Go to the original repository and click "New Pull Request".

📋 Roadmap

Feature	Status
✅ User Authentication	Complete
✅ Daily Word Selection	Complete
✅ Progress Tracking	Complete
✅ Favorites System	Complete
🔄 Chrome Extension	In Progress
📋 Spaced Repetition	Planned
📋 AI Word Recommendations	Planned
📋 Multi-language Support	Planned

🐛 Troubleshooting

Common Issues

❌ "Firebase API Key is missing or invalid"

Check if .env file exists in root directory
Verify all VITE_FIREBASE_* variables have values
Restart the development server: npm run dev
Make sure there are no extra spaces in your .env file

❌ "npm install" fails

Delete node_modules folder and package-lock.json
Clear npm cache: npm cache clean --force
Run npm install again

❌ Page shows blank after login

Check browser console for errors (F12)
Verify Firestore rules are deployed
Check if user document exists in Firestore

❌ Environment variables not working

Variables must start with VITE_ for Vite
Restart dev server after changing .env
Check for typos in variable names

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2026 Vocaply

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

👨‍💻 Author

MD Jamee

🙏 Acknowledgments

Firebase - Backend services
React - UI framework
Tailwind CSS - Styling
Lucide Icons - Beautiful icons
Framer Motion - Animations

⭐ If you found this project helpful, please give it a star!

Made with ❤️ for vocabulary learners everywhere

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
functions		functions
public		public
scripts		scripts
src		src
.env.example		.env.example
.firebaserc		.firebaserc
.gitignore		.gitignore
PROJECT_KEYS.md		PROJECT_KEYS.md
README.md		README.md
components.json		components.json
eslint.config.js		eslint.config.js
firebase.json		firebase.json
firestore.rules		firestore.rules
index.html		index.html
jsconfig.json		jsconfig.json
package-lock.json		package-lock.json
package.json		package.json
tailwind.config.js		tailwind.config.js
vite.config.js		vite.config.js

Folders and files

Latest commit

History

Repository files navigation

🎯 Vocaply

🌟 Overview

🌐 Live Demo

👉 https://vocaply.web.app/

✨ Features

🎯 Core Features

🔐 Authentication & Security

🎨 User Experience

🛠️ Tech Stack

Frontend

Backend & Services

Development Tools

🚀 Getting Started

Prerequisites

Installation

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Environment Setup

Step 4: Configure Firebase

Step 5: Run Development Server

📁 Project Structure

📜 Available Scripts

Firebase Commands

🌍 Continuous Deployment (CI/CD)

1. Initialize Firebase GitHub Action

2. How it works

🔐 Security

Environment Variables

Firestore Security Rules

🤝 Contributing

Step 1: Fork the Repository

Step 2: Clone Your Fork

Step 3: Create a Branch

Step 4: Make Changes

Step 5: Commit & Push

Step 6: Open a Pull Request

📋 Roadmap

🐛 Troubleshooting

Common Issues

📄 License

👨‍💻 Author

🙏 Acknowledgments

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages