Manage Assets

Process CSS, JavaScript, images, and other static files

2 min read 335 words

Bengal processes static assets including CSS, JavaScript, images, and fonts. The asset pipeline handles discovery, optimization, and delivery.

Default Python Pipeline

By default, Bengal uses a pure Python pipeline that requires no external dependencies (like Node.js).

Features

  • Discovery: Automatically finds assets inassets/and theme directories.
  • Minification: Minifies CSS using a built-in Python minifier (whitespace/comment removal) and JS usingrjsmin.
  • Image Optimization: Compresses and converts images (WebP support) using Pillow.
  • Fingerprinting: Adds SHA256 hashes to filenames for cache busting (style.abc123.css). This forces browsers to download the new version when the file changes.
  • Incremental Builds: Only reprocesses changed assets.

Usage

Place assets in yourassets/directory:

1
2
3
4
5
6
7
assets/
├── css/
│   └── style.css
├── js/
│   └── main.js
└── images/
    └── photo.jpg

Reference them in templates using theasset_urlhelper:

1
2
3
<link rel="stylesheet" href="{{ asset_url('css/style.css') }}">
<script src="{{ asset_url('js/main.js') }}"></script>
<img src="{{ asset_url('images/photo.jpg') }}" alt="Photo">

Whenfingerprint = trueis enabled,asset_urlautomatically resolves to the hashed filename (e.g.,/assets/css/style.a1b2c3.css).

Optional Node.js Pipeline

For modern frontend tooling (SCSS, PostCSS, Tailwind, TypeScript bundling), you can opt-in to the Node-based pipeline.

Prerequisites

  • Node.js v22 LTS
  • npmoryarnorpnpm

Setup

  1. Install dependencies in your project root:

    1
2
3
4
5
6
7
8
9
    {
  "devDependencies": {
    "sass": "^1.77.0",
    "postcss": "^8.4.35",
    "postcss-cli": "^11.0.0",
    "autoprefixer": "^10.4.19",
    "esbuild": "^0.23.0"
  }
}

  2. Enable the pipeline inbengal.toml:

    1
2
3
4
5
6
7
    [assets]
pipeline = true          # Enable Node-based pipeline
scss = true              # Compile SCSS → CSS
postcss = true           # Run PostCSS
postcss_config = "postcss.config.cjs"
bundle_js = true         # Bundle JS/TS with esbuild
sourcemaps = true        # Emit source maps

Conventions

  • SCSS: Place files inassets/scss/. Output goes topublic/assets/scss/.
  • JS/TS: Place entry files inassets/js/. Bundled output goes topublic/assets/js/.

Configuration

Configure the asset pipeline inbengal.toml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
[assets]
minify = true
optimize = true
fingerprint = true

# Image optimization settings
[assets.images]
quality = 85
strip_metadata = true
formats = ["webp"]

Deep Dive: For implementation details, caching behavior, and internal architecture, see the Asset Pipeline Reference.