Get Started

Introduction

Magos is a JS library for state management that compact, scalable, maintainable, and easy-to-use.

It helps you control states easily with concise code and operate a neat structure. Additionally, it helps you control data type safety and minimize errors.

Why Magos?

Magos was built to solve the complexity of large-scale state management while keeping the developer experience (DX) lightweight and intuitive.

Key Features

Compact Structure: No boilerplate, just focus on your logic.
Type Safety: Built with TypeScript from the ground up.
Scalable: Perfect for both small apps and large enterprise systems.

Quick Start

You can start to use the Magos and setup quickly here.

Installation

Magos is available as a package on NPM. You can integrate it into your project using any of the major package managers:

pnpm add magos

npm install magos

yarn add magos

bun add magos

Box is a concept used to declares slice in Magos. It checks and registers initial state and actions (action factory). Then it returns a function to get the new state, an action factory and a subcribe function.

import { createBox } from "magos"

const initialState = 0

export const counterBox = createBox(initialState, (set) => ({
  inc: () => set(prev => prev + 1),
}))

Then create a store

Store helps you register and manage the boxes you created.

import { createStore } from "magos"
import { counterBox } from "./boxes/counterBox"

export const store = createStore({
  counter: counterBox,
})

Finally bind your components

For React

You can use the hook anywhere without provider. Do you remember how to use useState? This question makes you imagine how Magos would use his hook, right? When your selected state changes, only the consuming components will re-render.

import { useAppStore } from "magos/react"
import { store } from "@/store/store"

function SheepCounter() {
  const [count] = useAppStore(store.counter)

  return <h1>`I have ${count} sheep on my farm`</h1>
}

function SheepCountAction() {
  const [,setCount] = useAppStore(store.counter)

  return <button onClick={setCount.inc}>Count</button>
}

Note

Do you remember how to use useState? This question alone helps you imagine how Magos works, right?

For Vanilla

If you're using Vanilla JS, use the unbox method to automatically synchronize your state with DOM elements. It handles state selection, UI updates, and provides a cleanup mechanism.

import { unbox } from "magos/vanilla"
import { store } from "@/store/store"

/**
 * 1. Synchronizing State to UI
 * Magos will automatically update the #sheep-display content
 */
export function setupSheepCounter() {
  const element = document.querySelector("#sheep-display")

  // unbox returns [state, actions, unsubscribe]
  const [, , unsub] = unbox(
    store.counter, 
    element, 
    (state) => `I have ${state} sheep on my farm`
  )

  // Call unsub() to stop updates when the element is removed
  return unsub 
}

/**
 * 2. Handling Actions
 * Access actions directly to bind events to your UI
 */
export function setupSheepCountAction() {
  const element = document.querySelector("#count-button")
  
  // We just need to get the actions for handling events
  const [, actions] = unbox(store.counter, element)

  const handleIncrement = () => actions.inc()
  element.addEventListener('click', handleIncrement)

  // Clean up both the Event Listener and the Unbox subscription
  return () => {
    element.removeEventListener('click', handleIncrement)
    unsub() // Always clean up to prevent memory leaks!
  }
}