Bosca / BML Read the docs

Tooling

From compiler to production

BML is compiled, not interpreted. A Kotlin K2 compiler plugin produces typed page objects, the IDE understands your files, the dev loop reloads the browser for you, and a finished site deploys as one server process.

The compiler

Pages are typed objects

There are no hand-written page classes. The build parses every .bml file and generates a Kotlin render object per page, which the Kotlin compiler compiles alongside the rest of the project. Embedded server Kotlin lowers into the generated code with source maps back to the .bml file, so diagnostics point at the line you wrote.

  • Client <script client> blocks compile to TypeScript and bundle into browser ES modules.
  • The IntelliJ plugin adds file-type support, syntax highlighting, comment toggling, and language injection — Kotlin inside server scripts, interpolation, and bound attributes; TypeScript inside client scripts.
generated page object
// build/generated/bml/kotlin — generated, never hand-written
@BmlPage(route = "/prayers/{id}")
object PrayerPage : BmlPageRenderer {
    override suspend fun render(ctx: RenderContext) {
        // compiled from prayer.bml
    }
}

The dev loop

Save the file. The browser follows.

bosca bml dev watches the source tree and regenerates Kotlin the instant a .bml file changes; with --run it also restarts the server command, and the server's dev mode pushes a live-reload event so the browser refreshes itself — no plugin, no manual refresh.

The GraphQL endpoint is configuration, so local development can point at a remote Bosca for real data and the same code runs unchanged once deployed.

the bosca CLI
# scaffold a project
bosca bml init my-site

# generate Kotlin once
bosca bml compile my-site

# watch, regenerate, restart, live-reload
bosca bml dev my-site --run "./gradlew run"

Deployment

A site is one process

Hand the generated registries to BmlServer and start it. The server registers each page's route, serves static assets, and hosts the action, contract, and GraphQL proxy endpoints — there is nothing else to run.

  • Assets ship in three tiers — global, per-page, and per-component — so a page loads only what it renders.
  • Served CSS/JS carries an ETag; repeat loads answer with a body-less 304.
  • Files under the public directory can opt into a long-lived Cache-Control policy.
Main.kt — wiring a compiled site
BmlServer(
    pages = bml.generated.BmlPages.all,
    components = bml.generated.BmlComponents.all,
    graphqlEndpoint = System.getenv("BML_GRAPHQL_ENDPOINT"),
    publicDir = File("public"),
    globalCss = File("app.css").readText(),
    port = 9092,
).start()

Keep exploring

More on BML

BML overview

What BML is, what makes it powerful, and how to use it.

The language

Pages, components, control flow, and scoped styles.

Live state & actions

Islands and interactivity without hand-written client code.

Data & auth

The typed GraphQL data plane and client-managed auth.

Ready for the reference? Read the BML documentation