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

Behaviour for Volt build plugins.

Plugins can participate in resolution, loading, compilation, import
extraction, and final chunk rendering. All callbacks except `name/0` are
optional.

Plugins may be configured as modules or `{module, opts}` tuples. When a
plugin defines a callback with one extra arity, Volt passes the tuple opts as
the final argument.

Plugins can opt into Vite-style ordering with `enforce/0` or `enforce/1`:
`:pre` plugins run before normal plugins, and `:post` plugins run after them.

# `compiled`

```elixir
@type compiled() :: Volt.Pipeline.Result.t()
```

# `prebundle_export`

```elixir
@type prebundle_export() :: Volt.JS.PrebundleEntry.Export.t()
```

# `prebundle_import`

```elixir
@type prebundle_import() :: Volt.JS.PrebundleEntry.Import.t()
```

# `compile`
*optional* 

```elixir
@callback compile(path :: String.t(), source :: String.t(), opts :: keyword()) ::
  {:ok, compiled()} | {:error, term()} | nil
```

Compile a source file into browser-ready JavaScript plus optional CSS.

# `define`
*optional* 

```elixir
@callback define(mode :: String.t()) :: %{required(String.t()) => String.t()}
```

Return compile-time replacements for a build mode.

# `embedded_modules`
*optional* 

```elixir
@callback embedded_modules(path :: String.t(), source :: String.t(), opts :: keyword()) ::
  [
    Volt.Plugin.EmbeddedModule.t()
    | {extension :: String.t(), source :: String.t()}
  ]
  | nil
```

Return modules embedded in a plugin-owned source file.

# `enforce`
*optional* 

```elixir
@callback enforce() :: :pre | :post | nil
```

Return `:pre`, `:post`, or `nil` to control plugin ordering.

# `extensions`
*optional* 

```elixir
@callback extensions(kind :: atom()) :: [String.t()]
```

Return extensions owned by this plugin for `:compile`, `:resolve`, `:watch`, or `:scan`.

# `extract_imports`
*optional* 

```elixir
@callback extract_imports(path :: String.t(), source :: String.t(), opts :: keyword()) ::
  {:ok, Volt.JS.ImportExtractor.Result.t()} | {:error, term()} | nil
```

Extract dependency metadata from source handled by this plugin.

Use this when a source format can contain imports that are not visible to
Volt's normal JavaScript parser before plugin processing, such as component
files or custom markup formats. Return `nil` to let Volt use the default
JavaScript import extractor.

# `load`
*optional* 

```elixir
@callback load(path :: String.t()) ::
  {:ok, String.t(), String.t()} | {:ok, String.t()} | nil
```

Load content for a resolved module path. A two-tuple return is treated as JavaScript.

# `name`

```elixir
@callback name() :: String.t()
```

Plugin name for identification and error messages.

# `prebundle_alias`
*optional* 

```elixir
@callback prebundle_alias(specifier :: String.t()) :: String.t() | nil
```

Return the canonical dev prebundle specifier for an import.

Use this advanced framework-integration hook when several package entrypoints
should share one dev vendor module. Return `nil` to leave the specifier
unchanged.

This is Volt-specific. Vite framework plugins achieve similar results through
dependency optimization, resolution, and virtual modules rather than a direct
hook with this name.

# `prebundle_entry`
*optional* 

```elixir
@callback prebundle_entry(specifier :: String.t()) ::
  {:source, filename :: String.t(), source :: String.t()}
  | {:proxy, filename :: String.t(),
     imports: [prebundle_import()], exports: [prebundle_export()]}
  | nil
```

Return a generated dev prebundle entry for a canonical specifier.

Use this advanced framework-integration hook when a framework needs a
synthetic vendor module that re-exports multiple package entrypoints or adapts
package exports for browser dev mode. Return `nil` to let Volt generate a
normal package prebundle.

This hook affects dev dependency prebundling only; production output is built
from the application module graph.

# `render_chunk`
*optional* 

```elixir
@callback render_chunk(code :: String.t(), chunk_info :: map()) :: {:ok, String.t()} | nil
```

Transform a final output chunk before writing.

# `resolve`
*optional* 

```elixir
@callback resolve(specifier :: String.t(), importer :: String.t() | nil) ::
  {:ok, String.t()} | :skip | nil
```

Resolve an import or build-entry specifier to a file path, virtual module id, `:skip`, or pass with `nil`.

# `transform`
*optional* 

```elixir
@callback transform(code :: String.t(), path :: String.t()) :: {:ok, String.t()} | nil
```

Transform compiled JavaScript before serving or bundling.

---

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