Fără Descriere

4 Ramuri

Ryan Chandler dfd6594b15 review(todo comment link to polyfill)		5 ani în urmă
.github	c0f50b978b chore(workflow)	5 ani în urmă
dist	dfd6594b15 review(todo comment link to polyfill)	5 ani în urmă
docs	361bca332d chore(docs)	5 ani în urmă
examples	d71d270cee tests(set)	5 ani în urmă
src	dfd6594b15 review(todo comment link to polyfill)	5 ani în urmă
tests	e7196d2c49 tests(on and emit tests)	5 ani în urmă
.gitignore	9900bd4260 build	5 ani în urmă
CHANGELOG.md	2c1bf7baf8 fix(changelog header)	5 ani în urmă
LICENSE.md	9436518c08 Create License file	5 ani în urmă
README.md	ce50fb14a7 docs	5 ani în urmă
babel.config.js	cb5e7ccd65 chore(tests)	5 ani în urmă
jest.config.js	326c804bf2 tests()	5 ani în urmă
package.json	326c804bf2 tests()	5 ani în urmă
yarn.lock	326c804bf2 tests()	5 ani în urmă

🌲 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/gh/ryangjchandler/spruce@0.x.x/dist/spruce.umd.js"></script>

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

Manual (coming soon)

If you wish to include Spruce with your own bundle:

yarn add @ryangjchandler/spruce

Then add the following to your script:

import Spruce from '@ryangjchandler/spruce'

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 from './store'
import 'alpinejs'

Note: You must import your store before Alpine.

Subscribing your components

To access the global state from your Alpine components, you can simply add the x-subscribe directive to your root component.

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

This directive adds a new $store magic variable to your component. This can be used to "get" and "set" data in your global store.

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="{}" x-subscribe>
    <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 object:

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

Spruce.stores.application.name = 'Amazing Spruce Integration'

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

Removing the need for `x-subscribe`

Alpine offers a Config API. Using this API, you can enable an experimental global $store variable that is declared on the window object. This means your components do not need to manually "subscribe" to state changes:

<script>
    Spruce.config({
        globalStoreVariable: true
    })
</script>

<div x-data>
    <span x-text="$store.foo.bar"></span>
</div>

Important: This feature is highly unoptimized at the moment and will actually cause all of your Alpine components on the page to re-render. This is due to the limited API that Alpine exposes to third party libraries and the $store variable has no simple way of knowing which element is currently retrieving data from the global store.

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