Skip to content

Toseef-Ahmad/interections

Repository files navigation

Interections

A collection of free online interactive calculators and math tools built with React. Features Pascal's Triangle Calculator, Matrix Calculator, Mechanical Calculator, and more. All tools include step-by-step solutions, visual feedback, and educational resources. Perfect for students, teachers, and professionals.

Popular Tools:

  • 🧮 Mechanical Gear Calculator
  • 📐 Matrix Calculator (coming soon)
  • 🔺 Pascal's Triangle Calculator (coming soon)
  • 🔢 And many more interactive math tools!

Deployed on GitHub Pages with full SEO optimization.

🚀 Quick Start

Prerequisites

  • Node.js (v18 or higher)
  • npm or yarn

Installation

  1. Clone the repository:
git clone <your-repo-url>
cd interections
  1. Install dependencies:
npm install
  1. Start development server:
npm start

The app will open at http://localhost:3000

📁 Project Structure

interections/
├── src/
│   ├── pages/              # Individual page components
│   │   ├── ExamplePage.js  # Example component
│   │   └── index.js        # Pages registry
│   ├── App.js              # Main app with routing
│   ├── App.css             # App styles
│   ├── index.js            # Entry point
│   └── index.css           # Global styles
├── public/                 # Public assets
├── scripts/
│   ├── create-page.js      # Script to create new pages
│   └── clean.js            # Clean build artifacts
├── .github/
│   └── workflows/
│       └── deploy.yml      # GitHub Actions deployment
└── package.json

➕ Adding a New Interactive Tool

📚 Complete Guide

👉 See PAGE_CREATION_GUIDE.md for the complete guide covering:

  • Step-by-step page creation (script & manual methods)
  • SEO best practices and metadata requirements
  • Naming conventions and file structure
  • Content guidelines and examples
  • Testing and deployment procedures

Quick Start

npm run create:page your-tool-name

This automatically:

  • ✅ Creates the component file
  • ✅ Registers it in routing
  • ✅ Sets up basic SEO metadata
  • ✅ Generates the correct URL structure

Popular Tools to Build

See INTERACTIVE_TOOLS_GUIDE.md for:

  • Popular tool categories (Calculators, Visualizations, Linear Algebra, etc.)
  • SEO-friendly description templates
  • Popular keywords to target
  • Examples: Pascal's Triangle, Matrix Inverse, etc.

🛠️ Development

Running Locally

npm start

Visit http://localhost:3000 to see the home page with all components listed.

Visit http://localhost:3000/xyz to see a specific component.

Building for Production

npm run build

This creates an optimized production build in the build/ directory.

Cleaning Build Artifacts

npm run clean

📦 Deployment

Automatic Deployment (GitHub Actions)

The repository is configured with GitHub Actions to automatically deploy to GitHub Pages when you push to the main branch.

Setup Steps:

  1. Go to your repository on GitHub
  2. Navigate to SettingsPages
  3. Under Source, select GitHub Actions
  4. Update homepage in package.json to match your repo name:
    {
      "homepage": "/your-repo-name"
    }
  5. Push your changes to the main branch
  6. The workflow will automatically build and deploy your app

Manual Deployment

If you prefer to deploy manually:

npm run build
npm run deploy

Note: Make sure you have gh-pages installed and configured with your GitHub credentials.

🔧 Configuration

GitHub Pages Base Path

Update the homepage field in package.json to match your GitHub repository name:

{
  "homepage": "/your-repo-name"
}

This ensures all routes work correctly on GitHub Pages.

📝 Available Scripts

Command Description
npm start Start development server
npm run build Build for production
npm test Run tests
npm run create:page <name> Create a new page component
npm run clean Remove build artifacts
npm run deploy Deploy to GitHub Pages (manual)

🎯 How It Works

  • Single React App: One React application with React Router
  • Multiple Pages: Each page is a single React component in src/pages/
  • Automatic Routing: Pages are automatically registered and routed
  • Home Page: Lists all available components with links
  • Unique URLs: Each component has its own URL like /xyz, /abc, etc.

📄 Example: Creating the "xyz" Component

npm run create:page xyz

This creates:

  • src/pages/XyzPage.js - Your component file
  • Registers it at route /xyz
  • Makes it appear on the home page

Then edit src/pages/XyzPage.js to add your interactive component code!

🐛 Troubleshooting

Routes Not Working on GitHub Pages

  • Make sure homepage in package.json matches your repo name
  • Ensure you're using BrowserRouter with basename (already configured)
  • Check that GitHub Pages is set to use GitHub Actions as the source

Component Not Appearing

  • Make sure the component is registered in src/pages/index.js
  • Check that the component name matches the route (kebab-case)
  • Restart the dev server after adding new pages

📄 License

GPL-2.0

🤝 Contributing

Feel free to add new interactive components! Each component should be self-contained and independent.