# `Volt.Builder`
[🔗](https://github.com/elixir-volt/volt/blob/v0.15.5/lib/volt/builder.ex#L1)

Production build — resolve dependencies, split chunks, bundle, and write assets.

Walks the dependency graph from entry files, compiles source through
`Volt.Pipeline`, expands Vite-compatible features such as `import.meta.glob()`
and dynamic import variables, bundles chunks with `OXC.bundle/2`, rewrites CSS
and JavaScript asset references, and writes content-hashed output files with a
manifest.

# `build_result`

```elixir
@type build_result() :: %{
  js:
    %{path: String.t(), size: non_neg_integer()}
    | [%{path: String.t(), size: non_neg_integer()}],
  css: %{path: String.t(), size: non_neg_integer()} | nil,
  manifest: %{required(String.t()) => String.t()}
}
```

# `build`

```elixir
@spec build(keyword()) :: {:ok, build_result()} | {:error, term()}
```

Build production assets from one or more entry files.

## Options

  * `:entry` — entry file path, plugin-resolved virtual entry specifier, or list of entries (required)
  * `:outdir` — output directory (default: `"priv/static/assets"`)
  * `:public_dir` — optional Vite-style public directory copied to the static root as-is
  * `:target` — JS target (e.g. `:es2020`)
  * `:minify` — minify output (default: `true`)
  * `:sourcemap` — generate source maps (default: `true`)
  * `:define` — compile-time replacements
  * `:node_modules` — path to node_modules (default: auto-detect)
  * `:resolve_dirs` — additional directories to resolve bare specifiers (e.g. `["deps"]`)
  * `:name` — output base name (default: derived from entry filename)
  * `:aliases` — import alias map (e.g. `%{"@" => "assets/src"}`)
  * `:plugins` — list of `Volt.Plugin` modules. Plugin `resolve/2` and `load/1` hooks can provide virtual modules and virtual build entries.
  * `:mode` — build mode for env variables (default: `"production"`)
  * `:env_prefix` — env variable prefix or prefixes exposed to client code (default: `"VOLT_"`)
  * `:asset_url_prefix` — public URL prefix for emitted asset references (default: `"/assets"`)
  * `:code_splitting` — split dynamic imports and multi-entry ESM shared modules into chunks (default: `true`)
  * `:tree_shaking` — remove unused exports (default: `true`)
  * `:chunks` — manual chunk definitions, map of chunk name to list of patterns:

        chunks: %{"vendor" => ["vue", "vue-router"], "ui" => ["assets/src/components"]}
  * `:external` — specifiers to exclude from the bundle and access as globals.
    Accepts a list (global name auto-derived) or a map of `specifier => global_name`:

        external: ["vue", "phoenix"]
        external: %{"vue" => "Vue", "phoenix" => "Phoenix"}

# `bundle`

```elixir
@spec bundle(keyword()) :: {:ok, Volt.Builder.Bundle.t()} | {:error, term()}
```

Bundle one JavaScript entry with Volt's normal build graph and return it in memory.

`bundle/1` accepts the same graph, compiler, and bundler options as `build/1`,
including `:plugins`, `:aliases`, `:node_modules`, `:resolve_dirs`, `:loaders`,
`:define`, `:target`, and `:external`. It does not write a manifest or output
JavaScript files, and it always returns a single entry bundle.

This API is intended for tools that need executable JavaScript from Volt's
production resolver/compiler pipeline without production file output, such as
test runners.

---

*Consult [api-reference.md](api-reference.md) for complete listing*