Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions src/content/contribute/writing-a-loader.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ contributors:
- dev-itsheng
- evenstensberg
- hagemaruwu
- raj-sapalya
---

A loader is a node module that exports a function. This function is called when a resource should be transformed by this loader. The given function will have access to the [Loader API](/api/loaders/) using the `this` context provided to it.
Expand Down Expand Up @@ -101,6 +102,52 @@ export default {
};
```

## Pitching loaders

Loaders normally run **right to left**. A loader can also export a
`pitch` function, which runs **left to right** before the normal phase
begins. This allows a loader to pass data to its own normal phase or
short-circuit the remaining loader chain.

```js
// my-loader.js
export default function (source) {
// Normal phase — runs right to left
const prefix = this.data.value ?? "";
return `${prefix}\n${source}`;
}

export function pitch(remainingRequest, precedingRequest, data) {
// Pitch phase — runs left to right before normal loaders
data.value = "/* processed by my-loader */";
}
```

T> `data` is shared only between the `pitch` and normal functions of
the same loader. It is not shared across different loaders in
the chain.

### Short-circuiting the loader chain

If a `pitch` function returns a value, webpack skips the remaining
loaders to the right and reverses immediately. This can be useful when
you want to generate module code early and bypass the normal phase.

```js
export function pitch(remainingRequest) {
return `
import style from ${JSON.stringify(`!!${remainingRequest}`)};
const el = document.createElement("style");
el.textContent = style;
document.head.appendChild(el);
`;
}
```

W> When a `pitch` function returns a value, the default export of that
loader does not run. Only use this pattern when you intend to replace
the normal processing pipeline.

## Guidelines

The following guidelines should be followed when writing a loader. They are ordered in terms of importance and some only apply in certain scenarios, read the detailed sections that follow for more information.
Expand Down
Loading