MiniReact

A learning project to build a simplified React-like library from scratch, with a focus on understanding virtual DOM, reconciliation, and component-based architecture. This project is developed incrementally in well-defined phases, each with comprehensive test coverage and production-quality code.

Overview

MiniReact is a step-by-step implementation of a React-like UI library designed for learning and understanding how modern UI frameworks work under the hood. The project emphasizes:

Test-driven development with full test coverage
Quality code with full TypeScript support and linting
Incremental complexity with well-documented phases
Performance optimization with efficient reconciliation algorithms
Real-world patterns that mirror React's actual implementation

Each phase includes clear specifications, working implementations, and extensive test coverage to ensure reliability and educational value.

Current Status

🆕 Current Phase: Stable Release Track - Phase 12 ✅ COMPLETE

Latest Achievements:

✅ Phase 12 Complete: Performance Optimization Suite - memo, useMemo, useCallback with comprehensive test coverage
✅ Enhanced Performance: React.memo equivalent for component memoization and optimization hooks
✅ 272 Tests Passing: Comprehensive test suite covering all functionality including performance optimizations
✅ Zero Linter Issues: Clean codebase with consistent formatting and biome configuration
✅ Complete Performance Toolkit: memo, useMemo, useCallback hooks for production-grade optimization
✅ Production-Ready: Robust error handling, TypeScript support, and comprehensive edge case coverage
✅ Package Preparation: Ready for npm registry publication with performance features

Stable Release Progress: 1/9 phases complete (11% complete) 🚀

Immediate Milestones:

🚀 npm Package Publication: Package will be available on npm registry soon
📦 Alpha Release v0.1.0: Complete core React-like functionality now available
📚 Documentation & Examples: Comprehensive guides and demo applications

Post-Alpha Roadmap: 12 additional phases planned for stable v1.0.0 release with advanced features including concurrent rendering, SSR, dev tools, and production optimizations.

Quick Start

Prerequisites

Bun (for runtime and testing)
Biome (for linting/formatting)
happy-dom (for DOM testing environment)

Installation

📦 npm Package (Coming Soon):

Installation

npm install @marcelolsen/mini-react
# or
bun add @marcelolsen/mini-react

🔧 Development Installation (Current):

# Clone the repository for development/testing
git clone https://github.com/MarcelOlsen/mini-react.git
cd mini-react

# Install dependencies
bun install

# Run tests to verify installation
bun test

# Build the project
bun run build

Basic Usage

import { createElement, render } from "@marcelolsen/mini-react";
import type { FunctionalComponent } from "@marcelolsen/mini-react";

// Simple host element
const simpleElement = createElement("h1", { id: "title" }, "Hello MiniReact!");

// Functional component with props
const Greeting: FunctionalComponent = (props) => {
  const { name } = props as { name: string };
  return createElement("p", { className: "greeting" }, `Hello, ${name}!`);
};

// Component with children
const Layout: FunctionalComponent = (props) => {
  const { title, children } = props as { title: string; children?: any[] };
  return createElement(
    "div",
    { className: "app" },
    createElement("h1", null, title),
    createElement("div", { className: "content" }, ...(children || []))
  );
};

// Complex component composition
const App = () => {
  return createElement(
    Layout,
    { title: "MiniReact Demo" },
    createElement(Greeting, { name: "World" }),
    createElement("p", null, "Building React from scratch!")
  );
};

// Render to DOM
const container = document.getElementById("root")!;
render(createElement(App), container);

// Dynamic updates (reconciliation in action)
setTimeout(() => {
  render(createElement(Greeting, { name: "Universe" }), container);
}, 2000);

Running Tests

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run specific test file
bun test tests/MiniReact.render.test.ts

# Check code quality
bunx biome check

JSX Usage (New!)

With Phase 10 complete, you can now use JSX syntax! Configure your build tool (TypeScript/Bun) to use the MiniReact JSX runtime:

tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@marcelolsen/mini-react"
  }
}

JSX Examples:

import { render, useState, Fragment } from "@marcelolsen/mini-react";

// JSX syntax instead of createElement!
const Greeting = ({ name }: { name: string }) => {
  return <p className="greeting">Hello, {name}!</p>;
};

const Counter = () => {
  const [count, setCount] = useState(0);

  return (
    <div className="counter">
      <h2>Count: {count}</h2>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
};

// Fragments work too!
const App = () => {
  return (
    <>
      <h1>MiniReact with JSX!</h1>
      <Greeting name="World" />
      <Counter />
    </>
  );
};

// Render with JSX
render(<App />, document.getElementById("root")!);

Advanced Usage Examples

Portal Usage

import {
  createElement,
  render,
  createPortal,
  useState,
} from "@marcelolsen/mini-react";

// Create a portal target in your HTML
// <div id="modal-root"></div>

const Modal = ({
  children,
  onClose,
}: {
  children: any;
  onClose: () => void;
}) => {
  const modalRoot = document.getElementById("modal-root");
  if (!modalRoot) return null;

  return createPortal(
    createElement(
      "div",
      {
        className: "modal-overlay",
        onClick: onClose,
        style: {
          position: "fixed",
          top: "0",
          left: "0",
          right: "0",
          bottom: "0",
          backgroundColor: "rgba(0,0,0,0.5)",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
        },
      },
      createElement(
        "div",
        {
          className: "modal-content",
          onClick: (e: Event) => e.stopPropagation(),
          style: {
            backgroundColor: "white",
            padding: "20px",
            borderRadius: "5px",
          },
        },
        children,
        createElement("button", { onClick: onClose }, "Close")
      )
    ),
    modalRoot
  );
};

const App = () => {
  const [showModal, setShowModal] = useState(false);

  return createElement(
    "div",
    null,
    createElement("h1", null, "Portal Demo"),
    createElement(
      "button",
      { onClick: () => setShowModal(true) },
      "Open Modal"
    ),
    showModal &&
      createElement(
        Modal,
        { onClose: () => setShowModal(false) },
        createElement("h2", null, "Modal Content"),
        createElement("p", null, "This modal is rendered using createPortal!")
      )
  );
};

Fragment Usage

import { createElement, Fragment } from "@marcelolsen/mini-react";

// Multiple children without wrapper element
const ItemList = ({ items }: { items: string[] }) => {
  return createElement(
    Fragment,
    null,
    ...items.map((item, index) => createElement("li", { key: index }, item))
  );
};

const App = () => {
  return createElement(
    "ul",
    null,
    createElement(ItemList, { items: ["Apple", "Banana", "Cherry"] })
  );
};

Features

🌟 Core React-Like Functionality

🏗️ Virtual DOM: Efficient virtual DOM implementation with reconciliation algorithm
⚡ Component System: Functional components with props and children support
🎣 Complete Hook Ecosystem: All essential React hooks implemented
- useState: State management with automatic re-rendering
- useEffect: Side effects with dependency arrays and cleanup
- useContext: Context API for prop drilling elimination
- useRef: DOM references and mutable values without re-renders
- useReducer: Complex state management with reducer patterns
⚡ Event Handling: Synthetic event system with proper event delegation and cleanup
🌐 Context API: createContext and useContext hooks with provider/consumer pattern
🌉 Portals: createPortal for rendering content to different DOM containers with React tree event bubbling
📦 Fragments: React.Fragment equivalent for rendering multiple children without wrapper DOM nodes
🎨 JSX Support: Full JSX syntax with jsx/jsxs/jsxDEV runtime functions and TypeScript integration

🎨 Advanced Capabilities

JSX Syntax: Full JSX syntax support with modern runtime (jsx, jsxs, jsxDEV)
TypeScript JSX: Complete type safety for JSX elements and components
Nested Components: Deep component hierarchies with proper reconciliation
Mixed Content: Text nodes, numbers, and elements as children
Conditional Rendering: Support for null/undefined elements with enhanced error handling
Performance Optimized: Key-based reconciliation for efficient list operations
Memory Efficient: Proper cleanup and DOM node reuse
Edge Case Handling: Robust error handling and boundary conditions with recent bug fixes
Portal Event System: Events bubble through React component tree, not DOM tree
Portal Context Propagation: Context values work seamlessly across portal boundaries
Fragment Reconciliation: Efficient updates for fragment children without wrapper elements

📋 Testing & Quality

261 Comprehensive Tests: Full test coverage for all features and edge cases including all hooks
TypeScript Support: Full type safety with detailed type definitions
Linting & Formatting: Biome-based code quality and consistent formatting
Error Handling: Graceful degradation and helpful error messages
Performance Testing: Reconciliation benchmarks and memory leak detection
Integration Testing: Full component lifecycle and interaction testing

Project Structure

mini-react/
├── src/
│   ├── MiniReact.ts          # Main library exports and JSX runtime
│   ├── types.ts              # TypeScript type definitions
│   ├── vdom.ts               # Virtual DOM creation and utilities
│   ├── reconciler.ts         # Virtual DOM reconciliation engine
│   ├── hooks.ts              # Hook implementations (useState, useEffect, useContext)
│   ├── context.ts            # Context API implementation
│   ├── portals.ts            # Portal system implementation
│   ├── events.ts             # Event system and synthetic events
│   └── jsx/                  # JSX runtime functions
│       ├── jsx-runtime.ts    # Production JSX runtime
│       └── jsx-dev-runtime.ts # Development JSX runtime with debugging
├── tests/                    # Comprehensive test suite
│   ├── MiniReact.render.test.ts
│   ├── MiniReact.functional-components.test.ts
│   ├── MiniReact.reconciliation.test.ts
│   ├── MiniReact.hooks.test.ts
│   ├── MiniReact.events.test.ts
│   ├── MiniReact.context.test.ts
│   ├── MiniReact.portals.test.ts
│   ├── MiniReact.fragments.test.ts
│   └── MiniReact.jsx.test.ts
├── examples/                 # Usage examples and demos
│   ├── jsx-examples/         # JSX syntax examples
│   ├── basic-usage/          # Basic API examples
│   ├── advanced-patterns/    # Advanced usage patterns
│   └── performance-tests/    # Performance benchmarks
└── package.json             # Dependencies and scripts

Development Phases

🚀 ALPHA RELEASE TRACK (Phases 1-11)

Phase 1: Element Creation & Basic Rendering ✅

Features:

✅ createElement function for host elements (div, span, etc.)
✅ Basic render function that creates real DOM from virtual DOM
✅ Support for props (attributes, event handlers, etc.)
✅ Support for children (text nodes, nested elements)
✅ Comprehensive test coverage for element creation and rendering

Phase 2: Functional Components ✅

Features:

✅ Support for functional components that return virtual DOM
✅ Props passing to functional components
✅ Component composition and nesting
✅ Proper TypeScript types for functional components
✅ Test coverage for functional component rendering and composition

Phase 3: Virtual DOM & Basic Reconciliation ✅

Features:

✅ Virtual DOM tree structure with proper typing
✅ Basic reconciliation algorithm to diff virtual DOM trees
✅ Efficient DOM updates (add, remove, update nodes)
✅ Text content updates and mixed content handling
✅ Element type changes and property updates
✅ Test coverage for virtual DOM creation and reconciliation

Phase 4: Prop Diffing & Efficient Children Reconciliation ✅

Features:

✅ Intelligent prop diffing with add/remove/update detection
✅ Key-based reconciliation for efficient list rendering and reordering
✅ Advanced children reconciliation with position tracking
✅ Style object diffing and updates
✅ Event handler updates and cleanup
✅ Edge case handling for complex reconciliation scenarios

Phase 5: State with useState Hook ✅

Features:

✅ useState hook implementation with proper state management
✅ Component re-rendering on state changes
✅ State preservation between renders
✅ Functional state updates and batching
✅ Hook rules enforcement and error handling
✅ Integration with reconciliation system for efficient updates

Phase 6: Event Handling ✅

Features:

✅ Synthetic event system with cross-browser compatibility
✅ Event delegation and efficient event management
✅ Event handler prop updates during reconciliation
✅ Event cleanup and memory leak prevention
✅ Support for all common DOM events (click, change, submit, etc.)
✅ Event object normalization and additional properties

Phase 7: Effects with useEffect ✅

Features:

✅ useEffect hook with dependency array support
✅ Effect cleanup functions and proper lifecycle management
✅ Effect scheduling and execution timing
✅ Dependency comparison and change detection
✅ Mount, update, and unmount effect handling
✅ Integration with component lifecycle and state changes

Phase 8: Context API ✅

Features:

✅ createContext function for context creation
✅ Context Provider component with value passing
✅ useContext hook for consuming context values
✅ Context value change detection and re-rendering
✅ Nested context support and context composition
✅ Performance optimization for context updates

Phase 9: Portals and Fragments ✅

Features:

✅ createPortal function for rendering to different DOM containers
✅ Portal event bubbling through React tree (not DOM tree)
✅ Context propagation across portal boundaries
✅ Portal cleanup and lifecycle management
✅ React.Fragment equivalent for grouping elements without wrapper
✅ Fragment reconciliation and efficient updates

Phase 10: JSX Support ✅

Features:

✅ JSX syntax support for component definitions and element creation
✅ JSX runtime functions (jsx, jsxs, jsxDEV) for build tool integration
✅ Fragment support with <> and </Fragment> syntax
✅ TypeScript JSX declarations for full type safety
✅ Build tool configuration (TypeScript/Babel integration)
✅ Development mode enhancements with source maps and debugging
✅ Backward compatibility with existing createElement API

Phase 11: Essential Hooks (useRef & useReducer) ✅

Features:

✅ useRef hook for DOM references and mutable values without re-renders
✅ useReducer hook for complex state management with reducer patterns
✅ Ref object with mutable .current property that persists across renders
✅ Reducer pattern with actions, state transitions, and dispatch function
✅ Integration with existing hook system and component lifecycle
✅ Comprehensive test coverage for all hook scenarios and edge cases
✅ TypeScript support with proper type inference and safety

🎉 ALPHA RELEASE v0.1.0 - Complete Core React-like Functionality

Status: ✅ NPM PACKAGE PUBLISHED

Alpha Release Features:

✅ Full React-like component system with JSX support
✅ Complete hook ecosystem (useState, useEffect, useContext, useRef, useReducer)
✅ Advanced rendering (Portals, Fragments)
✅ Production-ready reconciliation engine
✅ Comprehensive TypeScript support
✅ 261 tests with full coverage
✅ Developer-friendly API matching React patterns
✅ npm package ready for publication

🚀 STABLE RELEASE TRACK (Phases 12-20)

Phase 12: Performance Optimization Suite ✅

Features:

✅ Memoization (React.memo equivalent) for component optimization
✅ useMemo hook for expensive computation memoization
✅ useCallback hook for function reference stability
✅ Shallow prop comparison with custom comparison support
✅ Performance tracking and measurement utilities
✅ Comprehensive test coverage for all optimization features
✅ TypeScript support with proper type inference and safety

Phase 13: Error Boundaries & Resilience

Error boundary implementation
Graceful error handling and recovery
Development mode error overlays
Production error reporting
Component error isolation

Phase 14: Async Features & Suspense

Suspense component for async rendering
Lazy loading and code splitting support
Async component patterns
Loading state management
Error handling for async operations

Phase 15: Concurrent Features (Advanced)

Time slicing for smooth rendering
Priority-based rendering
Interruptible rendering
Scheduler implementation
Advanced reconciliation strategies

Phase 16: Developer Experience

Development tools and debugging
Component inspector
Hook debugging utilities
Performance profiler
Development warnings and tips

Phase 17: Server-Side Rendering

SSR capabilities
Hydration support
Server/client rendering parity
SEO optimization features
Static site generation support

Phase 18: Advanced Component Patterns

Higher-order components (HOCs)
Render props pattern
Compound components
Advanced composition patterns
Performance optimization patterns

Phase 19: Testing & Quality Assurance

Testing utilities and helpers
Component testing patterns
Integration testing tools
Performance testing suite
Accessibility testing support

Phase 20: Production Optimizations

Tree shaking and dead code elimination
Advanced bundling strategies
Runtime optimization
Memory usage optimization
Production monitoring tools

🎯 STABLE RELEASE v1.0.0 - Production-Ready React Alternative

Target: 6-8 months after Alpha Release

Stable Release Features:

Complete React API compatibility
Advanced performance optimizations
Full SSR and concurrent rendering support
Comprehensive developer tools
Production-ready with monitoring
Enterprise-level documentation and support

API Reference

createElement

function createElement(
  type: string | FunctionalComponent,
  props: Props | null,
  ...children: (MiniReactElement | string | number | null | undefined)[]
): MiniReactElement;

Creates a virtual DOM element. Supports both host elements (strings) and functional components.

Parameters:

type: Element type (e.g., 'div', 'span') or functional component
props: Element properties/attributes object or null
children: Child elements, text nodes, or primitive values

Example:

const greeting = createElement(Greeting, { name: "World" });

render

function render(
  element: AnyMiniReactElement | null | undefined,
  container: HTMLElement
): void;

Renders a virtual DOM element into a real DOM container with efficient reconciliation.

Parameters:

element: Virtual DOM element to render
container: Target DOM container element

Example:

const app = createElement("div", null, "Hello World");
render(app, document.getElementById("root")!);

Functional Components

type FunctionalComponent<P = Record<string, unknown>> = (
  props: P & { children?: AnyMiniReactElement[] }
) => AnyMiniReactElement | null;

Components are functions that take props and return virtual DOM elements. The type is generic, allowing for strongly typed props with destructuring. Now supports inferred component types just like React!

Examples:

// ✅ Inferred component (React-style) - RECOMMENDED
const Component = ({ id }: { id: string }) => {
  return createElement("div", { id }, "Hello World");
};

// ✅ Inferred with optional props
const Greeting = ({
  name = "Anonymous",
  age,
}: {
  name?: string;
  age?: number;
}) => {
  return createElement(
    "p",
    null,
    age ? `${name} is ${age} years old`

useState

function useState<T>(
  initialValue: T
): [T, (newValue: T | ((prev: T) => T)) => void];

Hook for managing component state with automatic re-rendering.

Example:

const Counter = () => {
  const [count, setCount] = useState(0);
  return createElement(
    "button",
    { onClick: () => setCount(count + 1) },
    `Count: ${count}`
  );
};

useEffect

function useEffect(
  effect: () => void | (() => void),
  dependencies?: any[]
): void;

Hook for side effects with optional cleanup and dependency tracking.

Example:

const Timer = () => {
  const [time, setTime] = useState(0);

  useEffect(() => {
    const interval = setInterval(() => setTime((t) => t + 1), 1000);
    return () => clearInterval(interval); // Cleanup
  }, []); // Empty dependency array = run once on mount

  return createElement("div", null, `Time: ${time}`);
};

createContext & useContext

function createContext<T>(defaultValue: T): Context<T>;
function useContext<T>(context: Context<T>): T;

Context API for passing data through component tree without prop drilling.

Example:

const ThemeContext = createContext("light");

const ThemedButton = () => {
  const theme = useContext(ThemeContext);
  return createElement(
    "button",
    { style: { background: theme === "dark" ? "#333" : "#fff" } },
    "Themed Button"
  );
};

const App = () => {
  return createElement(
    ThemeContext.Provider,
    { value: "dark" },
    createElement(ThemedButton)
  );
};

createPortal

function createPortal(
  children: MiniReactElement,
  container: HTMLElement
): PortalElement;

Renders children into a different DOM container while maintaining React tree relationships.

Example:

const Modal = ({ children }: { children: MiniReactElement }) => {
  const modalRoot = document.getElementById("modal-root")!;
  return createPortal(children, modalRoot);
};

Fragment

const Fragment: symbol;

Component for grouping multiple children without adding extra DOM nodes.

Example:

const ItemList = () => {
  return createElement(
    Fragment,
    null,
    createElement("li", null, "Item 1"),
    createElement("li", null, "Item 2")
  );
};

JSX Runtime Functions

function jsx(type: any, props: any, key?: string): MiniReactElement;
function jsxs(type: any, props: any, key?: string): MiniReactElement;
function jsxDEV(
  type: any,
  props: any,
  key?: string,
  isStaticChildren?: boolean,
  source?: any,
  self?: any
): MiniReactElement;

JSX runtime functions for transpiled JSX syntax. These are automatically used by build tools and shouldn't be called directly.

useRef

function useRef<T>(initialValue: T): MutableRefObject<T>;

interface MutableRefObject<T> {
  current: T;
}

Hook for creating mutable references that persist across re-renders without triggering re-renders when changed. Useful for DOM references and storing mutable values.

Example:

const InputComponent = () => {
  const inputRef = useRef<HTMLInputElement | null>(null);
  const renderCountRef = useRef(0);

  // Track renders without causing re-renders
  renderCountRef.current += 1;

  const focusInput = () => {
    if (inputRef.current) {
      inputRef.current.focus();
    }
  };

  return createElement(
    "div",
    null,
    createElement("input", { ref: inputRef, type: "text" }),
    createElement("button", { onClick: focusInput }, "Focus Input"),
    createElement("p", null, `Render count: ${renderCountRef.current}`)
  );
};

useReducer

function useReducer<State, Action>(
  reducer: (state: State, action: Action) => State,
  initialState: State
): [State, (action: Action) => void];

function useReducer<State, Action, Init>(
  reducer: (state: State, action: Action) => State,
  initialArg: Init,
  init: (arg: Init) => State
): [State, (action: Action) => void];

Hook for managing complex state with a reducer function. Ideal for state that involves multiple sub-values or complex update logic.

Example:

interface CounterState {
  count: number;
  step: number;
}

type CounterAction =
  | { type: "INCREMENT" }
  | { type: "DECREMENT" }
  | { type: "SET_STEP"; payload: number }
  | { type: "RESET" };

const counterReducer = (
  state: CounterState,
  action: CounterAction
): CounterState => {
  switch (action.type) {
    case "INCREMENT":
      return { ...state, count: state.count + state.step };
    case "DECREMENT":
      return { ...state, count: state.count - state.step };
    case "SET_STEP":
      return { ...state, step: action.payload };
    case "RESET":
      return { count: 0, step: 1 };
    default:
      return state;
  }
};

const Counter = () => {
  const [state, dispatch] = useReducer(counterReducer, { count: 0, step: 1 });

  return createElement(
    "div",
    null,
    createElement("h3", null, `Count: ${state.count}`),
    createElement(
      "button",
      { onClick: () => dispatch({ type: "INCREMENT" }) },
      "+"
    ),
    createElement(
      "button",
      { onClick: () => dispatch({ type: "DECREMENT" }) },
      "-"
    ),
    createElement(
      "button",
      { onClick: () => dispatch({ type: "RESET" }) },
      "Reset"
    )
  );
};

Testing

The project uses Bun as the test runner with happy-dom for DOM simulation.

Running Tests

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run specific test file
bun test tests/MiniReact.render.test.ts

# Run tests with coverage
bun test --coverage

Test Structure

tests/
├── MiniReact.render.test.ts              # Basic rendering tests
├── MiniReact.functional-components.test.ts # Component tests
├── MiniReact.reconciliation.test.ts      # Virtual DOM reconciliation
├── MiniReact.hooks.test.ts               # Hook implementations
├── MiniReact.events.test.ts              # Event system tests
├── MiniReact.context.test.ts             # Context API tests
├── MiniReact.portals.test.ts             # Portal functionality
├── MiniReact.fragments.test.ts           # Fragment rendering
└── MiniReact.jsx.test.ts                 # JSX runtime tests

Test Coverage

Current test coverage: 261 tests covering:

✅ Element creation and rendering
✅ Functional component composition
✅ Virtual DOM reconciliation algorithms
✅ Hook lifecycle and state management (useState, useEffect, useContext, useRef, useReducer)
✅ Event handling and cleanup
✅ Context propagation and updates
✅ Portal rendering and event bubbling
✅ Fragment reconciliation
✅ JSX syntax and runtime functions
✅ Edge cases and error conditions
✅ Performance and memory leak prevention

Code Quality

Linting and Formatting

The project uses Biome for linting and code formatting:

# Check code quality
bunx biome check

# Fix auto-fixable issues
bunx biome check --apply

# Format code
bunx biome format --write .

TypeScript Configuration

Full TypeScript support with strict type checking:

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "jsxImportSource": "./src/MiniReact"
  }
}

Development Workflow

Write Tests First: Follow TDD approach with comprehensive test coverage
Type Safety: Use TypeScript for all code with strict type checking
Code Quality: Run Biome checks before committing
Documentation: Keep README and code comments updated
Performance: Profile and optimize critical paths

Contributing

Development Setup

Clone the repository:

git clone https://github.com/MarcelOlsen/mini-react.git
cd mini-react

Install dependencies:

bun install

Run tests:

bun test --watch

Start developing and follow the phase-based approach!

Contribution Guidelines

Follow the established phase structure
Write comprehensive tests for new features
Maintain TypeScript type safety
Use consistent code formatting (Biome)
Document new APIs and patterns
Focus on educational value and code clarity

Phase Development Process

Plan: Review phase specifications and requirements
Test: Write comprehensive tests for the new functionality
Implement: Build the feature with focus on clarity and correctness
Validate: Ensure all tests pass and code quality standards are met
Document: Update README, API documentation, and examples
Review: Code review focusing on educational value and best practices

License

MIT License - feel free to use this project for learning and educational purposes.

Happy Coding! 🚀

Building React from scratch, one phase at a time.

Name		Name	Last commit message	Last commit date
Latest commit History 205 Commits
.changeset		.changeset
.github/workflows		.github/workflows
.trae/rules		.trae/rules
example		example
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CHANGESETS.md		CHANGESETS.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
bun.lock		bun.lock
bunfig.toml		bunfig.toml
index.ts		index.ts
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

License

MarcelOlsen/mini-react

Folders and files

Latest commit

History

Repository files navigation

MiniReact

Table of Contents

Overview

Current Status

Quick Start

Prerequisites

Installation

Installation

Basic Usage

Running Tests

JSX Usage (New!)

Advanced Usage Examples

Portal Usage

Fragment Usage

Features

🌟 Core React-Like Functionality

🎨 Advanced Capabilities

📋 Testing & Quality

Project Structure

Development Phases

🚀 ALPHA RELEASE TRACK (Phases 1-11)

Phase 1: Element Creation & Basic Rendering ✅

Phase 2: Functional Components ✅

Phase 3: Virtual DOM & Basic Reconciliation ✅

Phase 4: Prop Diffing & Efficient Children Reconciliation ✅

Phase 5: State with useState Hook ✅

Phase 6: Event Handling ✅

Phase 7: Effects with useEffect ✅

Phase 8: Context API ✅

Phase 9: Portals and Fragments ✅

Phase 10: JSX Support ✅

Phase 11: Essential Hooks (useRef & useReducer) ✅

🎉 ALPHA RELEASE v0.1.0 - Complete Core React-like Functionality

🚀 STABLE RELEASE TRACK (Phases 12-20)

Phase 12: Performance Optimization Suite ✅

Phase 13: Error Boundaries & Resilience

Phase 14: Async Features & Suspense

Phase 15: Concurrent Features (Advanced)

Phase 16: Developer Experience

Phase 17: Server-Side Rendering

Phase 18: Advanced Component Patterns

Phase 19: Testing & Quality Assurance

Phase 20: Production Optimizations

🎯 STABLE RELEASE v1.0.0 - Production-Ready React Alternative

API Reference

createElement

render

Functional Components

useState

useEffect

createContext & useContext

createPortal

Fragment

JSX Runtime Functions

useRef

useReducer

Testing

Running Tests

Test Structure

Test Coverage

Code Quality

Linting and Formatting

TypeScript Configuration

Development Workflow

Contributing

Development Setup

Contribution Guidelines

Phase Development Process

License

About

Resources

License

Uh oh!

Stars

Packages