بدون توضیح

Ryan Chandler d5a4af6aa6 tests		4 سال پیش
.github	5ed0ac1003 chore(workflow0	5 سال پیش
dist	0cbf855eda fix(allow methods to be stored on persisted stores)	4 سال پیش
examples	0cbf855eda fix(allow methods to be stored on persisted stores)	4 سال پیش
src	0cbf855eda fix(allow methods to be stored on persisted stores)	4 سال پیش
tests	d5a4af6aa6 tests	4 سال پیش
.gitignore	0681917e03 wip	4 سال پیش
LICENSE.md	9436518c08 Create License file	5 سال پیش
README.md	80c7bda976 Update README.md	4 سال پیش
babel.config.js	cb5e7ccd65 chore(tests)	5 سال پیش
jest.config.js	326c804bf2 tests()	5 سال پیش
package.json	061be1a412 1.1.1	4 سال پیش
yarn.lock	bfedb49e7e Bump bl from 4.0.2 to 4.0.3	4 سال پیش

✨ Help support the maintenance of this package by sponsoring me.

🌲 Spruce

A lightweight state management layer for Alpine.js

About

Many large frameworks have their own state management solutions. One thing these libraries have in common is a higher level of complexity and a wide range of API interactions. Since Alpine.js is designed to be a simpler and lighter alternative to larger frameworks such as Vue and React, shouldn't the state management solution be as simple, if not simpler, too?

Installation

CDN

Include the following <script> tag in the <head> of your document:

<script src="https://cdn.jsdelivr.net/npm/@ryangjchandler/spruce@1.x.x/dist/spruce.umd.js"></script>

Important: This must be added before loading Alpine.js when using CDN links.

Manual

If you wish to include Spruce with your own bundle:

yarn add @ryangjchandler/spruce

or:

npm install @ryangjchandler/spruce --save

Then add the following to your script:

import Spruce from '@ryangjchandler/spruce'

Quick start

To verify you have correctly installed Spruce, copy & paste the following code snippet into your project.

<div x-data>
    <div x-show="$store.modal.open === 'login'">
        <p>
            This "login" modal isn't built with a11y in mind, don't actually use it
        </p>
    </div>
</div>

<div x-data>
    <div x-show="$store.modal.open === 'register'">
        <p>
            This "register" modal isn't built with a11y in mind, don't actually use it
        </p>
    </div>
</div>

<div x-data>
    <select x-model="$store.modal.open">
        <option value="login" selected>login</option>
        <option value="register">register</option>
    </select>
</div>

<script>
    Spruce.store('modal', {
        open: 'login',
    });
</script>

To see what the code should do, use this CodePen. Thanks @HugoDF!

Usage

Spruce exposes less than a handful of possible interaction points. There is an extremely simple "subscriptions" interaction which connects the roots from your Alpine component to the global store, then there is the "stores" interaction which allows you to define scopes of global state for use throughout your components.

Entry point

If you are using the CDN build, you can interact with Spruce using the window.Spruce variable:

<script>
    Spruce.store('modals', {
        open: 'login',
    })
</script>

If you are importing Spruce into your own bundle, you can interact with it like any other variable:

store.js

import Spruce from '@ryangjchandler/spruce'

Spruce.store('modals', {
    open: 'login'
})

export default Spruce

app.js

import './store'
import 'alpinejs'

Note: You must import your store before Alpine.

Subscribing your components

Spruce hooks into Alpine using the "magic properties" API, meaning there are no extra steps needed. Start using the $store variable in your components right away.

<div x-data="{}">
    <span x-text="$store.application.name"></span>
</div>

Defining global state

To define a piece of global state, you can use the Spruce.store() method:

Spruce.store('application', {
    name: 'Amazing Alpine Application'
})

The first argument defines the top level property of the scope. The second argument defines the state for the scope, it could be a string, integer or object with nested properties.

To access the name property, you can do the following inside of your component:

<div x-data="{}">
    <span x-text="$store.application.name"></span>
</div>

The <span> will now have "Amazing Alpine Application" set as its innerText .

Modifying state from outside of Alpine

You can modify your global state from external scripts using the Spruce.store() method too:

Spruce.store('application', {
    name: 'Amazing Alpine Application'
})

Spruce.store('application').name = 'Amazing Spruce Integration'

This will trigger Alpine to re-evaluate your subscribed components and re-render.

Resetting global state

A Spruce.reset() method is provided so that you can completely overwrite a global store:

Spruce.store('application', {
    name: 'Amazing Alpine Application'
})

Spruce.reset('application', {
    name: 'Reset Application'
})

Calling the reset method will make the new state reactive and cause subscribed components to re-render.

In the above snippet, when we change the value of form.email either from a component or externally in a separate JavaScript file, our callback will be invoked and will receive the old value, as well as the new value. This can be useful for running automatic inline validation when a property changes, or triggering an action elsewhere in another component without the need for dispatching events.

Note: you can get stuck in an watch loop if you're updating other store properties that also have watchers defined.

Versioning

This projects follow the Semantic Versioning guidelines. This means that there could be breaking changes on minor version changes, up until v1.x is reached.

For example, 0.1 -> 0.2 might introduce a breaking change.

License

Licensed under the MIT license, see LICENSE.md for details.

README.md