DOCSEARCHbyAlgolia
Submit Docs

Refract Documentation

website·Indexed 29 days ago

https://refract-stg.netlify.app

A lightweight framework for building reactive UIs. Features include a reactivity system with `useRefraction()`, a component-based architecture using `createComponent()`, and state transformation tools such as Optics and Lenses. Includes guides on lifecycle hooks, performance optimization, TypeScript support, and extending the framework via custom routers, compilers, and plugins.

Tokens
19.9K
Snippets
103
Records
148
Agent score
75%

What's inside Refract

  1. Overview of Refract Framework

    Refract is a reactive, composable, and optics-powered JavaScript framework for building user interfaces. It focuses on modularity and developer experience, utilizing a state model based on 'Refractions' and 'Optics' to create predictable and scalable UIs with automatic reactivity.

  2. Overview of Refract framework

    Refract is a JavaScript framework designed for building reactive user interfaces using optics (a functional programming concept). It provides a unique approach to state management and data flow control. Note: Refract is currently a learning project for the Technical Writers Mentorship Program (TWMP) and is not intended for production use.

  3. Overview of Refract Optics

    Optics in Refract are reusable "views" or state transformers that allow developers to focus on, transform, and reuse specific slices of application state without duplicating logic. They decouple the physical structure of the state from the component logic, allowing components to subscribe to a transformed view of the state rather than the raw state object. Updates flow both ways if the optic supports writing.

  4. Manage reactive state with Refractions

    A Refraction is the fundamental reactive state unit in Refract. It acts as a container for data and automatically notifies dependent parts of the application when that data changes, combining state management with built-in optical capabilities.

  5. Recommended learning path for Refract

    New developers should follow this sequence to learn the framework:

    1. Introduction: High-level overview.
    2. Quick Start: Build the first app.
    3. Core Concepts: Understand refractions and optics.
    4. Counter App Tutorial: Practical introduction to refractions.
    5. Mouse Tracker Tutorial: Learn optics in action.
    6. Global Theme Switcher Tutorial: Manage global state and side effects.

  6. Handle Side Effects in Refract

    Effects (or Side Effects) are operations that interact with the external world, such as API calls, DOM manipulations, or subscriptions. Refract provides a dedicated effect system to ensure these operations remain predictable and testable.

  7. Create Nested Lenses for deep state access

    Lenses can be chained by creating a new lens from an existing lens. This allows you to drill deeper into the state hierarchy while keeping re-renders minimal, as the final lens only cares about its specific slice.
    const userLens = createLens(appState, state => state.user);
const nameLens = createLens(userLens, user => user.name);

  8. Extend Refract via Plugins and the Compiler

    Refract can be extended using Plugins to add new functionality or integrate external libraries. Additionally, the Refract Compiler optimizes performance and enables advanced features by processing code under the hood.

  9. Understand the Refract Compiler architecture

    The Refract compiler transforms declarative code (JSX, templates, etc.) into optimized JavaScript through a three-step process:

    1. Parsing: Source code is converted into an Abstract Syntax Tree (AST), a structured representation of the code.
    2. Transformation: The compiler traverses the AST to convert JSX/templates to function calls, optimize reactive expressions, and handle scoped styles.
    3. Code Generation: The transformed AST is converted back into executable JavaScript optimized for the browser.

  10. Understand the purpose of Lenses in Refract

    In Refract, a lens is a tool used to focus on a specific part of a larger state. This allows a developer to read and update a slice of state without interacting with or accidentally modifying unrelated data. Lenses help keep components smaller and more focused by ensuring they only observe the data they specifically require.

  11. Extend Refract functionality via Plugins, Router, and Compiler

    Refract is designed to be lightweight and extensible. Depending on the project requirements, developers can extend the framework in three primary ways:

    1. Plugins: Used to package reusable features (e.g., global theming, analytics integration) and share logic across multiple apps or design systems. Plugins can hook into components, extend lifecycles, and expose new utilities.
    2. Router: Refract does not include a built-in router by default. This allows developers to implement a custom routing solution that integrates with Refract's reactive model, often utilizing optics for state scoping and composition.
    3. Compiler Customization: Advanced build-layer customization used to add custom syntax sugar, implement performance optimizations, or integrate build-time checks. This is typically used when building a framework on top of Refract or requiring deep-level control over how code is transformed for the browser.

  12. Understand Refract core architectural concepts

    Refract is built on a hierarchy of state management and UI components:

    • Apps serve as the top-level containers that hold components.
    • Components manage their state using refractions.
    • Refractions are manipulated via optics, which include lenses, prisms, and traversals.
    • Optical composition allows developers to combine multiple optics to perform complex state transformations.
    • The lifecycle API is used to manage effects and define component behavior.
    • The framework supports extensibility through plugins and provides built-in performance optimizations.