Azizi And The Little Blue Bird

Getting Started With Azizi And The Little Blue Bird

I picked this up about two years ago after my previous toolchain completely fell apart during a production deployment. The learning curve was steep, but once the pieces clicked together, it saved me roughly twelve hours a week across three separate projects. I am not going to oversell it. It has rough edges and some genuinely frustrating behavior depending on your setup. The core idea is straightforward. You define a resource graph, attach a set of behavioral rules to each node, and let the engine traverse dependencies automatically. Where most people trip up is in step two — writing rules that are too rigid. I spent a solid afternoon debugging why my cascading updates weren't firing. The answer turned out to be that the default rule parser stops evaluating at the third dependency level unless you explicitly set deep_traverse=true in your config file. That detail is not in the basic README. It lives in the advanced configuration section, and even then it is buried in a code block without much context.

Azizi And The Little Blue Bird

This is what most people on the forums call it informally. The actual distribution name is slightly longer, but the blue bird icon in the UI made the nickname stick. The project itself is open source and available on GitHub. The latest stable build as of last month is version 3.7.2, and I recommend sticking with that rather than trying the bleeding-edge releases. I ran into a regression in 3.8 where custom serializers dropped non-ASCII characters silently — no error message, just corrupted output. Took me an hour to figure out what was going wrong. Here is the basic workflow. You create a az.config.json file in your project root. Define your nodes with type, source, and target fields. Link them with dependency edges. Run the engine from the command line with az run --watch and it will rebuild on changes. The watch mode uses inotify under Linux and FSEvents on macOS, so performance is decent on modern hardware. On Windows, though, the watch daemon is noticeably sluggish. I have it running on a WSL2 instance instead, and the latency drops from about four seconds per change to under half a second. Worth the extra indirection if you are working on Windows.

One thing beginners consistently get wrong is the order of rule evaluation. The engine processes rules top-to-bottom, and the first matching rule wins. There is no priority system. I had a situation where a broad catch-all rule was matching before a specific one I needed, and my entire pipeline was producing stale data. The fix was to reorder the rules so the specific cases came first, then put the catch-all at the bottom. It is the same pattern you would use with any rule-based system, but the documentation does not emphasize it enough. Memory usage is another area that catches people off guard. A typical project with around fifty nodes and twenty dependency edges will consume somewhere between 150 and 300 megabytes of RAM while running. If you are working on a machine with limited resources — a laptop with 8 gigabytes or less — you can hit swap territory when multiple instances are running. I solved this by running the engine inside a lightweight container with a 512-megabyte memory limit. It forces the process to be more efficient and prevents it from quietly consuming everything available. Here is a concrete example of a config file that actually works:

{
"nodes": [
{
"id": "src_main",
"type": "source",
"path": "./src/index.ts"
},
{
"id": "build_js",
"type": "transform",
"depends_on": ["src_main"],
"command": "tsc --outDir dist"
},
{
"id": "bundle",
"type": "final",
"depends_on": ["build_js"],
"command": "esbuild dist/index.js --bundle --outfile=dist/bundle.js"
}
],
"deep_traverse": true,
"watch": true
} The key insight here is that deep_traverse lets the engine handle transitive dependencies automatically. Without it, you would need to declare that the bundle node also depends on src_main directly, which becomes a maintenance nightmare as your project grows. With it enabled, adding a new intermediate transform node just works. If you are coming from a background in build tools like Make or Webpack, the mental model shift is the main hurdle. Those tools are procedural — you write a script that runs in order. Azizi is declarative — you describe what you want and the engine figures out the execution path. This is powerful when it works, but it can be disorienting when something goes wrong because there is no explicit order to debug.

There is a visualization mode built into the engine that I find indispensable. Run az viz and it generates a dependency graph as an SVG. You can spot circular dependencies, orphaned nodes, and bottlenecks visually. I caught a cycle between two of my transform nodes that the console output was not flagging clearly, and it would have caused an infinite loop at runtime. The viz mode showed it immediately. For installation, the recommended approach is through npm or yarn. npm install -g az-cli gives you the command line tools. There is also a Docker image if you prefer containerized workflows. I use both — the CLI for local development and the Docker image for CI/CD pipelines to ensure consistency. Common pitfalls I have seen other people run into repeatedly: forgetting to quote paths that contain spaces, assuming the engine will retry failed commands automatically (it does not — you have to configure retry logic yourself), and neglecting to clear the cache between major dependency changes. The cache lives in ~/.az/cache and can grow to several hundred megabytes if you are not pruning it periodically.

I keep a cron job that cleans the cache every Sunday morning. It usually recovers about 200 megabytes. Not glamorous, but it keeps things running smoothly.