Everyone figured visual workflows meant trading code for drag-and-drop drudgery. You’d fire up some glossy demo—nodes snapping together like Lego, promises of speed and clarity—then bam, reality hits: proprietary formats, vanished types, linters gathering dust. Close tab. Repeat.
Flow Weaver shatters that. It’s a solo side-project by Ricardo, two years in the making, a TypeScript workflow compiler that treats your code as gospel. Visuals? Mere views. This isn’t hype—it’s an architectural U-turn, code stays sovereign.
Look.
Ricardo nails it right out the gate: “I don’t think developers hate visual workflows. I think they hate what they have to give up to get them. Your types, your linter, your version control, your ability to just read the code and understand what’s happening.”
I don’t think developers hate visual workflows. I think they hate what they have to give up to get them. Your types, your linter, your version control, your ability to just read the code and understand what’s happening.
Spot on. Here’s the thing—tools like Zapier, n8n, or even Node-RED demand you abandon ship. Enter their editor. Learn their DSL. Pray Git diffs make sense. Flow Weaver says no. You write plain functions—greet a name, shout the result—slap on an annotation, and the compiler weaves a graph.
Why Have Visual Workflows Always Felt Like a Trap?
But start here: the betrayal baked into most tools. They promise intuition—see the flow at a glance!—yet hide the machinery. Reverse-engineer from pixels? Nightmare. Types evaporate; you’re flying blind on inputs, outputs. One typo in a JSON config, hours lost.
Flow Weaver inverts this. Your TypeScript is the workflow. Annotate like so:
/** @flowWeaver nodeType @expression */
function greet(name: string): { greeting: string } {
return { greeting: `Hello, ${name}!` };
}
That’s it. Call it directly. Vitest it. Import anywhere. Compiler infers ports: execute in, name in, greeting out, success/failure signals auto-wired. No magic—just structured plumbing exposed.
Connect ‘em in a workflow stub:
/**
* @flowWeaver workflow
* @node g greet
* @node s shout
* @path Start -> g -> s -> Exit
*/
export function helloWorld(...) { /* compiler fills */ }
Run npx flow-weaver compile, and it injects execution logic between markers. Output? Pure TypeScript. Nuke the package; it still runs. Dead simple, zero runtime deps.
And visuals? npx flow-weaver diagram hello.ts spits ASCII, SVG, Mermaid, or browser playground. Compile-time checks catch port mismatches, dead ends—structured errors with fixes, AI-ready.
This matters because it resurrects visuals as documentation, not dictatorship. Think Makefiles from the ’70s: code describes the build graph, tools render it. Flow Weaver drags that to modern workflows—serverless, data pipelines, whatever—without YAML hell.
Shift happens underground first.
Ricardo’s not yelling from rooftops (yet). Solo dev, side gig. But peek at the CLI: run executes with params, spits JSON results. validate scans graphs. MCP tools hook into Claude, Cursor—AI chats fix syntax via context.
Does Flow Weaver Kill the No-Code Hype Machine?
Yes—and here’s my hot take, absent from the announcement: this echoes GraphQL’s schema-first revolution. Remember REST? Bloated endpoints, client-server mismatches. Schema-first flipped it—define types centrally, code and queries derive. Flow Weaver does that for workflows. Schema (your functions) first; graph second. No more “magic” under the hood—it’s all there, typed, testable.
Corporate PR spins visuals as salvation for prods, but devs know: magic scales to regret. Airflow DAGs? Pythonic, sure, but sprawl hits. Temporal? Powerful, verbose. Flow Weaver threads the needle—lightweight compiler, full TS ecosystem.
Test it. npx flow-weaver run hello.ts --params '{"name":"World"}' → “HELLO, WORLD!!!” in 1ms. Interactive HTML lets you tweak live. GitHub READMEs glow with Mermaid. Documentation crisis? Solved.
But why now? TS dominance—90% of nodes run it. Workflows exploding: LLMs chaining, ETLs, CI/CD. Everyone’s gluing functions; why not visualize without friction?
Skeptical? Fair. Solo project—will it stick? Compiler’s young; edge cases lurk (cycles? parallelism?). Yet standalone output means immortality. Fork it, embed it. No vendor lock.
How Does the Compiler Actually Work Under the Hood?
Dive deeper—because “how” unlocks “why this sticks.”
Annotations parse via TS decorators (future-proof?). Compiler builds a graph: nodes from functions, ports from params/returns. @path chains control flow; @connect wires data. Virtual Start/Exit handle IO.
Type flow? Inferred bidirectionally—greet’s ‘name: string’ demands upstream string port. Mismatches? Fail fast, pinpointed:
✗ [line 11] Unknown Input Port: Port ‘wrong_port’ doesn’t exist on node Exit. ⚠ How to fix: Check the port name in the @connect annotation.
Execution? Topological sort, execute nodes on signals. Expression nodes (@expression) auto-set success (no throw) or failure. Complex? Manual nodes override.
Generated code? FSM-like: if execute && !onSuccess, dispatch next. Reactive? Ports are signals, pure functions transform.
Architecturally, it’s literate diagramming—Knuth dreamed diagrams from prose; Ricardo delivers from code. Bold prediction: six months, this forks into infra-as-code king. Kubeflows, Airflows watch out—TS devs will eat YAML’s lunch.
Tradeoffs? File-per-workflow now; multi-file? Coming. Parallelism implicit via ports, explicit fan-out needed.
Still—game for pipelines craving visuals without chains.
One punchy demo seals it. Chain greet → shout → LLM prompt → API call. All typed. Diagram evolves as code does. Version control? Diff functions, not squiggles.
Ricardo’s dropping this mid-AI boom—perfect. Assistants grok it; MCP integrates. “fw docs” in chat, CLI proxies.
Why Does Flow Weaver Matter for TypeScript Devs?
Because workflows aren’t toys. They’re the glue—microservices orchestrate, data dances, agents deliberate. Visuals clarify; code verifies. Flow Weaver unites ‘em.
No more tab-closing. This changes mental models: workflows as composable functions, graphs as projections.
Grab it. npm i -g flow-weaver. Write. Compile. Visualize. Repeat.
🧬 Related Insights
- Read more: Nometria’s No-Code Escape: Real Founder Freedom
- Read more: OpenAI Structured Outputs vs Zod: JSON Salvation or Vendor Trap?
Frequently Asked Questions
What is Flow Weaver exactly?
A TypeScript compiler that turns annotated functions into executable workflow graphs, with visuals generated from code.
Does Flow Weaver replace tools like Node-RED or Temporal?
Not fully—it’s lighter, code-first. Ideal for TS-heavy stacks; scales via standalone output.
Can I use Flow Weaver with AI coding assistants?
Yep—MCP tools for Claude/Cursor, CLI with context commands. AI fixes errors automatically.
