# Build Hooks

URL: /docs/extending/build-hooks/
Section: extending

--------------------------------------------------------------------------------

Build hooks let you run shell commands before and after Bengal builds. Use them to integrate CSS preprocessors, JavaScript bundlers, icon generators, or custom validation scripts. Configuration Add hooks to your bengal.toml under the [dev_server] section: [dev_server] pre_build = [ "npm run build:icons", "npx tailwindcss -i src/input.css -o assets/style.css" ] post_build = [ "echo 'Build complete!'", "node scripts/validate-output.js" ] How Hooks Work Hooks execute sequentially in the order defined: Pre-build hooks run before the build starts Bengal processes and renders your site Post-build hooks run after all pages are written If a pre-build hook fails (non-zero exit code), the build stops immediately and reports the error. If a post-build hook fails, a warning is logged but the build is considered complete. Common Use Cases CSS Preprocessing with Tailwind [dev_server] pre_build = [ "npx tailwindcss -i src/input.css -o assets/css/tailwind.css --minify" ] JavaScript Bundling with esbuild [dev_server] pre_build = [ "npx esbuild src/main.ts --bundle --outfile=assets/js/bundle.js --minify" ] Icon Sprite Generation [dev_server] pre_build = [ "npx svg-sprite --symbol --dest assets/icons src/icons/*.svg" ] Post-Build Validation [dev_server] post_build = [ "python scripts/check-links.py public/", "npx html-validate public/**/*.html" ] Multi-Step Asset Pipeline [dev_server] pre_build = [ "npm run build:icons", "npm run build:css", "npm run build:js" ] Environment and Working Directory Hooks run in your project's root directory with access to your shell environment. This means: npm, npx, and other tools in your PATH work as expected Environment variables from your shell are available Relative paths resolve from the project root Error Handling When a pre-build hook fails: The command's stderr is logged (truncated to 500 characters) The build stops immediately An error message shows which hook failed Example error output: Pre-build hook failed - skipping build When a post-build hook fails: The command's stderr is logged A warning is logged, but the build is considered successful Your site output is still available Successful hook output (stdout) is logged at debug level. Run bengal serve --debug to see full command output during development. Limitations Hooks run synchronously (one at a time) Each command has a 60-second timeout No shell features like pipes (|) or redirects (>) — commands are parsed as argument lists, not passed to a shell interpreter Hooks run for every build, including incremental rebuilds in dev server mode Tips Use npm Scripts for Complex Commands Instead of long inline commands: # ❌ Hard to read pre_build = [ "npx tailwindcss -i src/input.css -o assets/style.css --config tailwind.config.js --minify" ] Define an npm script: // package.json { "scripts": { "build:css": "tailwindcss -i src/input.css -o assets/style.css --config tailwind.config.js --minify" } } Then use it in your hooks: # ✅ Clean and maintainable pre_build = ["npm run build:css"] Skip Hooks in CI If your CI pipeline handles asset building separately, you can use environment variables: # Only run hooks if BENGAL_HOOKS is set pre_build = [] # Override in local config Or use a local config override file that's not committed to version control. Related Configuration for all bengal.toml options Build Pipeline for understanding when hooks run

--------------------------------------------------------------------------------

Metadata:
- Author: lbliii
- Word Count: 498
- Reading Time: 2 minutes