@eschatons/edu-tools

🎓 Educational Tools Library - Complete Guide

A zero-config, auto-discovery system for creating and publishing educational React components.

🚀 Quick Start (3 Steps)

For Users - Installing the Library

npm install @your-org/edu-tools

import { Calculator, Ruler } from "@your-org/edu-tools";
import "@your-org/edu-tools/styles";

function App() {
  return (
    <div>
      <Calculator />
      <Ruler lengthPx={800} />
    </div>
  );
}

For Maintainers - Adding a New Tool

# Step 1: Create your component
# Create: app/components/mytool/MyTool.tsx

# Step 2: Auto-generate library files
npm run generate:lib

# Step 3: Build and publish
npm run build:lib
npm version patch
npm publish

That's it! Zero configuration needed! 🎉

📖 Table of Contents

• Available Tools
• Step-by-Step: Create Your First Tool
• Publishing to NPM
• Usage Examples
• Auto-Discovery System
• Project Structure
• Commands Reference
• Advanced Configuration
• Troubleshooting

🧰 Available Tools

This library includes 14 educational tools:

• Calculator - Full-featured calculator with keyboard support
• Ruler - Interactive ruler with inches and centimeters
• Protractor - Rotatable protractor for angle measurement
• Equation Editor - Mathematical equation editor (MathLive)
• Periodic Table - Interactive periodic table of elements
• Magnifier - Text magnification tool
• Todo List - Task management component
• TTS Reader - Text-to-speech functionality
• GeoGebra - Interactive geometry tool
• Dictionary - Word lookup and definitions
• Browser - Embedded browser component
• Set Square - Drawing tool for geometry
• Ask AI - AI assistant interface
• Context7 - Documentation browser

🎯 Step-by-Step: Create Your First Tool

Step 1: Create the Component

Create a new directory and component file:

app/components/timer/Timer.tsx

"use client";

import { useState, useEffect } from "react";

export default function Timer() {
  const [seconds, setSeconds] = useState(0);
  const [isRunning, setIsRunning] = useState(false);

  useEffect(() => {
    let interval: NodeJS.Timeout | null = null;

    if (isRunning) {
      interval = setInterval(() => {
        setSeconds((s) => s + 1);
      }, 1000);
    }

    return () => {
      if (interval) clearInterval(interval);
    };
  }, [isRunning]);

  const reset = () => {
    setSeconds(0);
    setIsRunning(false);
  };

  return (
    <div className="p-4 rounded-lg border border-border bg-card">
      <div className="text-4xl font-mono mb-4">
        {Math.floor(seconds / 60)}:{(seconds % 60).toString().padStart(2, "0")}
      </div>
      <div className="flex gap-2">
        <button
          onClick={() => setIsRunning(!isRunning)}
          className="px-4 py-2 bg-accent text-white rounded"
        >
          {isRunning ? "Pause" : "Start"}
        </button>
        <button onClick={reset} className="px-4 py-2 bg-surface rounded">
          Reset
        </button>
      </div>
    </div>
  );
}

Step 2: Auto-Generate Library Files

Run the auto-discovery script:

npm run generate:lib

Output:

✓ Found tool: timer (Timer)
✓ Generated lib/index.ts with 15 tools
✓ Generated 15 individual tool entries
✅ All library files generated successfully!

What just happened?

• ✅ Your new tool was automatically discovered
• ✅ lib/index.ts was updated with your export
• ✅ lib/tools/timer.ts was created for tree-shaking
• ✅ Build configuration was updated

Step 3: Test Locally

Test your tool in the Next.js app:

// app/page.tsx
import Timer from "./components/timer/Timer";

export default function Page() {
  return <Timer />;
}

npm run dev
# Visit http://localhost:3000

Step 4: Build the Library

npm run build:lib

Output:

✓ Found 15 tools
✓ Generated library files
📦 Building library with 16 entries
✓ built in 417ms

dist/timer.js     0.12 kB │ gzip: 0.12 kB
dist/timer.cjs    0.19 kB │ gzip: 0.17 kB

Step 5: Test in Another Project (Optional but Recommended)

Before publishing, test in a separate project:

# In your library directory
npm pack
# Creates: your-org-edu-tools-1.0.0.tgz

# In a test project
npm install /path/to/your-org-edu-tools-1.0.0.tgz

# Test it
import { Timer } from "@your-org/edu-tools";

📦 Publishing to NPM

First-Time Setup

• Create NPM Account (if you don't have one)

  • Visit https://www.npmjs.com/signup
  • Create your account

• Login to NPM

  npm login
  

• Choose Your Package Name

  Update package.json:

  {
    "name": "@your-username/edu-tools",
    "version": "1.0.0",
    "description": "Educational tools as React components"
  }
  

Publishing

# Build the library
npm run build:lib

# Version bump (choose one)
npm version patch  # 1.0.0 -> 1.0.1 (bug fixes)
npm version minor  # 1.0.0 -> 1.1.0 (new features)
npm version major  # 1.0.0 -> 2.0.0 (breaking changes)

# Publish to NPM
npm publish --access public

Success! Your package is now on NPM! 🎊

Updating the Package

When you add new tools or make changes:

# 1. Make your changes (add tools, fix bugs, etc.)

# 2. Regenerate library files
npm run generate:lib

# 3. Build
npm run build:lib

# 4. Bump version
npm version patch  # or minor/major

# 5. Publish
npm publish

💡 Usage Examples

Basic Import (All Tools)

import { Calculator, Timer, Ruler } from "@your-org/edu-tools";
import "@your-org/edu-tools/styles";

function App() {
  return (
    <div>
      <Calculator />
      <Timer />
      <Ruler lengthPx={600} />
    </div>
  );
}

Individual Import (Better Tree-Shaking)

import { Calculator } from "@your-org/edu-tools/calculator";
import { Timer } from "@your-org/edu-tools/timer";
import "@your-org/edu-tools/styles";

// Only Calculator and Timer code is bundled! (~3 KB total)

Lazy Loading

import { lazy, Suspense } from "react";

const Timer = lazy(() =>
  import("@your-org/edu-tools/timer").then((m) => ({ default: m.Timer }))
);

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Timer />
    </Suspense>
  );
}

With Draggable Windows

import { Timer, WindowLayer, useWindowStore } from "@your-org/edu-tools";

function App() {
  const createWindow = useWindowStore((s) => s.createWindow);

  const openTimer = () => {
    createWindow({
      type: "timer",
      title: "Timer",
      initialBounds: { width: 300, height: 200 },
    });
  };

  return (
    <div>
      <button onClick={openTimer}>Open Timer</button>
      <WindowLayer />
    </div>
  );
}

🔍 Auto-Discovery System

How It Works

The system automatically discovers tools based on file structure:

app/components/
├── calculator/
│   └── Calculator.tsx       ← Auto-discovered!
├── timer/
│   └── Timer.tsx            ← Auto-discovered!
└── mytool/
    └── MyTool.tsx           ← Auto-discovered!

Naming Conventions

The system is smart and supports multiple naming patterns:

Directory	Component File	Export Name
calculator/	Calculator.tsx	Calculator
equation/	EquationEditor.tsx	EquationEditor
periodic/	PeriodicTable.tsx	PeriodicTable
timer/	Timer.tsx	Timer

Priority:

• Exact match: calculator/Calculator.tsx
• Common suffixes: [Name]Editor, [Name]Table, [Name]Reader
• First .tsx file alphabetically

Excluded Directories

These directories are automatically excluded:

• hooks/ - Utility hooks
• ui/ - UI components
• windows/ - Window management
• tools/ - Tool definitions
• docks/ - Dock components

What Gets Generated

When you run npm run generate:lib:

• Main Entry (lib/index.ts)

  export { default as Calculator } from "../app/components/calculator/Calculator";
  export { default as Timer } from "../app/components/timer/Timer";
  // ... all tools
  

• Individual Entries (lib/tools/timer.ts)

  export { default as Timer } from "../../app/components/timer/Timer";
  export * from "../../app/components/timer/Timer";
  

• Build Configuration

  • Updates Vite entry points
  • Generates package.json exports

📁 Project Structure

equation-editor/
│
├── app/
│   ├── components/              # Your tools (add new tools here!)
│   │   ├── calculator/
│   │   │   └── Calculator.tsx
│   │   ├── timer/
│   │   │   └── Timer.tsx
│   │   └── [your-new-tool]/
│   │       └── [YourNewTool].tsx
│   └── ...
│
├── lib/                         # Library utilities
│   ├── calculator.ts           ✅ Keep (utility library)
│   ├── calculator.test.ts      ✅ Keep (tests)
│   │
│   # Auto-generated (gitignored):
│   ├── index.ts                ⚠️  Generated by npm run generate:lib
│   └── tools/                  ⚠️  Generated by npm run generate:lib
│
├── scripts/
│   └── generate-lib-entries.mjs  # Auto-discovery magic
│
├── docs/                        # Documentation
│
├── vite.lib.config.ts          # Library build config
├── package.json                # NPM configuration
└── README.md                   # This file

🔧 Commands Reference

Development

npm run dev              # Start Next.js dev server
npm test                 # Run tests
npm run lint             # Run linter

Library Building

npm run generate:lib     # Auto-discover tools and generate exports
npm run build:lib        # Build library (includes generate:lib)
npm run build:types      # Generate TypeScript definitions

Publishing

npm version patch        # Bump version (bug fixes)
npm version minor        # Bump version (new features)
npm version major        # Bump version (breaking changes)
npm publish              # Publish to NPM

Verification

npm pack                 # Create .tgz for local testing
npm run build:lib        # Verify build works
npm test                 # Verify tests pass

⚙️ Advanced Configuration

Custom Discovery Logic

Edit scripts/generate-lib-entries.mjs to customize:

// Add custom suffixes
const mainVariants = [
  `${componentNameFromDir}Editor`,
  `${componentNameFromDir}Table`,
  `${componentNameFromDir}Widget`, // Your custom suffix
];

// Add exclusions
const EXCLUDED_DIRS = [
  "hooks",
  "ui",
  "your-excluded-dir", // Add here
];

Build Configuration

Edit vite.lib.config.ts for custom build settings:

export default defineConfig({
  build: {
    lib: {
      name: "EduTools",
      formats: ["es", "cjs"], // Add "umd" if needed
    },
  },
});

Package Configuration

Edit package.json for metadata:

{
  "name": "@your-org/edu-tools",
  "version": "1.0.0",
  "description": "Your description",
  "keywords": ["react", "education", "components"],
  "repository": "https://github.com/your-org/edu-tools"
}

🐛 Troubleshooting

Tool Not Discovered

Problem: Your tool doesn't appear after running npm run generate:lib

Solutions:

• Check component file is .tsx or .jsx
• Verify directory isn't in EXCLUDED_DIRS
• Ensure file is in immediate subdirectory:

  ✅ app/components/mytool/MyTool.tsx
  ❌ app/components/mytool/sub/MyTool.tsx
  

• Check component name matches directory (PascalCase):

  ✅ timer/ -> Timer.tsx
  ❌ timer/ -> MyTimer.tsx (won't match)
  

Build Errors

Problem: Build fails with module errors

Solutions:

# Clean and rebuild
rm -rf dist/ lib/index.ts lib/tools/
npm run build:lib

# Check for import errors
npm run lint

Wrong Component Exported

Problem: Script exports wrong file from directory

Solutions:

• Rename main component to match directory
• Use standard suffixes: Editor, Table, Reader
• Make it alphabetically first

Publishing Fails

Problem: npm publish fails

Solutions:

• Not logged in:

  npm login
  

• Package name taken:

  {
    "name": "@your-username/edu-tools"
  }
  

• Access denied (scoped package):

  npm publish --access public
  

• Missing build:

  npm run build:lib
  

Users Can't Import Styles

Problem: Styles not working for users

Solution: Tell users to import styles:

import "@your-org/edu-tools/styles";

📊 Bundle Size Optimization

For Library Maintainers

Keep tools small and focused:

// Good - Single responsibility
export default function Calculator() { ... }

// Avoid - Multiple tools in one file
export function Calculator() { ... }
export function ScientificCalculator() { ... }

For Library Users

Use individual imports for better tree-shaking:

// Larger bundle (~200 KB)
import { Calculator, Timer, Ruler } from "@your-org/edu-tools";

// Smaller bundle (~10 KB)
import { Calculator } from "@your-org/edu-tools/calculator";
import { Timer } from "@your-org/edu-tools/timer";

🎨 Styling

Default Styles

The library uses Tailwind CSS. Import the bundled styles:

import "@your-org/edu-tools/styles";

Custom Theming

Override CSS variables:

:root {
  --color-accent: #your-color;
  --color-card: #your-color;
  --color-foreground: #your-color;
}

Integrate with Your Tailwind

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@your-org/edu-tools/**/*.js",
  ],
  theme: {
    extend: {
      // Your customizations
    },
  },
};

🔐 Best Practices

For Tool Creation

• ✅ One tool per directory
• ✅ Match component name to directory (PascalCase)
• ✅ Keep tools focused (single responsibility)
• ✅ Add TypeScript types
• ✅ Include accessibility (ARIA labels)
• ✅ Make responsive

For Library Maintenance

• ✅ Always run generate:lib before building
• ✅ Test locally with npm pack before publishing
• ✅ Use semantic versioning
• ✅ Document breaking changes
• ✅ Keep dependencies up to date
• ✅ Don't commit auto-generated files

For Users

• ✅ Import only what you need (tree-shaking)
• ✅ Import styles: import "@your-org/edu-tools/styles"
• ✅ Use TypeScript for better DX
• ✅ Lazy load heavy components

📚 Quick Reference

File Structure

✅ app/components/[toolname]/[ComponentName].tsx  # Your tools
✅ lib/calculator.ts                              # Utility libraries
⚠️ lib/index.ts                                   # Auto-generated
⚠️ lib/tools/*.ts                                 # Auto-generated

Commands

npm run generate:lib     # Discover tools
npm run build:lib        # Build library
npm version patch        # Bump version
npm publish              # Publish to NPM

Workflow

1. Create component → 2. generate:lib → 3. build:lib → 4. publish

🤝 Contributing

• Create your tool in app/components/[toolname]/
• Run npm run generate:lib
• Test with npm run dev
• Build with npm run build:lib
• Submit a PR!

📄 License

MIT © Your Name

🙏 Credits

• Built with React & Next.js
• Bundled with Vite
• Equation editor: MathLive
• Icons: Lucide
• Animations: Framer Motion

📞 Support

• 🐛 Report Issues
• 💬 Discussions
• 📖 NPM Package

Made with ❤️ for educators and learners

⭐ Star us on GitHub | 📦 Install from NPM