single-spa-alpinejs
single-spa-alpinejs is a helper library for mounting alpinejs components as single-spa applications or parcels.
#
InstallationAlternatively, you can use single-spa-alpinejs from a CDN as a global variable:
Note that you might want to lock down the package to a specific version. See here for how to do that.
#
Usage- There are three ways the you can define AlpineJS components as single-spa applications or parcels.
#
1 - Template Only- The simplest way where the template contains all the required data and initialization logic (including
x-data
andx-init
) as part of the dom. The template is provided via the options attributetemplate
x-data
#
2 - Template with externally defined - You could also provide
x-data
externally and the helper will add it to the component.- The
x-data
can be provided in the following forms (via the options attributexData
)- an object
- a function that returns an object
- a function that returns a promise which resolves with an object.
- The
x-data
with x-init
#
3 - Template with externally defined You can also provide
x-init
externally along with thex-data
and the helper will add it to the component.The
x-init
can be provided in the following forms (via the options attributexInit
) and needs to be a function.Please note the
xData
attribute must be provided otherwise thexInit
attribute will be ignored.The sample below references the example from the Alpine Toolbox - Alpine JS and fetch() and demonstrates how you can use the
xInit
andxData
attributes to create an AlpineJS application .
#
Usage Examples#
1 - Template Only#
Via cdnExample usage when installed via CDN:
- The usage is similar and once the library is loaded it will be available globally and accessed via the
window
object.
x-data
#
2 - Template with externally defined x-data
with x-init
#
3 - Template with externally defined #
API / Optionssingle-spa-html is called with an object that has the following properties:
template
(required): An HTML string or a function that returns a string. The function will be called with the single-spa custom props. The returned string is injected into the DOM during the single-spa mount lifecycle.domElementGetter
(optional): A function that returns the dom element container into which the HTML will be injected. If omitted, a default implementation is provided that wraps the template in a<div>
that is appended todocument.body
.xData
(optional): An object or a function or a function that returns a promise.The returned string is injected into the DOM as thex-data
attribute during the single-spa mount lifecycle.xInit
(optional): A function or a function that returns a promise. The function provided is added to the global scope and the function initiation along with the root dom element id as a parameter is injected into the DOM as thex-init
attribute during the single-spa mount lifecycle. Please note thexData
attribute must be provided otherwise thexInit
attribute will be ignored. The function you providexInit
#
xData and xInit HandlingThis section covers the details of how
xData
andxInit
option attributes are processed by the single spa helper.Consider the example below
The helper does the following
- Adds the template to the dom wrapped in
parent dom element
with and id that has a prefix ofalpine
. In this case it will beid='alpine-myapp'
- Attaches a resolved
xData
as a stringx-data="{ "name": "myapp" ,"open": false }"
to theparent dom element
. - It will make the user defined
appXInitFn
available globally as an attribute ofwindow.singleSpaAlpineXInit
and will be accessible via variablewindow.singleSpaAlpineXInit.myapp
- Attaches a resolved
xInit
as a string that calls the globally defined variablex-init="singleSpaAlpineXInit.myapp('alpine-myapp')"
to theparent dom element
. - Note that this also passes
id
of theparent dom element
which can then be used to access the alpine data elements to update the state as required.
#
Special characters in the application names- You may have special characters in the application name for example
@my/app
. See the example below
The single spa helper converts these to valid
global
function names byreplacing
all the special characters
with underscores (_
). This does not require any special handling from the user as the helper takes care of this internallyIn the above case the
xInit
dom element would look like the followingx-init="singleSpaAlpineXInit._my_app('alpine-@my/app')"
where thexInit
function is available as aglobal
variable_my_app
.
- Adds the template to the dom wrapped in