feat: add before_build and after_build hooks to dev server

Add optional hooks that run around each rebuild cycle in the dev server.
Hooks return Result(Nil, String) so they can abort the rebuild with a
descriptive error message (e.g. a failing Tailwind compilation).

Execution order: before_build → build command → after_build → SSE reload.
A failing before_build aborts the build entirely; a failing after_build
prevents the browser reload. Both error paths log the reason and keep
the server running.

Internal changes:
- Introduce RebuildStateConfig public type to bundle build_command and
  hooks into rebuild_actor.new()
- Refactor rebuild() to use Result with `use _ <- result.try` for clean
  short-circuit chaining via run_hook() and exec_build() helpers
- Update existing tests for the new RebuildStateConfig API
- Add 7 new tests covering hook invocation, ordering, and error handling
- Document hooks in docs/dev-server.md (API, reference table, rebuild flow)

Author: veeso

CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 5.0.0
+
+Released on 2026-03-18
+
+### Added
+
+- add before_build and after_build hooks to dev server
+  > Add optional hooks that run around each rebuild cycle in the dev server.
+  > Hooks return Result(Nil, String) so they can abort the rebuild with a
+  > descriptive error message (e.g. a failing Tailwind compilation).
+  >
+  > Execution order: before_build → build command → after_build → SSE reload.
+  > A failing before_build aborts the build entirely; a failing after_build
+  > prevents the browser reload. Both error paths log the reason and keep
+  > the server running.
+  >
+  > Internal changes:
+  > - Introduce RebuildStateConfig public type to bundle build_command and
+  >   hooks into rebuild_actor.new()
+  > - Refactor rebuild() to use Result with `use _ <- result.try` for clean
+  >   short-circuit chaining via run_hook() and exec_build() helpers
+  > - Update existing tests for the new RebuildStateConfig API
+  > - Add 7 new tests covering hook invocation, ordering, and error handling
+  > - Document hooks in docs/dev-server.md (API, reference table, rebuild flow)
+
+### CI
+
+- gleam 1.15.1
+
 ## 4.0.2
 
 Released on 2026-03-17

docs/dev-server.md

@@ -99,14 +99,14 @@ The server starts, performs an initial build, then watches for changes:
 ```text
 🔨 blogatto dev server starting...
 👀 Watching for file changes...
-	👀 Watching: ./static
-	👀 Watching: ./src/
-	👀 Watching: ./blog
+👀 Watching: ./static
+👀 Watching: ./src/
+👀 Watching: ./blog
 
 ⟳ Rebuilding...
 ✓ Rebuild complete
-	→  http://127.0.0.1:3000
-	Output: ./dist
+  →  http://127.0.0.1:3000
+  Output: ./dist
 ```
 
 Open `http://127.0.0.1:3000` in your browser. When you save a file, the site rebuilds and the browser reloads automatically.
@@ -122,6 +122,14 @@ blog.config()
 |> dev.port(8080)
 |> dev.host("0.0.0.0")
 |> dev.live_reload(False)
+|> dev.before_build(fn() {
+  io.println("Starting build...")
+  Ok(Nil)
+})
+|> dev.after_build(fn() {
+  io.println("Build finished!")
+  Ok(Nil)
+})
 |> dev.start()
 ```
 
@@ -182,6 +190,37 @@ dev.new(config)
 |> dev.live_reload(False)
 ```
 
+### `dev.before_build(server, hook)`
+
+Set a function to run **before** each rebuild. The hook runs before the build command is executed, on every rebuild (including the initial build on startup). This is useful for setup or cleanup tasks.
+
+The hook must return `Result(Nil, String)`. If it returns `Error(reason)`, the build is aborted and the error reason is logged. The hook runs regardless of whether the subsequent build would succeed or fail.
+
+```gleam
+dev.new(config)
+|> dev.before_build(fn() {
+  // Clean generated assets, fetch data, etc.
+  io.println("Preparing build...")
+  Ok(Nil)
+})
+```
+
+### `dev.after_build(server, hook)`
+
+Set a function to run **after** each successful rebuild. The hook runs only when the build command exits with code 0. This is useful for post-processing tasks like running Tailwind CSS, copying additional assets, or sending notifications.
+
+The hook must return `Result(Nil, String)`. If it returns `Error(reason)`, the error is logged and browsers are **not** reloaded. The hook is **not** called when the build fails.
+
+```gleam
+dev.new(config)
+|> dev.after_build(fn() {
+  case shellout.command("npx", ["tailwindcss", "-o", "./dist/style.css"], ".", []) {
+    Ok(_) -> Ok(Nil)
+    Error(_) -> Error("Tailwind CSS compilation failed")
+  }
+})
+```
+
 ## Reference
 
 | Option | Default | Description |
@@ -190,6 +229,8 @@ dev.new(config)
 | `port` | `3000` | HTTP server port |
 | `host` | `"127.0.0.1"` | Bind address |
 | `live_reload` | `True` | Inject live-reload script into HTML responses |
+| `before_build` | `None` | `fn() -> Result(Nil, String)` to run before each rebuild |
+| `after_build` | `None` | `fn() -> Result(Nil, String)` to run after each successful rebuild |
 
 ## How it works
 
@@ -206,9 +247,10 @@ The dev server is built on OTP actors:
 1. A file changes on disk
 2. The file watcher sends a `FileChanged` message to the rebuild actor
 3. The rebuild actor cancels any pending debounce timer and starts a new 300ms timer
-4. When the timer fires, the actor shells out to the build command
-5. On success (exit code 0), a `Reload` event is sent to all connected SSE clients
-6. On failure, the error output is logged and the server keeps running with the last successful build
+4. When the timer fires, the `before_build` hook runs (if configured)
+5. The actor shells out to the build command
+6. On success (exit code 0), the `after_build` hook runs (if configured), then a `Reload` event is sent to all connected SSE clients
+7. On failure, the error output is logged and the server keeps running with the last successful build (the `after_build` hook is **not** called)
 
 ### Watched directories
 

examples/simple_blog/manifest.toml

@@ -2,7 +2,7 @@
 # You typically do not need to edit this file
 
 packages = [
-  { name = "blogatto", version = "4.0.2", build_tools = ["gleam"], requirements = ["filepath", "filespy", "frontmatter", "gleam_erlang", "gleam_http", "gleam_otp", "gleam_stdlib", "gleam_time", "gtempo", "houdini", "lustre", "marceau", "maud", "mist", "mork", "simplifile", "smalto", "smalto_lustre", "str", "webls"], source = "local", path = "../.." },
+  { name = "blogatto", version = "5.0.0", build_tools = ["gleam"], requirements = ["filepath", "filespy", "frontmatter", "gleam_erlang", "gleam_http", "gleam_otp", "gleam_stdlib", "gleam_time", "gtempo", "houdini", "lustre", "marceau", "maud", "mist", "mork", "simplifile", "smalto", "smalto_lustre", "str", "webls"], source = "local", path = "../.." },
   { name = "casefold", version = "2.0.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "casefold", source = "hex", outer_checksum = "F09530B6F771BB7B0BCACD3014089C20DFDA31775BA4793266C3814607C0A468" },
   { name = "exception", version = "2.1.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "exception", source = "hex", outer_checksum = "329D269D5C2A314F7364BD2711372B6F2C58FA6F39981572E5CA68624D291F8C" },
   { name = "filepath", version = "1.1.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "filepath", source = "hex", outer_checksum = "B06A9AF0BF10E51401D64B98E4B627F1D2E48C154967DA7AF4D0914780A6D40A" },

gleam.toml

@@ -1,5 +1,5 @@
 name = "blogatto"
-version = "4.0.2"
+version = "5.0.0"
 description = "A Gleam framework for building static blogs with Lustre and Markdown. Generates HTML pages, RSS feeds, sitemaps, and robots.txt from markdown files with frontmatter, with multilingual support."
 repository = { type = "github", user = "veeso", repo = "blogatto" }
 licenses = ["MIT"]

src/blogatto/dev.gleam

@@ -9,13 +9,19 @@ import gleam/erlang/process
 import gleam/int
 import gleam/io
 import gleam/list
-import gleam/option
+import gleam/option.{type Option}
 import gleam/result
 import gleam/string
 
 /// A development server for Blogatto. This will serve the generated blog and watch for file changes to trigger rebuilds.
 pub type DevServer(msg) {
   DevServer(
+    /// An optional function to run after each build.
+    /// This can be used to perform any tasks after the build command is run, such as running tailwind or other post-build tasks. (default: None)
+    after_build: Option(fn() -> Result(Nil, String)),
+    /// An optional function to run before each build.
+    /// This can be used to perform any setup or cleanup tasks before the build command is run. (default: None)
+    before_build: Option(fn() -> Result(Nil, String)),
     /// Build command to build the blog. (default: "gleam run")
     build_command: String,
     /// Blogatto build config to use for knowing which files to watch.
@@ -32,6 +38,8 @@ pub type DevServer(msg) {
 /// Create a new development server with the given config and options.
 pub fn new(config: config.Config(msg)) -> DevServer(msg) {
   DevServer(
+    after_build: option.None,
+    before_build: option.None,
     build_command: "gleam run",
     config:,
     port: 3000,
@@ -40,6 +48,24 @@ pub fn new(config: config.Config(msg)) -> DevServer(msg) {
   )
 }
 
+/// Set a function to run after each build.
+/// This can be used to perform any tasks after the build command is run, such as running tailwind or other post-build tasks.
+pub fn after_build(
+  server: DevServer(msg),
+  after_build: fn() -> Result(Nil, String),
+) -> DevServer(msg) {
+  DevServer(..server, after_build: option.Some(after_build))
+}
+
+/// Set a function to run before each build.
+/// This can be used to perform any setup or cleanup tasks before the build command is run.
+pub fn before_build(
+  server: DevServer(msg),
+  before_build: fn() -> Result(Nil, String),
+) -> DevServer(msg) {
+  DevServer(..server, before_build: option.Some(before_build))
+}
+
 /// Set the build command to use for building the blog.
 /// This should be a command that can be run in the terminal to build the blog,
 /// such as "gleam run" or "make build".
@@ -76,7 +102,12 @@ pub fn start(server: DevServer(msg)) -> Result(Nil, error.BlogattoError) {
 
   // Start the rebuild actor (performs an initial build on startup)
   use started <- result.try(
-    rebuild_actor.new(server.build_command)
+    rebuild_actor.RebuildStateConfig(
+      build_command: server.build_command,
+      before_build: server.before_build,
+      after_build: server.after_build,
+    )
+    |> rebuild_actor.new
     |> result.map_error(fn(e) {
       error.DevServer("Failed to start rebuild actor: " <> string.inspect(e))
     }),

src/blogatto/internal/dev/rebuild_actor.gleam

@@ -8,13 +8,25 @@ import gleam/io
 import gleam/list
 import gleam/option.{type Option}
 import gleam/otp/actor
+import gleam/result
 
 const debounce_delay: Int = 300
 
+/// Configuration for the rebuild actor, including the build command and optional hooks to run before and after the build.
+pub type RebuildStateConfig {
+  RebuildStateConfig(
+    build_command: String,
+    before_build: Option(fn() -> Result(Nil, String)),
+    after_build: Option(fn() -> Result(Nil, String)),
+  )
+}
+
 type RebuildState {
   RebuildState(
     self: Subject(message.RebuildMessage),
     build_command: String,
+    before_build: Option(fn() -> Result(Nil, String)),
+    after_build: Option(fn() -> Result(Nil, String)),
     debounce_timer: Option(Timer),
     sse_clients: List(Subject(message.SseMessage)),
   )
@@ -42,14 +54,16 @@ pub fn register_sse_client(
 /// for file change messages, debounce them, shell out to the build command,
 /// and broadcast reload events to connected SSE clients.
 pub fn new(
-  build_command: String,
+  config: RebuildStateConfig,
 ) -> Result(actor.Started(Subject(message.RebuildMessage)), actor.StartError) {
   actor.new_with_initialiser(5000, fn(subject) {
     // Schedule an immediate rebuild on startup
     process.send(subject, message.Rebuild)
     RebuildState(
       self: subject,
-      build_command:,
+      build_command: config.build_command,
+      before_build: config.before_build,
+      after_build: config.after_build,
       debounce_timer: option.None,
       sse_clients: [],
     )
@@ -78,9 +92,9 @@ fn handle_message(
     message.Rebuild -> {
       // Prune dead SSE clients, then broadcast reload on success
       let live_clients = prune_dead_clients(state.sse_clients)
-      case rebuild(state.build_command) {
-        True -> broadcast_reload(live_clients)
-        False -> Nil
+      case rebuild(state.build_command, state.before_build, state.after_build) {
+        Ok(_) -> broadcast_reload(live_clients)
+        Error(_) -> Nil
       }
       actor.continue(
         RebuildState(
@@ -101,21 +115,50 @@ fn handle_message(
   }
 }
 
-fn rebuild(build_command: String) -> Bool {
+fn rebuild(
+  build_command: String,
+  before_build: Option(fn() -> Result(Nil, String)),
+  after_build: Option(fn() -> Result(Nil, String)),
+) -> Result(Nil, Nil) {
+  use _ <- result.try(run_hook(before_build, "before_build"))
+  use _ <- result.try(exec_build(build_command))
+  use _ <- result.try(run_hook(after_build, "after_build"))
+  Ok(Nil)
+}
+
+fn run_hook(
+  hook: Option(fn() -> Result(Nil, String)),
+  name: String,
+) -> Result(Nil, Nil) {
+  case hook {
+    option.Some(f) ->
+      case f() {
+        Ok(Nil) -> Ok(Nil)
+        Error(msg) -> {
+          io.println("✗ " <> name <> " hook failed: " <> msg)
+          io.println("  (server still running, fix the error and save again)")
+          Error(Nil)
+        }
+      }
+    option.None -> Ok(Nil)
+  }
+}
+
+fn exec_build(build_command: String) -> Result(Nil, Nil) {
   io.println("⟳ Rebuilding...")
   let #(exit_code, output) = command.exec(build_command)
   case exit_code {
     0 -> {
       io.println("✓ Rebuild complete")
-      True
+      Ok(Nil)
     }
     _ -> {
       io.println(
         "✗ Build failed (exit code " <> int.to_string(exit_code) <> "):",
       )
       io.println(output)
       io.println("  (server still running, fix the error and save again)")
-      False
+      Error(Nil)
     }
   }
 }