Skip to content

README.md

Latest commit

 

History

History
350 lines (263 loc) · 14.1 KB

README.md

File metadata and controls

350 lines (263 loc) · 14.1 KB
JSphere Logo

JSphere

The JavaScript Engineering Knowledge System

A premium, structured knowledge platform built for real-world JavaScript engineers.
Learn, reference, build, integrate, and debug — all in one place.

React TypeScript Vite Tailwind CSS License


🌐 Live Site  ·  📚 Content Pillars  ·  🚀 Getting Started  ·  🐛 Report Bug  ·  ✨ Request Feature


"Built for builders. Engineered for clarity."

📖 Table of Contents

🚀 Overview

JSphere is a modern, full-featured JavaScript engineering knowledge platform designed for developers who want more than just documentation. It's a curated ecosystem of:

  • 📘 Structured learning paths — from beginner fundamentals to advanced patterns
  • 📄 API references — instantly searchable method signatures with examples
  • 🍳 Production-ready recipes — real code patterns you can drop into any project
  • 🔌 Integration guides — connect JavaScript with real-world services
  • 🚀 Project walkthroughs — build complete apps from scratch
  • 🧭 Discovery tools — explore libraries, glossaries, and comparisons
  • 🐛 Debugging playbooks — break down errors and fix them fast

All wrapped in a beautiful, fast, accessible, and fully responsive UI — with dark mode, smart search, bookmarks, and reading progress tracking built in.

Whether you're a beginner learning closures or a senior engineer wiring up OAuth flows, JSphere meets you exactly where you are.

📚 Content Pillars

JSphere organizes all knowledge into 7 focused pillars, each designed for a specific engineering need:

Pillar Description Topics Covered
📘 Learn Structured lessons from basics to advanced Fundamentals, Async, Advanced Patterns, Browser APIs
📄 Reference Fast, searchable method-level documentation Array, String & Object methods with signatures & examples
🍳 Recipes Production-ready implementation patterns Debouncing, Pagination, File Upload, Infinite Scroll & more
🔌 Integrations Guides for external services & APIs REST APIs, OAuth, Payments, Telegram, YouTube & more
🚀 Projects Full app walkthroughs from idea to code CRUD App, Chat App, Notes, Analytics Dashboard & more
🧭 Explore Curated directories and discovery tools Libraries, Tooling, Glossary, Comparisons
🐛 Errors Debugging guides and error breakdowns Common Errors, API Errors, Async Bugs, DOM Issues

✨ Features

🔍 Smart Search

  • Full-text search with fuzzy matching and token-based relevance ranking
  • Weighted scoring across titles, aliases, keywords, tags, and descriptions
  • Results intelligently grouped by content type and ordered by relevance
  • Keyboard shortcut: ⌘K / Ctrl+K for instant access anywhere

📖 Rich Content Renderer

  • Block-based content system: paragraphs, headings, code, lists, callouts, and tables
  • Syntax-highlighted code blocks with language detection and line-level highlights
  • Function signature tables, parameter docs, and return type info for Reference pages
  • Prerequisites, learning goals, and practice exercises for Learn pages

🗺️ Smart Navigation

  • Breadcrumb trails for full context awareness at every level
  • Previous / Next navigation to move through pillar content sequentially
  • Auto-generated Table of Contents from page headings
  • Responsive collapsible sidebar with section grouping

👤 Personalization & User Library

  • Bookmarks — save any piece of content for later
  • Recently Viewed — instantly revisit your reading history
  • Continue Reading — resume exactly where you left off
  • Search History — bring back any past search with one click

🎨 Polished Design System

  • HSL-based design tokens with unique accent colors per pillar
  • Fully responsive layout optimized for mobile, tablet, and desktop
  • Dark / Light mode with automatic system preference detection
  • Custom typography: Inter for UI + JetBrains Mono / Fira Code for code

⚡ Performance First

  • Vite + SWC for sub-second builds and instant Hot Module Replacement
  • Route-based code splitting via React Router lazy loading
  • Metadata-driven content with auto-generated loaders for lean bundles
  • Skeleton loading states for a smooth perceived performance experience

🔎 SEO Ready

  • Dynamic <meta> tags per page via React Helmet Async
  • Structured content metadata: difficulty level, reading time, and related topics
  • Clean, semantic URL structure: /{pillar}/{category}/{slug}

🛠 Tech Stack

JSphere is built on a modern, production-grade stack chosen for speed, scalability, and developer experience:

Layer Technology Purpose
Framework React 18 + TypeScript 5 UI & type safety
Build Tool Vite 5 + SWC Ultra-fast builds & HMR
Styling Tailwind CSS 3 Utility-first styling with custom tokens
UI Components shadcn/ui + Radix UI Accessible, composable primitives
Routing React Router v6 Client-side routing with lazy loading
Data Fetching TanStack Query v5 Async state management
Forms React Hook Form + Zod Form handling & schema validation
Code Highlighting Prism React Renderer Syntax-highlighted code blocks
Charts Recharts Data visualization
Icons Lucide React Consistent icon system
Theming next-themes Dark/light mode
Unit Testing Vitest + Testing Library Fast unit & integration tests
E2E Testing Playwright End-to-end browser testing
Linting ESLint 9 Code quality enforcement

🗂 Project Structure

jsphere/
├── public/                      # Static assets (favicon, robots.txt)
├── scripts/
│   └── generate-content.mjs     # Auto-generates content loaders & metadata
├── src/
│   ├── components/
│   │   ├── cards/               # Category & content card components
│   │   ├── code/                # Syntax-highlighted code block
│   │   ├── content/             # Content renderers, callouts, meta, skeletons
│   │   ├── layout/              # DocsLayout — the main page shell
│   │   ├── navigation/          # Navbar, Sidebar, Breadcrumbs, TOC, Prev/Next
│   │   ├── search/              # Search modal with fuzzy matching
│   │   ├── seo/                 # SEO & Open Graph meta tag components
│   │   ├── shared/              # ThemeToggle, NavLink & shared utilities
│   │   └── ui/                  # shadcn/ui component primitives
│   ├── config/
│   │   ├── categories.ts        # Pillar definitions & accent colors
│   │   ├── navigation.ts        # Sidebar navigation tree
│   │   └── site.ts              # Global site metadata
│   ├── content/
│   │   ├── learn/               # Lesson content (fundamentals, async, advanced, browser)
│   │   ├── reference/           # API reference docs (array, string, object)
│   │   ├── recipes/             # Code recipes & production patterns
│   │   ├── integrations/        # External service integration guides
│   │   ├── projects/            # Full project walkthroughs
│   │   ├── explore/             # Libraries, glossary, tooling, comparisons
│   │   ├── errors/              # Debugging guides & error breakdowns
│   │   ├── generated/           # Auto-generated loaders & metadata (do not edit)
│   │   └── registry.ts          # Central content registry
│   ├── features/                # Feature-level page components per pillar
│   ├── hooks/                   # Custom React hooks (search, reading progress, library)
│   ├── lib/                     # Core utilities (content, search, navigation)
│   ├── pages/                   # Route-level page entry points
│   ├── tests/                   # Unit tests (Vitest + Testing Library)
│   ├── types/                   # Shared TypeScript type definitions
│   └── main.tsx                 # Application entry point
├── tests/                       # Playwright E2E test specs
├── vite.config.ts
├── tailwind.config.ts
├── playwright.config.ts
└── vitest.config.ts

🏁 Getting Started

Prerequisites

Make sure you have the following installed before you begin:

  • Node.js v18 or higher
  • Bun (recommended for speed) or npm / yarn / pnpm

Installation

# 1. Clone the repository
git clone https://github.com/your-username/jsphere.git
cd jsphere

# 2. Install dependencies
bun install
# or: npm install

# 3. Start the development server
# (content metadata is auto-generated before dev starts)
bun run dev
# or: npm run dev

The app will be running at http://localhost:8080 🚀

Manual Content Generation

Content metadata is automatically generated before dev, build, and test commands. To run it manually:

bun run generate:content
# or: npm run generate:content

📜 Available Scripts

Command Description
bun run dev Start the local dev server on port 8080 with HMR
bun run build Build the app for production
bun run build:dev Build in development mode (unminified)
bun run preview Preview the production build locally
bun run generate:content Generate content metadata & dynamic loaders
bun run lint Run ESLint across the entire codebase
bun run test Run all unit tests with Vitest
bun run test:watch Run unit tests in watch mode (great for TDD)
bun run test:e2e Run end-to-end tests with Playwright

All bun run commands can be replaced with npm run if you prefer npm.

🧪 Testing

JSphere has a comprehensive three-layer testing strategy to ensure correctness and reliability.

Unit & Integration Tests — Vitest

bun run test

Covers:

  • ✅ Content integrity — validates all content entries are well-formed
  • ✅ Search logic — fuzzy matching, ranking, and filtering correctness
  • ✅ SEO — ensures meta tags render correctly per page
  • ✅ User library — bookmarks, history, and reading state management

Watch Mode

bun run test:watch

Ideal for active development — tests re-run automatically on every file change.

End-to-End Tests — Playwright

bun run test:e2e

Smoke tests for critical user journeys:

  • App loads and renders correctly
  • Navigation between pillars works
  • Search modal opens and returns results
  • Content pages render without errors

🤝 Contributing

Contributions are welcome and appreciated! Here's how to get involved:

  1. Fork this repository
  2. Create a feature branch: 
    git checkout -b feat/your-feature-name
  3. Make your changes and ensure tests pass: 
    bun run test && bun run lint
  4. Commit using conventional commit format: 
    git commit -m "feat: add your feature description"
  5. Push to your branch: 
    git push origin feat/your-feature-name
  6. Open a Pull Request and describe what you've changed

Guidelines

  • Follow the existing code style (TypeScript, ESLint rules enforced)
  • All new content entries must be registered in src/content/registry.ts
  • Keep components small, focused, and well-typed
  • Write tests for any new logic in src/lib/ or src/hooks/

👨‍💻 Author

Built with passion and precision by Umar — a developer who believes that great documentation and clean code are the foundation of great software.

Platform Handle
📱 Telegram @Winnr0
📸 Instagram @winnr.9

JSphere — Engineered for clarity. Built for builders.


⭐ If JSphere helps you, please consider giving it a star — it means a lot!


React TypeScript Vite