Introduction to Refract

Welcome to Refract Docs

What is Refract?

Refract is a modern JavaScript framework designed to help developers build scalable, reactive user interfaces with an intuitive developer experience. Inspired by React's component model and state management principles, Refract introduces a novel concept called "refractions"—a declarative way to describe UI behavior and state transitions based on reactive data flows.

While sharing conceptual similarities with React (components, hooks, virtual DOM), Refract reimagines the developer experience with several key innovations:

Refract encourages pure function-driven UIs, uses refractive signals (similar to Svelte's stores or Solid.js signals), and introduces optical composition—modular patterns for UI logic reuse.

Quick Start

Here's a simple counter that shows Refract's components:

Your First Refract Component

import { createComponent } from "refract";

const Counter = createComponent(({ lens }) => {
  const count = lens.useRefraction(0);

  return (
    <button onClick={() => count.set(count.value + 1)}>
      Clicked {count.value} times
    </button>
  );
});

export default Counter;

Result

That's it, The count state automatically updates the UI when you click the button.

Why Choose Refract?

1. Reactive by Design : Built from the ground up with reactivity in mind. State changes automatically propagate through your component tree with optimal performance

2. Composable Architecture : Create reusable logic patterns with optical composition. Share stateful logic between components without complex patterns.

3. Developer Experience : Intuitive APIs, excellent TypeScript support, and clear error messages make development a joy.

Core Concepts Overview

Refract is built around five fundamental concepts that work together to create a powerful and intuitive development experience:

Components

Pure functions that return JSX, created with createComponent(). The building blocks of your Refract application.

→

Refractions

Reactive units of state that automatically update the UI when changed. Similar to signals or refs in other frameworks.

→

Lenses

The bridge between props, refractions, and effects. Provide scoped access to component state and lifecycle.

→

Optical Composition

Reusable logic patterns with dependency-aware caching and animation-aware transitions.

→

Side Effects

Controlled effects with useEffect, useOptic, and useFlash for clear, predictable behavior.

→

How to use the docs

The docs are organized into 3 sections:

1. Getting Started: Step-by-step guides to help you create and deploy a new application.

2. Guides: Tutorials on specific use cases, choose what's relevant to you.

3. API Reference: Detailed technical reference for every feature.

4. Core Concepts: Detailed explaination on Refract's core concepts.

Use the sidebar to navigate through the sections, or search (Ctrl+K or Cmd+K) to quickly find a page.

Community & Support

Join the growing Refract community:

• GitHub: github.com/refract-js/refract - Source code, issues, and contributions
• Discord: discord.gg/refract - Community chat and support
• Twitter: @RefractJS - Updates and announcements
• Stack Overflow: Tag your questions with refract-js

---

Ready to start building with Refract? Get started now →