Tooling
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
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.
<script client> blocks compile to TypeScript and bundle into browser ES modules.// 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
bosca bml dev watches application sources, rebuilds the affected output, and swaps the new application generation into the running server. The process, port, and active sessions stay put, while the server pushes a live-reload event so the browser follows automatically.
If a build fails, the last good generation keeps serving while the diagnostics point back to the source. Framework or dependency changes still ask for a deliberate restart; ordinary application work stays in the fast loop.
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.
# scaffold a project
bosca bml init my-site
# generate Kotlin once
bosca bml compile my-site
# rebuild, hot-swap, live-reload
bosca bml dev my-siteDeployment
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.
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()Measurement
The compiler knows exactly which assets each page links — its island bundle, the CSS chunks of the components it renders, the global tier — so the build can price every page. Running bmlMetrics prints each page's first-load payload in raw and gzip bytes and writes a JSON report, so size changes are visible build over build.
For a running site there's bosca bml audit: it fetches a route, discovers the assets the page actually declares, and records real transfer bytes and timing per request. It works against any HTTP site — not just BML — so you can measure a BML deployment against the same pages on another stack.
BML site metrics — first-load payload per page (raw, gzip)
Page Route JS CSS First load
------------- ---------------- --------------- ------------- ----------------
HomePage / 3.4 KB (1.6 KB) 564 B (291 B) 3.9 KB (1.9 KB)
CartPage /cart 3.3 KB (1.6 KB) 55 B (72 B) 3.4 KB (1.6 KB)
DashboardPage /dashboard - - -
ScenarioPage /scenario/{mode} - 508 B (269 B) 508 B (269 B)
JSON report: build/reports/bml/site-metrics.jsonKeep exploring
What BML is, what makes it powerful, and how to use it.
Pages, components, control flow, and scoped styles.
Islands and interactivity without hand-written client code.
The typed GraphQL data plane and client-managed auth.
Localized sites and versioned, email-safe transactional templates.