Documentation Index

Complete documentation for Router-Kit v1.3.1

🌐 Website: https://routerkit.com/

📚 Documentation Structure

This directory contains comprehensive documentation for Router-Kit. Choose the documentation that best fits your needs:

For Users

• Quick Start Guide - Get up and running in 5 minutes
• Complete Documentation - Full feature guide with examples
• API Reference - Detailed API documentation
• Examples - Real-world usage examples

For Developers

• Architecture - Internal implementation details
• Contributing Guide - How to contribute to Router-Kit

Quick Start Guide

Installation

npm install router-kit

Basic Setup

Programmatic Approach (Traditional):

import React from "react";
import { createRouter, RouterProvider, Link } from "router-kit";

// 1. Define your components
const Home = () => <h1>Home Page</h1>;
const About = () => <h1>About Page</h1>;

// 2. Create routes
const routes = createRouter([
  { path: "/", component: <Home /> },
  { path: "about", component: <About /> },
]);

// 3. Wrap your app with RouterProvider
function App() {
  return <RouterProvider routes={routes} />;
}

export default App;

Declarative Approach (New in v1.3.1):

import React from "react";
import { Router, Route, Link } from "router-kit";

// 1. Define your components
const Home = () => <h1>Home Page</h1>;
const About = () => <h1>About Page</h1>;

// 2. Use declarative JSX routing
function App() {
  return (
    <Router>
      <Route path="/" element={<Home />} />
      <Route path="/about" element={<About />} />
    </Router>
  );
}

export default App;

🆕 New in v1.3.1: Declarative routing with <Router> and <Route> components! Choose the approach that fits your style.

Navigation

import { Link, NavLink } from "router-kit";

function Navigation() {
  return (
    <nav>
      <Link to="/">Home</Link>
      <NavLink to="/about" activeClassName="active">
        About
      </NavLink>
    </nav>
  );
}

Dynamic Routes

import { useParams } from "router-kit";

// Route: /users/:id
const routes = createRouter([
  { path: "users/:id", component: <UserProfile /> },
]);

function UserProfile() {
  const { id } = useParams();
  return <h1>User {id}</h1>;
}

Programmatic Navigation

import { useRouter } from "router-kit";

function LoginForm() {
  const { navigate } = useRouter();

  const handleLogin = () => {
    // After successful login
    navigate("/dashboard");
  };

  return <button onClick={handleLogin}>Login</button>;
}

Documentation Files

DOCUMENTATION.md

Complete user guide covering:

• Introduction and key features
• Installation instructions
• Core concepts explained
• API reference with examples
• Advanced usage patterns
• Error handling strategies
• TypeScript support
• Best practices
• Migration guide from other routers
• Real-world examples

Best for: Learning Router-Kit from scratch, understanding concepts, and finding usage examples.

API_REFERENCE.md

Comprehensive API documentation including:

• createRouter() function
• RouterProvider component
• Link and NavLink components
• useRouter() hook
• useParams() hook
• useQuery() hook
• useLocation() hook
• useDynamicComponents() hook
• Type definitions
• Error system reference

Best for: Looking up specific APIs, understanding function signatures, and exploring available options.

EXAMPLES.md

Practical examples featuring:

• Basic routing examples
• E-commerce application
• Blog platform
• Dashboard application
• Multi-language website
• Authentication flow
• Advanced patterns (lazy loading, modals, breadcrumbs, animations)

Best for: Finding real-world implementation patterns and copy-paste solutions.

ARCHITECTURE.md

Technical implementation details including:

• System architecture overview
• Core component implementations
• Route matching algorithm
• History management
• Context system
• Error handling system
• Type system
• Performance considerations
• Build and distribution

Best for: Understanding internals, contributing to the project, or debugging complex issues.

Common Use Cases

Simple Website

const routes = createRouter([
  { path: "/", component: <Home /> },
  { path: "about", component: <About /> },
  { path: "contact", component: <Contact /> },
  { path: "/404", component: <NotFound /> },
]);

📖 See: Basic Examples in EXAMPLES.md

Blog or CMS

const routes = createRouter([
  { path: "/", component: <BlogHome /> },
  { path: "posts/:category/:slug", component: <BlogPost /> },
  { path: "author/:username", component: <AuthorProfile /> },
]);

📖 See: Blog Platform in EXAMPLES.md

Dashboard Application

const routes = createRouter([
  { path: "dashboard/:view", component: <Dashboard /> },
]);

function Dashboard() {
  const views = {
    overview: <OverviewView />,
    analytics: <AnalyticsView />,
    settings: <SettingsView />,
  };

  return useDynamicComponents(views, "view");
}

📖 See: Dashboard Application in EXAMPLES.md

E-commerce Site

const routes = createRouter([
  { path: "/", component: <HomePage /> },
  { path: "products", component: <ProductList /> },
  { path: "products/:id", component: <ProductDetail /> },
  { path: "cart", component: <Cart /> },
  { path: "checkout", component: <Checkout /> },
]);

📖 See: E-commerce Application in EXAMPLES.md

Protected Routes

const routes = createRouter([
  { path: "/", component: <PublicHome /> },
  {
    path: "dashboard",
    component: (
      <ProtectedRoute>
        <Dashboard />
      </ProtectedRoute>
    ),
  },
]);

📖 See: Authentication Flow in EXAMPLES.md

Feature Matrix

| Feature | Status | Documentation | | ----------------------- | ---------- | ------------------------------------------------ | | Static Routes | ✅ | Docs | | Dynamic Routes | ✅ | Docs | | Nested Routes | ✅ | Docs | | Multiple Path Aliases | ✅ | Docs | | Query Parameters | ✅ | Docs | | Navigation State | ✅ | Docs | | Custom 404 Pages | ✅ | Docs | | TypeScript Support | ✅ | Docs | | Error Handling | ✅ | Docs | | Dynamic Components | ✅ | Docs | | Declarative Routing | ✅ NEW | Docs | | Hash Routing | ⏳ | Planned | | Regex Routes | ⏳ | Planned |

Quick Reference

Imports

// Core
import { createRouter, RouterProvider, Router, Route } from "router-kit";

// Components
import { Link, NavLink } from "router-kit";

// Hooks
import {
  useRouter,
  useParams,
  useQuery,
  useLocation,
  useDynamicComponents,
} from "router-kit";

// Types
import type {
  Route,
  RouterContextType,
  NavigateOptions,
  Location,
  RouterKitError,
} from "router-kit";

// Error System
import { RouterErrorCode, RouterErrors, createRouterError } from "router-kit";

Route Patterns

Programmatic Approach:

// Static route
{ path: "about", component: <About /> }

// Dynamic parameter
{ path: "users/:id", component: <UserProfile /> }

// Multiple parameters
{ path: "posts/:category/:slug", component: <BlogPost /> }

// Multiple paths
{ path: ["about", "about-us"], component: <About /> }

// Nested routes
{
  path: "dashboard",
  component: <Dashboard />,
  children: [
    { path: "settings", component: <Settings /> }
  ]
}

// 404 page
{ path: "/404", component: <NotFound /> }

Declarative Approach:

// Static route
<Route path="/about" element={<About />} />

// Dynamic parameter
<Route path="/users/:id" element={<UserProfile />} />

// Multiple parameters
<Route path="/posts/:category/:slug" element={<BlogPost />} />

// Multiple paths
<Route path={["/about", "/about-us"]} element={<About />} />

// Nested routes
<Route path="/dashboard" element={<Dashboard />}>
  <Route path="settings" element={<Settings />} />
</Route>

// 404 page
<Route path="/404" element={<NotFound />} />

Hook Usage

// Get router context
const { path, navigate } = useRouter();

// Get route parameters
const { id, slug } = useParams();

// Get query parameters
const { search, page } = useQuery();

// Get location details
const { pathname, search, hash, state } = useLocation();

// Dynamic components
const component = useDynamicComponents(viewsObject, "paramName");

Version Information

• Current Version: 1.3.1
• React Version: >=16 <20
• TypeScript: >=5.2.0
• License: MIT

Support & Community

• Website: routerkit.com
• GitHub Repository: github.com/Mohammed-Ben-Cheikh/router-kit
• Issues: Report bugs or request features
• Author: Mohammed Ben Cheikh
• Email: [email protected]
• Website: mohammedbencheikh.com

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests and type checks: npm run typecheck
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to your fork: git push origin feature/amazing-feature
7. Open a Pull Request

See: ARCHITECTURE.md for implementation details.

Changelog

v1.3.1 (Current)

• Full TypeScript support with comprehensive types
• Enhanced error handling system with detailed context
• New useDynamicComponents hook
• New useLocation hook with state support
• Improved type exports
• Better error messages

Previous Versions

See GitHub Releases for full changelog.

FAQ

How does Router-Kit compare to React Router?

Router-Kit is simpler and lighter. It's perfect for small to medium projects that don't need the full complexity of React Router.

📖 See: Migration Guide in DOCUMENTATION.md

Can I use Router-Kit with TypeScript?

Yes! Router-Kit is written in TypeScript and provides full type definitions.

📖 See: TypeScript Support in DOCUMENTATION.md

How do I handle authentication?

Use the ProtectedRoute pattern with useRouter and useLocation hooks.

📖 See: Authentication Flow in EXAMPLES.md

How do I create nested routes?

Use the children property in route configuration.

📖 See: Nested Routes in DOCUMENTATION.md

What about 404 pages?

Add a route with path: "/404" and Router-Kit will use it automatically.

📖 See: Custom 404 Pages in DOCUMENTATION.md

Learn More

Ready to dive deeper? Start with the Complete Documentation or explore specific topics:

• New to Router-Kit? → DOCUMENTATION.md
• Need API details? → API_REFERENCE.md
• Want examples? → EXAMPLES.md
• Curious about internals? → ARCHITECTURE.md

Happy Routing! 🚀