---
title: "Build large exports ahead of time · Agent Wranglers"
url: https://agentwranglers.se/playbook/scaling/background-jobs-and-queues/build-exports-ahead
id: SCL-39
level: Recommended
updated: 2026-10-22
tokens: 1145
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Build large exports ahead of time

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Background jobs and queues](https://agentwranglers.se/playbook/scaling/background-jobs-and-queues.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: SCL-39
- Level: Recommended
- Chapter: [Background jobs and queues](https://agentwranglers.se/playbook/scaling/background-jobs-and-queues.md)
- Rule: Build large generated files, such as full-content dumps, feeds, sitemaps and JSON exports, at build or deploy time. Serve them as static files with compressed copies made in the same step.
- Check: The build output holds each large file with `.gz` and `.br` copies. Requests for those files never appear in the app's access log and carry no app time in `Server-Timing`. Their first byte leaves the server within 20 ms.
- How: A file built and compressed on each request costs the same work every time, and a large one can hold a worker for seconds. Write each file and its `.gz` and `.br` copies during the build, at the highest compression level, since it runs once. Let the web server send the right copy without calling the app, for example with `gzip_static` in nginx or `precompressed` in Caddy. Rebuild the files when the content changes, or on a schedule as a background job. Files that differ per customer go to object storage from a job, with a link sent when ready, as [Run long jobs asynchronously](https://agentwranglers.se/playbook/api-design/reliability/long-running-jobs.md) says. Pages follow [Render at build time and serve from memory](https://agentwranglers.se/playbook/website/site-architecture/render-at-build-time-serve-from-memory.md). [Prove one request cannot stall the site](https://agentwranglers.se/playbook/testing/non-functional-tests/single-request-stall.md) finds the files that need this.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
import { writeFile } from 'node:fs/promises';
import { brotliCompressSync, constants, gzipSync } from 'node:zlib';

export async function writePrecompressed(path, text) {
  const bytes = Buffer.from(text);
  await writeFile(path, bytes);
  await writeFile(`${path}.gz`, gzipSync(bytes, { level: 9 }));
  await writeFile(`${path}.br`, brotliCompressSync(bytes, { params: { [constants.BROTLI_PARAM_QUALITY]: 11 } }));
}

await writePrecompressed('dist/feed.xml', buildFeed(articles));
```

### Python example

```python
import gzip
from pathlib import Path

import brotli


def write_precompressed(path: Path, text: str) -> None:
    data = text.encode()
    path.write_bytes(data)
    Path(f"{path}.gz").write_bytes(gzip.compress(data, compresslevel=9))
    Path(f"{path}.br").write_bytes(brotli.compress(data, quality=11))


write_precompressed(Path("dist/feed.xml"), build_feed(articles))
```

## Sources

- [nginx gzip_static module](https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html)

## Related rules

- TST-54 [Prove one request cannot stall the site](https://agentwranglers.se/playbook/testing/non-functional-tests/single-request-stall.md) in Testing
- API-37 [Run long jobs asynchronously](https://agentwranglers.se/playbook/api-design/reliability/long-running-jobs.md) in API design
- WEB-18 [Render at build time and serve from memory](https://agentwranglers.se/playbook/website/site-architecture/render-at-build-time-serve-from-memory.md) in Website
- MED-23 [Build documents in a background job](https://agentwranglers.se/playbook/files-and-media/generated-documents/document-jobs.md) in Files and media

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/scaling/background-jobs-and-queues/build-exports-ahead">Agent Wranglers scaling playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Move slow work out of the request](https://agentwranglers.se/playbook/scaling/background-jobs-and-queues/slow-work-off-requests.md)
- Next: [Make every job safe to run twice](https://agentwranglers.se/playbook/scaling/background-jobs-and-queues/idempotent-jobs.md)
- [Background jobs and queues](https://agentwranglers.se/playbook/scaling/background-jobs-and-queues.md)