DOCSEARCHbyAlgolia
Submit Docs

Refract Documentation

website·Indexed 29 days ago

https://refractdocs.netlify.app

A lightweight library for building scalable UIs. Refract features a JSX-like template compiler, a robust routing system with navigation guards, and specialized logic units called Optics and Lenses for managing state and reusable behaviors.

Tokens
10.6K
Snippets
63
Records
95
Agent score
72%

What's inside Refract

  1. Overview of Refract Lenses

    Lenses in Refract are composable, type-safe helpers for reading and updating deeply nested props, state, and derived effects. They allow developers to focus on a specific slice of data without prop-drilling or manual mutation. Lenses maintain reactivity, meaning changes made through a lens automatically update the underlying refraction (state unit).

  2. Overview of Refract framework

    Refract is a React-inspired JavaScript framework designed to simplify state management, logic, and component architecture. It utilizes a refraction-based model to ensure predictable state flow, composability, and reactivity. Key architectural pillars include:

    • Declarative Components: Developers describe the desired UI state rather than manually manipulating the DOM; Refract handles the updates automatically.
    • Refractions: A state primitive used to track values and automatically notify dependent components when changes occur.

    Refract is designed for incremental adoptability, meaning it can be used for small tasks (adding interactivity to static HTML without a build step) or large-scale projects (building full single-page applications and managing complex state).

  3. Access state and props using Lenses

    Lenses are scope-aware helpers used to access props, effects, and state. They enable the creation of cleaner, more maintainable code by reducing boilerplate through a composable approach to state access.

  4. Understand the purpose of Optics in Refract

    Optics are composable logic units in Refract that bundle reusable behaviors into components. They combine state, side effects, and transformations, acting as a bridge between Refractions (which hold state) and Lenses (which scope state). Their primary goals are to encapsulate logic into reusable units, allow behaviors to be mixed and matched across components, and keep UI components lean by separating them from business logic.

  5. Understand and use Refractions in Refract

    Refractions are reusable lenses used to share logic and behavior across components in Refract without tight coupling. They act as read-only snapshots passed into components. While they can change between renders, they must never be mutated directly; for interactive state updates, standard state should be used instead of mutating a refraction.

  6. Synchronize components with external systems using useEffect

    The useEffect hook in Refract allows a component to perform side effects after the UI has been committed to the screen. Use it for tasks that reach beyond the render cycle, such as fetching data, subscribing to data streams, running timers/animations, or manually manipulating the DOM.
    import { useEffect } from "refract";

function WelcomeMessage() {
	useEffect(() => {
		console.log("WelcomeMessage rendered!");
	});

	return <h1>Welcome to Refract!</h1>;
}

  7. Ways to contribute to Refract

    Contributors can support Refract through several channels:

    • Bug Reporting: Open issues with reproduction steps and screenshots.
    • Documentation: Improve the docs/ folder by fixing typos or adding examples.
    • Enhancements: Propose new features or APIs via issues or discussions.
    • Plugins: Build router, compiler, or state plugins to extend functionality.
    • Testing: Write tests to increase code coverage and reliability.

  8. Understand the Refract Rendering Pipeline

    The Refract rendering pipeline manages the transition from component logic to DOM updates through four primary stages: Component Execution (running functions with props to return a virtual tree), VNode Construction (compiling JSX into lightweight virtual nodes), Diff & Reconciliation (comparing old and new trees), and the Commit Phase (applying minimal updates to the DOM).
    // Pseudo-code for reconciliation
function reconcile(oldVNode, newVNode, container) {
	if (!oldVNode) {
		mount(newVNode, container);
	} else if (oldVNode.type !== newVNode.type) {
		replaceNode(oldVNode, newVNode, container);
	} else {
		patchProps(oldVNode, newVNode);
		reconcileChildren(oldVNode.children, newVNode.children, container);
	}
}

  9. Extend navigation with Refract Router plugins

    Router plugins in Refract allow developers to extend the framework's navigation system. They are used to intercept navigation, implement custom guards, or add features such as authentication, analytics, and route transitions without modifying the core router logic.

  10. Manage reactive state with Refractions

    Refractions are reactive state units in Refract, similar to signals or stores. They are designed to keep the UI in sync with minimal effort and high performance, and they include built-in TypeScript support.

  11. Understand the Refract Compiler Pipeline

    The Refract compiler transforms JSX-like templates into efficient JavaScript render functions through a three-phase pipeline:

    1. Parse: Source code is converted into an Abstract Syntax Tree (AST).
    2. Transform: Plugins traverse and modify the AST.
    3. Generate: The optimized AST is converted into final JavaScript render functions.

  12. Understand the purpose of Refract plugins

    Plugins in Refract serve as extension points that allow developers to hook into framework internals and enhance functionality without modifying the core library. They are used to add new directives, integrate external libraries (such as i18n or analytics), customize compiler transformations, and provide reusable components and hooks.