mrwolfz / simplux

simplux - simple, scalable state management for web applications

simplux - simple, scalable state management for web applications

simplux is state management as it should be: simple to use, no boilerplate, type-safe but not verbose, and with excellent testability. simplux provides out-of-the-box support for React and Angular, but can be used with any framework.

Quickstart

npm i @simplux/core -S

import { createSimpluxModule, createMutations, createSelectors } from '@simplux/core'

// state in simplux is contained in modules identified by a unique name
const counterModule = createSimpluxModule('counter', { value: 0 })

export const counter = {
  ...counterModule,

  // use mutations to modify the state
  ...createMutations(counterModule, {
    increment(state) {
      state.value += 1
    },
    incrementBy(state, amount: number) {
      state.value += amount
    },
  }),

  // use selectors to access the state
  ...createSelectors(counterModule, {
    value: (state) => state.value,
    plus: (state, amount: number) => state.value + amount,
  }),
}

counter.increment()
console.log('incremented counter:', counter.value())
console.log('counter value + 2:', counter.plus(2))

counter.incrementBy(5)
console.log('incremented counter by 5:', counter.value())

See this example in action here. For a more detailed look into how simplux can make your life simple follow our recipe for getting started.

React

npm i @simplux/core @simplux/react -S

import { SimpluxProvider, useSimplux } from '@simplux/react'
import React from 'react'
import { render } from 'react-dom'
import { counter } from './counter.module'

const Counter = () => {
  const value = useSimplux(counter.value)
  const valuePlusFive = useSimplux(counter.plus, 5)

  return (
    <>
      <span>value: {value}</span>
      <br />
      <span>value + 5: {valuePlusFive}</span>
      <br />
      <button onClick={counter.increment}>Increment</button>
      <br />
      <button onClick={() => counter.incrementBy(5)}>Increment by 5</button>
    </>
  )
}

const App = () => (
  <SimpluxProvider>
    <Counter />
  </SimpluxProvider>
)

render(<App />, document.getElementById('root'))

See this example in action here. For a more detailed look into how simplux can power up your React application follow our recipe for using simplux in your React application.

Angular

See the recipe for using simplux in your Angular application.

Recipes

Instead of traditional documentation simplux has these recipes that will show you how it can make life simple for you. Each recipe will help you solve one particular task that you will typically face during development.

For every "How do I do X?" you have ever asked yourself, there should be a recipe here. If you find one that is missing, please let us know by creating an issue or even better, provide the recipe as a pull request.

Basics

• getting started
• testing my state changes
• computing derived state
• testing derived state

Advanced

• creating non-trivial modules
• testing my code that uses mutations
• testing my code that uses modules and selectors
• reacting to state changes
• creating testable side effects (like loading data from my API)
• organizing my application state
• communicating between modules
• managing collections of entities (work-in-progress)
• composing my mutations
• composing my selectors
• routing between different views in my web application (work-in-progress)
• using simplux in my application together with Redux
• debugging with Redux DevTools

React

• using simplux in my React application
• testing my React components
• building non-trivial React applications (work-in-progress)
• using lazy loaded components/code splitting
• using hot module reloading (HMR)
• routing between different views in my React application (work-in-progress)
• using server-side rendering (SSR) (work-in-progress)
• using simplux in my React Native application (work-in-progress)
• routing between different views in my React Native application (work-in-progress)

Angular

• using simplux in my Angular application
• testing my Angular components
• building non-trivial Angular applications (work-in-progress)
• using lazy loaded routes/code splitting (work-in-progress)
• routing between different views in my Angular application (work-in-progress)

Motivation

When discovering this library your first thought may have been: "Are you kidding me, yet another state management library?" That sentiment is perfectly understandable. There are many existing options for managing your state in web applications. If you are already using one of those and it works for you, then you should probably stick with it. However, simplux brings some unique points to the table that make it a worthwhile addition to the state management ecosystem:

• excellent task-driven documentation: a lot of effort went into writing our recipes. While most other libraries have documentation that is centered around explaining what they do, our task-driven documentation is focused on showing you how simplux helps you to solve your concrete tasks. We also provide code sandboxes for every recipe that allow you to interact with the code while reading the recipe, which greatly improves the learning experience.

• strong focus on testability: testing is a very important topic that is sadly often neglected. simplux takes testability very seriously and makes sure that you know how you can test the code you have written using it (you may have noticed that the recipe immediately following getting started in the list above already shows you how you can test the code from the first recipe).

• optimized for TypeScript: simplux is built with and for TypeScript. Sometimes TypeScript code can be a bit verbose. We put a lot of effort into ensuring that the amount of type annotations in your code is minimized by leveraging type inference wherever possible. That said simplux can also be used with plain JavaScript, in which case your IDE may still use the TypeScript information to help you due to our bundled typings.

• out-of-the-box solutions for many common yet complex use-cases: Have you ever tried setting up hot module reloading or code splitting with React and Redux? It can be quite tricky. simplux aims to solve as many of these complex use-cases by providing zero-configuration out-of-the-box solutions.

• modular and extensible architecture: Our core package only contains the bare minimum that is required to use simplux. All other advanced functionality is added via extension packages. On one hand this allows you to pick and choose what functionality you want to use without paying for anything that you don't. On the other hand it allows adding new extension packages without risk of breaking any existing functionality.

Prior Art

This library was heavily inspired by Rematch and shares a lot of ideas with it.

Open points

core

• add a function that "activates" subscriptions which has to be called during app initialization
• add a resetSimplux function that resets all modules to their initial state (useful for SSR)
• add a combineSelectors utility function
• add a subscribe function to selectors to get notified of value changes

testing

• add functions to throw when calling unmocked mutations or effects

router

• add type tests
• capture navigation history
• allow going back to previously active route

browser-router

• add support for base href in history mode

• intercept click events on window and navigateToUrl for same tab target on same origin (only if within base-href)

• add navigation option for replacing browser history entry

• allow ?[, [?, &[, and [& for optional query parameters

• add navigation option for setting URL at start or end of navigation (or not at all)

• support object parameters

• add type tests

• add support for setting hash parameter in history mode

• add support for hash mode

• allow defining default values for parameters (e.g. /:id:string|defaultValue/)

• alternatively add function configuration parameter to fill in defaults dynamically (also infer correct full parameter type from return value of callback)

entities

• create package for managing collections of entities
• create default set of entity management mutations
• allow creating custom mutations that act on one entity
• create default set of selectors for entities

react

nothing

angular

nothing

misc

• docs: create website
• recipes: add example effects to recipe for creating non-trivial modules and explicitly mention mixin pattern
• build: create root jest config to run tests of all projects at once
• build: switch to eslint

Contributing

If you want to help with the development of this library please have a look at the contributing guidelines.

License

Everything in this repository is licensed under the MIT License unless otherwise specified.

Copyright (c) 2019-present Jonathan Ziller

simplux's Issues

react 18 support

any plans/schedule to support react 18?

currently i see warnings when using with react 18 cause of unmet dependencies. probably it just works with bumping those. i can try and create PR if you want.

warning " > @simplux/[email protected]" has incorrect peer dependency "react@^16.14.0".
warning " > @simplux/[email protected]" has incorrect peer dependency "react-dom@^16.14.0".