Improve documentation for installation as a module

[docdunning]

I have been trying out building Alpine into a bundle - so far so good. However, I struggled today with an error 'Uncaught ReferenceError: Alpine is not defined, and it would help relative newbies like me if the docs could be a little more helpful.

Here's an example given at https://alpinejs.dev/globals/alpine-store#registering-a-store

import Alpine from 'alpinejs'
Alpine.store('darkMode', {
    on: false,
    toggle() {
        this.on = ! this.on
    }
})
Alpine.start()

When bundled, this works OK, and the store can be used just fine. And any components with inline x-data directives work as well.

But now I want to move the component state into a script , like this:

<script>
    document.addEventListener('alpine:init', () => {
        Alpine.data('app', () => ({
... etc ... 

But it doesn't work - I just get the Alpine is not defined error.

The cause (which it took me a long while to discover) is that this line is missing from the module:

window.Alpine = Alpine

To be fair, the page at https://alpinejs.dev/essentials/installation#as-a-module does show that line. But it goes on to say that it's optional, and mentions tinkering with Alpine from the devtools as one reason you might include it.

I suggest that you make it clear that this line should probably always be included, and particularly that if you intend to use the Alpine.data() function, you must include it.

[ekwoka]

This isn't really true though.

But this is all in how modules work not anything to do with Alpine.

You can still do script tags without defining it on the window.

You can just do

<script type="module">
  import Alpine from 'alpinejs'
  
  Alpine.data('app' ()=>({}))
</script>

Then have at the end of the body

<script type=module>
  import Alpine from 'alpinejs'

  Alpine.start()
</script>

[docdunning]

But this is all in how modules work not anything to do with Alpine.

Well, I guess that's true. All I'm saying is that it took me a long while to work out why things weren't working, and I had just followed the Alpine docs.

[ekwoka]

There is a lot to the discussion of "How much fundamental JS knowledge should the docs assume developers have?".

The best way is probably to, when these issues come up, make a PR to add some of that info that people get stuck on as it happens.

[docdunning]

make a PR to add some of that info that people get stuck on

OK, although I don't know how I would do that. Is there a repo for the docs, or am I (yet again) missing something?

[ekwoka]

This repo has the docs in it.

[docdunning]

Thanks, I see that now.