alpinejs-app

A Simplest Single Page Application (SPA) library for Alpine.js.

The Vision

• To maintain a clear separation between HTML and JavaScript logic.

  This separation keeps presentation distinct from logic as much as possible and have as few abstractions as possible.

  Develop layout with HTML/CSS and the logic with Alpine.js for two-way data bindings and reactivity.

• To have some kind of central registry of HTML templates and Javascript classes and use it to register components.

  The registry is just 2 properties in the global app object, app.templates and app.components.

  Server-side rendering of templates (similar to htmx) is supported out of the box, same directives render bundled or remote HTML templates the same way without any external dependencies.

  How the registry is delivered to the browser depends on bundling or application, for example:

  Native support:

  • esbuild: use builtin loader to import .html files as text and inject into app.templates
  • esbuild: bundle everything into a single file by importing multiple JS/HTML files: see scripts/build-app.js for a simple esbuild plugin
  • server-side: maintain HTML files on the server to load individually on demand using the same directives, see examples/dashboard.html.

  More ideas:

  • keep HTML templates in JSON files to load separately via fetch on demand or via importmap
  • include your .js files in the HTML for small apps and let the browser to handle caching

New directives

<div x-template="template"></div>

<div x-template="show ? 'index' : ''"></div>

<div x-template.cache="show ? '/path/index.html' : ''"></div>

<a x-render="'hello/hi?reason=World'">Show hello component with params</a>

<button @click="toggle">Call the toggle method in the current component</button>

<button x-render="'index?$target=#div'">Show Bundled or Cached by ID</button>

<button x-render.cache="'/index.html?$target=#div'">Show External File</button>

Component class

app.components.hello = class extends app.AlpineComponent {
    template = ""

    onCreate() {

    }

    onDelete() {

    }

    onToggle(data) {
        console.log("received toggle event:", data)
    }

    toggle() {
        this.template = !this.template ? "example" : "";

        app.emit(app.event, "toggle", this.template)
    }
}

Features

• Components: These are the primary building blocks of the UI. They can be either standalone HTML templates or HTML backed by JavaScript classes, capable of nesting other components.

• Main Component: Displays the current main page within the #app-main HTML element. It manages the navigation and saves the view to the browser history using app.savePath.

• History Navigation: Supports browser back/forward navigation by rendering the appropriate component on window popstate events, achieved using app.restorePath.

• Direct Deep-Linking: For direct access, server-side routes must redirect to the main app HTML page, with the base path set as ‘/app/’ by default.

Getting started

Visit the tutorial.

Full documentation

Visit the documentation.

Live demo

Available at demo.

External rendering is not working due pages only serving static content, local demo shows server-side rendering.

Author

Vlad Seryakov

License

Licensed under MIT

This site is open source. Improve this page.