Volt.Plugin behaviour (Volt v0.10.1)

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.

Summary

Types

compiled()

Callbacks

compile(path, source, opts)

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

define(mode)

Return compile-time replacements for a build mode.

extensions(kind)

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

extract_imports(path, source, opts)

Extract static/dynamic imports and worker specifiers from a source file.

load(path)

Load content for a resolved module path.

name()

Plugin name for identification and error messages.

prebundle_alias(specifier)

Return the canonical prebundle specifier to use for an import, or pass with nil.

prebundle_entry(specifier)

Return a generated prebundle entry for a canonical specifier, or pass with nil.

render_chunk(code, chunk_info)

Transform a final output chunk before writing.

resolve(specifier, importer)

Resolve an import specifier to a file path, :skip, or pass with nil.

transform(code, path)

Transform compiled JavaScript before serving or bundling.

Types

compiled()

@type compiled() :: %{
  code: String.t(),
  sourcemap: String.t() | nil,
  css: String.t() | nil,
  hashes: map() | nil
}

Callbacks

compile(path, source, opts)

(optional)

@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(mode)

(optional)

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

Return compile-time replacements for a build mode.

extensions(kind)

(optional)

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

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

extract_imports(path, source, opts)

(optional)

@callback extract_imports(path :: String.t(), source :: String.t(), opts :: keyword()) ::
  {:ok, %{imports: [{:static | :dynamic, String.t()}], workers: [String.t()]}}
  | {:error, term()}
  | nil

Extract static/dynamic imports and worker specifiers from a source file.

load(path)

(optional)

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

Load content for a resolved module path.

name()

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

Plugin name for identification and error messages.

prebundle_alias(specifier)

(optional)

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

Return the canonical prebundle specifier to use for an import, or pass with nil.

prebundle_entry(specifier)

(optional)

@callback prebundle_entry(specifier :: String.t()) ::
  {:source, filename :: String.t(), source :: String.t()}
  | {:proxy, filename :: String.t(), keyword()}
  | nil

Return a generated prebundle entry for a canonical specifier, or pass with nil.

render_chunk(code, chunk_info)

(optional)

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

Transform a final output chunk before writing.

resolve(specifier, importer)

(optional)

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

Resolve an import specifier to a file path, :skip, or pass with nil.

transform(code, path)

(optional)

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

Transform compiled JavaScript before serving or bundling.