Skip to content
alacris-go

Installation

  1. Add the module.

    Terminal window
    go get github.com/bmartel/alacris-go

    The alacris runtime is vendored inside it, so there is nothing to install from npm and no JavaScript build step to add.

  2. Serve the runtime.

    mux := http.NewServeMux()
    mux.Handle("/_alacris/", alacris.RuntimeHandler())

    The handler resolves requests by file name, so it works at any mount point and needs no http.StripPrefix.

  3. Put the script tags in <head>.

    import "github.com/bmartel/alacris-go/ui"
    What Scripts renders
    return alacris.Scripts(alacris.Config{
      Modules: []string{"/web/components.js"},
      Version: "2026.08.08",
    })
    renders verified by go test 
    <script type="importmap">
      {"imports":{"alacris":"/_alacris/alacris.js?v=2026.08.08","alacris/context":"/_alacris/context.js?v=2026.08.08","alacris/signal":"/_alacris/signal.js?v=2026.08.08","alacris/store":"/_alacris/store.js?v=2026.08.08"}}
    </script>
    <script type="module" src="/web/components.js"></script>

    The import map has to precede the first module import.

    templ layout() {
        <html>
            <head>
                @ui.Pending()
                @alacris.Scripts(alacris.Config{
                    UI:      true, // Material Design 3 catalog + theme
                    Modules: []string{"/web/components.js"},
                    Version: buildRevision,
                })
            </head>
            <body>{ children... }</body>
        </html>
    }

    Config.UI loads every Alacris UI component and applies Material defaults (seed #e8ad18, Google Sans Flex, scheme from the OS). Omit Modules if the page only uses the design system. See Alacris UI.

  4. Write a component and render it.

    web/components.js
    import { define, html } from 'alacris';
    

    define('hello-world', {
      props: { name: 'world' },
      setup: ({ name }) => html`<p>Hello, ${name}!</p>`,
    });
    @alacris.E("hello-world").Prop("name", "Ada")

Project layout

Section titled “Project layout”
  • go.mod
  • main.go
  • Directoryweb/
    • components.js every define() call, one module
  • Directoryinternal/components/ generated app wrappers; see Generating wrappers
    • components_gen.go
    • alacris_gen.go
  • Directoryviews/
    • page.templ
    • page_templ.go

Serving your components

Section titled “Serving your components”

The runtime handler serves alacris itself. Your own component module is an ordinary static asset; serve it however you serve the rest of them:

//go:embed web
var webFS embed.FS


mux.Handle("/web/", http.FileServerFS(webFS))

One binary, nothing to deploy alongside it.

Caching

Section titled “Caching”

Asset URLs carry no version by default, so the handler serves them Cache-Control: public, no-cache: cached, but revalidated. Revalidation costs one conditional request and almost always answers 304.

Set Config.Version to anything that changes with a deploy, and each release becomes a distinct URL that can be cached for a year:

alacris.Config{Version: build.Revision}   // /_alacris/alacris.js?v=<revision>

Development build

Section titled “Development build”

Config.Dev swaps in alacris.dev.js, which is unminified and carries readable errors. Wire it to whatever flag already distinguishes your environments:

alacris.Config{Dev: !isProduction}

Next

Section titled “Next”