DEV Community: Veys Aliyev

Taking a Break — See You When I'm Ready

Veys Aliyev — Wed, 11 Mar 2026 14:13:09 +0000

This is a short one.

Velnora is going on pause for an unknown amount of time. Not because something broke, not because I lost interest — the opposite, actually. I want to come back to this with fresh energy instead of grinding through tired.

Why Now

A few things lined up at the same time.

First — I have a project in the crypto space that needs attention. It has been waiting while I poured everything into Velnora's internals, and now it is time to give it the focus it deserves.

Second — March in Azerbaijan is packed with holidays. Novruz is coming, and honestly, I want to actually enjoy it this year instead of spending it staring at TypeScript generics. Sometimes you need to step away from the screen and just live for a bit.

Third — I can feel that I need a reset. The last stretch has been intense: the Unit System, BaseContext, config resolution, integration graphs, adapter loading, runtime detection. A lot of foundational work landed in a short time. The best thing I can do for Velnora right now is let all of that settle in my head before I push into the next phase.

Where Things Stand

The project is in a solid place to pause:

Configuration System — fully designed with 7-layer resolution, merge semantics, extends, freeze, and validation
BaseContext — working expose/query mechanism, GlobalRegistry, typed registry keys
Integrations — all configured, dependency graph built
Adapter loading — H3 adapter's configure stage done
Runtime detection — runtimes detected per project, but not yet implemented

The next big thing when I come back is the runtime implementation — toolchain bootstrapping, execution plans, package manager integration. That is a meaty problem and it deserves a fresh mind, not a burned out one.

Not Goodbye

This isn't the end of Velnora. The architecture is written down, the foundations are in place, and the next phase is clear. Nothing is lost — it is all sitting there, waiting.

When I return, the focus shifts to runtime execution and toolchain integration. That is where the real test begins — and I want to show up for it with a clear head, not a tired one.

For now, it is time to step away for a bit. Enjoy Novruz. Ship something in crypto. Let the ideas breathe.

See you on the other side. 🌙

Configuration System Overhaul

Veys Aliyev — Sat, 07 Mar 2026 17:40:10 +0000

Where We Left Off

Before we dive into the technical stuff — Happy March 8th! 🌷 Today is International Women's Day, and I want to take a moment to celebrate the women in tech, in open source, in every field — your strength, brilliance, and contributions shape the world we build in. Thank you. 💐

The future is built by those who refuse to wait for permission.

Alright —

Last time, the BaseContext was wired up — ctx.expose() and ctx.query() working for real, the GlobalRegistry holding exposed APIs, and makeRegistryObject keeping registry keys sane. The unit communication layer was done. But the system that feeds config into those units? That was still a rough sketch. A few notes in a spec page, no real pipeline, no contracts.

That had to change before anything else could move forward.

The Problem

Here is the thing about building a meta-framework — eventually every unit, every adapter, every runtime needs to ask the same question: "what is my config, and where did it come from?"

And until this point, Velnora did not have a real answer. There was a vague idea of "find a config file and parse it" — but no defined order of precedence, no merge rules when two layers disagreed, no way to share presets between projects, and no validation at all. Every time I tried to wire up something new, the same question came back: which config wins? What if there is a workspace config and a project config and they both set the same key?

I kept working around it. Hardcoding values here, passing things manually there. But that only works until it does not — and with integrations, adapters, and runtimes all needing config at the same time, the duct tape was running out fast.

Oh, and the type system issues from the last post? 😅 To be honest, still there. Not blocking anything, so I kept moving. I will circle back and clean that mess up — but config was the fire that needed putting out first.

Building the Pipeline

So I sat down and designed the full resolution pipeline. The goal was simple: config resolution should be deterministic, layered, and frozen before any unit sees it.

The result is 7 layers, each overriding the previous:

Built-in defaults — hardcoded in the Kernel, always present
Extended presets — shared config packages resolved recursively, depth-first
Workspace config — velnora.config.ts at workspace root
Project config — velnora.config.ts in project root
package.json fallback — "velnora" key, but only if no project config exists
CLI flags — --log-level=verbose and friends
VELNORA_* env vars — highest priority, always wins

One decision I spent time on: layers 4 and 5 are mutually exclusive. If a project config file exists, the package.json key is completely ignored. I could have merged them, but that creates ambiguity — which one wins when they disagree? Instead, the rule is simple: if you have a config file, that is your config. No surprises.

Merge Rules

When two layers provide the same key, the merge behavior depends on the type:

Objects → deep merge, later layer wins per key
Arrays → concatenated, later layer appends
Primitives → last-write-wins

The decision to concatenate arrays instead of replacing them was deliberate. In a monorepo, you might declare some integrations at the workspace level and others at the project level. Replacing would force you to redeclare everything. Concatenating lets you build on what the workspace provides. It feels natural once you see it in action.

Presets and `extends`

Both workspace and project configs can extend shared presets. This is the part that unlocks reuse across teams — a company can publish @company/velnora-preset-react and every project just extends it instead of copying the same config.

Presets resolve recursively and depth-first, merging bottom-up before the config's own values are applied. I borrowed this pattern from how TypeScript's tsconfig.json extends works — familiar, predictable, no magic.

Freeze and Validate

After resolution, the entire config object is deeply frozen. No mutations. No "just tweak this one value during build." If a unit needs different config, it should be in the config file — not patched at runtime. This was a hard line to draw, but it eliminates an entire class of bugs where one unit's mutation silently affects another.

Validation happens before freezing — every resolved config runs through a strict schema (via untyped or Zod). Unknown keys get a warning and are stripped. Errors include the source file and the key that failed. No deferred validation, no "we will check later." If the config is bad, you know immediately.

Putting It to Work

With the config pipeline in place, I moved into implementation.

First — a Graph structure for integrations. Before configuring anything, the system needs to understand the relationships between units — who depends on whom, what order things should initialize in. So I built a general-purpose graph tree that maps out those dependencies. The key decision here was designing it to be reusable — it is not tied to integrations specifically. The same graph can be used for adapters, runtimes, dependency resolution, or anything else that needs a directed relationship tree later. Build the abstraction once, use it everywhere.

With the graph in place, all integrations are now fully configured. The config resolution feeds into the integration loading pipeline, and each integration gets its resolved config through the BaseContext. That loop is closed.

Next — adapter loading. Adapters now load through the system properly, resolved from config, classified, and handed to the Kernel. The H3 adapter's configure stage is done — it receives its config, sets up its context, and is ready for the dev and build lifecycle hooks.

Then I went through each project and detected the runtime for each one. The Kernel now knows which runtime belongs to which project. But here is the honest part — the runtimes do nothing yet. 😄 They are detected, assigned, sitting in the right slots. But the actual runtime implementation — toolchain bootstrapping, execution plans, package manager integration — is still the open question from the last post. The runtimes are placeholders waiting for the research to finish.

What Is Next

The config system is done. Integration configuration is done. Adapter loading and the H3 configure stage are done. Runtime detection is done. What is not done is making the runtimes actually do something — which means the next step is the same one I paused on last time: designing the runtime implementation. How toolchains boot, how execution plans get built and dispatched, and how the package manager API connects. That is the next wall to break through.

One Context, One Registry, and Knowing When to Stop

Veys Aliyev — Wed, 04 Mar 2026 14:28:33 +0000

Last post, the first runtime and adapter were alive. The type system had been fighting back — declaration merging across packages, build tool swaps — but honestly? I kind of forgot about that problem. It is still there, just not blocking anything right now. Sometimes you move forward and the old fight waits. 😄 The units existed. They could register. But the plumbing between "units declared in a config file" and "units actually running" did not exist yet.

That changed. This round of work is quieter than the last, but it touches everything: config resolution, a shared base context, a working expose-and-query system, and a few small utilities to keep the registry sane.

First Things First: Loading the Units

Before anything else can work, the Kernel needs to know what units it is dealing with. That is what config.resolve.units does — it takes the flat list of units from your config file and resolves them into something the Kernel can actually use. The units go in as references — strings, factory functions, imported objects — and they come out as loaded, validated, ready-to-boot definitions that the Kernel knows how to classify and initialize.

This is the bridge between "I declared units in my config" and "the Kernel knows what to do with them." Without it, the unit array is just data sitting in a file. With it, the Kernel can classify units by kind, topological-sort them by dependencies, and start calling lifecycle hooks in the right order.

It is not glamorous work. But it is the plumbing that makes everything else possible.

One Context to Share Them All

With units resolved, the next question is: what do they get to work with? Every unit kind in Velnora gets a context object — the thing passed into lifecycle hooks like configure() and build(). The context is how a unit talks to the rest of the system: exposing APIs, querying other units, reading config.

Until now, each context was defined independently. IntegrationConfigureContext had its own ctx.query(). IntegrationBuildContext had its own. AdapterDevContext — same thing, redeclared from scratch. That meant duplicated surface area everywhere, and any change to the shared behavior had to be mirrored across all of them. It was manageable with three unit kinds. It would not be manageable at ten.

The fix is straightforward — create a BaseContext that carries everything shared, and let the specific contexts extend from it. Integration contexts inherit the base and add integration-specific capabilities on top. Adapter contexts do the same. Runtime contexts do the same. The shared parts live in one place. The specialized parts stay where they belong.

This is not a clever idea. It is just the first time it is actually built.

Expose, Query, Done

The BaseContext now fully implements the exposing and querying mechanism — the two operations that every unit needs regardless of kind. This is ctx.expose() and ctx.query() actually working, not just typed, but wired up end-to-end. A unit can expose an API under a key during configure(), and any other unit that declared a dependency on it can query that key and get the real implementation back. No casting, no any, no manual lookups. The foundation that the entire Unit System was designed around is now real.

Backing the BaseContext is the GlobalRegistry — a central registry object that holds all exposed APIs at runtime. When a unit calls ctx.expose("docker", dockerApi), it writes to the GlobalRegistry. When another unit calls ctx.query("docker"), it reads from the same place. One source of truth for the entire unit graph.

Every registry entry is keyed, and the keys are properly typed and enforced. The same key that TypeScript checks at compile time is the one used to look things up at runtime. If the types say "docker" exists, the runtime registry has a slot for "docker". If they do not, the slot does not exist and the query fails loudly.

With these in place, the BaseContext is not just a shared interface anymore. It is the working layer that integrations, adapters, and runtimes all build on top of. The thing that was just types two posts ago is now running code.

A Helper for the Lazy

One small helper that came out of this work — makeRegistryObject. It is a convenience for lazy people. You give it a name and a shape, and it builds you a nested object where every level is also a usable string key. So instead of writing "kernel:config:units" by hand and hoping you did not typo it, you just do result.config.units and it gives you that exact string. You can use it as a lookup key and dot into it for child keys — both at the same time.

For example, makeRegistryObject("kernel", { config: { units: "units" } }) gives you a value where result is "kernel", result.config is "kernel:config", and result.config.units is "kernel:config:units". Each level works as a registry key. No manual string building, no typos, full autocomplete.

It is a tiny thing. But in a monorepo with a growing number of registry keys, it saves a lot of stupid mistakes.

The Pause

After wiring up the base context and the config resolution, I started pushing into the runtime implementation — the actual guts of how a runtime like Node or Bun boots its toolchain, resolves packages, and executes code. And then I stopped.

Not because something broke. Because I realized I was about to make decisions that would be very expensive to undo. The runtime layer touches everything: how units get their toolchains, how execution plans are built, how the package manager abstraction plugs in, how thread-mode and process-mode execution diverge. One wrong abstraction here and every adapter, every integration, every future runtime inherits the mistake.

So I went back to research. Reading through the earlier design notes, sketching alternatives, revisiting the Toolchain API and the Adapter Protocol to see if the boundaries still made sense after everything that changed in the last few rounds. Sometimes the most productive thing you can do is stop coding and think. This is one of those times.

What Is Next

Once the runtime design solidifies, the next step is implementing it: a real Node runtime that boots its toolchain through the BaseContext, resolves packages through the registry, and produces execution plans that adapters can consume without knowing which runtime is behind them. That is the test that proves the whole stack works end-to-end.

Filling the Unit System: IntegrationUnit, AdapterUnit, and the Full Boot Sequence

Veys Aliyev — Sat, 28 Feb 2026 14:39:19 +0000

Last post, the Unit System had its first real types — RuntimeUnit, PackageManager, and defineRuntime(). The runtime layer was done. But a runtime by itself does nothing. It knows how to run things, but nothing is asking it to run anything yet. The system needed the other two unit kinds — integrations and adapters — before any of it would actually connect.

IntegrationUnit

IntegrationUnit is the interface for framework-specific plugins — React, NestJS, Angular, Docker as an orchestrator, and anything else that wires into the Velnora lifecycle. If runtimes are the foundation and adapters are the build tools, integrations are the things that actually give a workspace its identity.

The key design decision here was making all lifecycle hooks optional. An integration only implements what it needs. If it just needs to expose an API during init, it implements configure(). If it also needs to do something at build time, it adds build(). If it needs neither, it can still exist as a unit that just declares capabilities for others to depend on.

This is Interface Segregation in practice. The Kernel duck-types before calling — 'configure' in unit — so there is no dead code, no empty method stubs, no forced implementations.

Two Phases, Two Contexts

Every unit kind now gets phased contexts. The configure() hook receives an IntegrationConfigureContext — full access to ctx.expose() and ctx.query(). The build() hook receives an IntegrationBuildContext — query-only, because by the time you are building, registration is closed. No new APIs can be exposed during a production build.

Right now all three unit kinds share the same idea, but the context types are not fully separated yet. Runtimes, adapters, and integrations each have different phase-specific needs, and the concrete context interfaces still need to be split out per kind. That is a task for the next round.

This separation is not just for safety. It makes the intent clear at the type level. If you are inside build(), TypeScript will not even let you call expose(). You know exactly what phase you are in by looking at the context type.

`defineIntegration`

Just like defineRuntime(), the factory is thin. You pass your integration definition, it injects kind: 'integration' and returns a VelnoraUnit. Same pattern, same type inference, same generics capturing literal strings from requires and capabilities.

All three define helpers — defineRuntime(), defineAdapter(), and defineIntegration() — support a second calling convention: a factory function. Instead of passing a plain object, you can pass a function that receives ConfigEnv (command, mode, etc.) and returns the config. This is useful when you need to change behavior based on whether you are running dev or build. The factory wraps your function and injects kind at call-time.

Both conventions produce the same thing. Static for simple cases, factory for environment-aware ones. The pattern is identical across all three unit kinds.

Init Order

In theory, integrations should initialize last — after runtimes, after adapters. The idea is that by the time an integration runs its configure() hook, every runtime is booted and every adapter is ready, so the integration can safely query anything it depends on.

Within the integration tier, a topological sort by requires and optionalRequires would determine exact ordering. So if your integration depends on 'docker', the Docker integration would configure first. This is the design — the actual resolver is not wired up yet.

One open question: what happens when A requires B and B requires A? A circular dependency. The honest answer is I have not decided yet. The resolver could reject it at startup, or it could try to break the cycle with a warning. For now the design assumes no cycles — if you create one, you get what you deserve. This will need a real answer before the resolver ships.

AdapterUnit — The Middle Layer

With integrations done, the adapter was next. AdapterUnit represents build-tool orchestrators — Vite, Webpack, Turbopack, esbuild, and similar. Unlike integrations, adapters have required hooks: dev(project, ctx) and build(project, ctx). Both take a Project — the specific project directory the adapter is operating on — plus a typed context. An adapter must handle both modes. There is no optional here — if you are an adapter, you know how to start a dev server and you know how to produce a production build. And dev() returns a DevServerResult — connection info that the Host uses to wire up the dev server.

But the biggest design shift from earlier iterations of the spec was removing the mode field. I originally had mode: 'thread' | 'process' on the adapter itself. That was wrong. Whether something runs in-thread or as a child process is not the adapter's decision — it is the runtime's decision. A Vite adapter should not care if it runs inside Node's process or gets spawned separately. It just says what to run. The runtime says how. Velnora executes the plan.

So the adapter queries the runtime via ctx.query(), calls something like execute(), and the runtime returns a declarative ExecutionPlan — a discriminated union. In thread mode, it carries a run function that Velnora calls in-process. In process mode, it carries the binary, args, and cwd for Velnora to spawn as a child process. Either way, the adapter does not care which one comes back. Same adapter code works with Node, Bun, or any other runtime. The adapter never changes.

Like integrations, adapters get phased contexts — AdapterDevContext for dev() and AdapterBuildContext for build(). And defineAdapter() follows the same pattern: static object or factory function, kind injected automatically, full type inference on dependencies.

The Full Boot Sequence (In Theory)

The init order is not implemented yet, but in theory this is how it should work:

Runtimes — language runtimes boot first
Adapters — build tools next
Integrations — frameworks last

Within each tier, topological sort by requires and optionalRequires would determine exact ordering. You drop units into one array and the Kernel figures out the rest — that is the design. What actually happens in practice is a different story, but this is the contract the system is built around.

All three unit kinds are now implemented. The runtime layer has RuntimeUnit, PackageManager, Toolchain, and defineRuntime(). The integration layer has IntegrationUnit, phased contexts, and defineIntegration(). The adapter layer has AdapterUnit, the execution model split, and defineAdapter(). The Unit System is complete — every unit kind has its interface, its factory, and its place in the boot sequence.

A Note on AI and How I Work

I use AI for generating tests and JSDoc. In rare cases, code. And even when it generates code, I review it multiple times before applying it to the project and committing. The code architecture is mine. But the way it gets seen — which packages should exist, how the spec should read, how the design should be documented — that is where I use Notion AI. Each time I work on a feature, it takes almost a couple of hours: understand the design, consult with AI, analyze it again, and then document it properly. The thinking is mine. The documentation process is a collaboration.

But right now I hit the limits. Almost every code assistant out there has usage caps — except Notion AI — and I have burned through all of them. That means tests and JSDoc generation are temporarily gone until I get a local assistant running. I have been setting one up, but it is not fully ready yet — right now I am working on creating a connection between my PC and my Mac so I can run and use it remotely, distance independent.

What Is Next

The Unit System is complete — every unit kind has its interface, its factory, and its place in the boot sequence. The next step is wiring them into the Kernel's actual resolver and making the first real unit packages. That means real defineRuntime() calls for Node and Bun, a real defineAdapter() for Vite, and a real defineIntegration() for React. Interfaces are done. Now it is time to fill them.

Filling the Unit System: IntegrationUnit, AdapterUnit, and the Full Boot Sequence

Veys Aliyev — Wed, 25 Feb 2026 18:52:17 +0000

IntegrationUnit

This is Interface Segregation in practice. The Kernel duck-types before calling — 'configure' in unit — so there is no dead code, no empty method stubs, no forced implementations.

Two Phases, Two Contexts

`defineIntegration`

Both conventions produce the same thing. Static for simple cases, factory for environment-aware ones. The pattern is identical across all three unit kinds.

Init Order

AdapterUnit — The Middle Layer

The Full Boot Sequence (In Theory)

The init order is not implemented yet, but in theory this is how it should work:

Runtimes — language runtimes boot first
Adapters — build tools next
Integrations — frameworks last

A Note on AI and How I Work

What Is Next

One Array to Rule Them All: Designing Velnora's Unit System

Veys Aliyev — Sat, 21 Feb 2026 08:48:08 +0000

v0.1 is tagged. The skeleton stands. And the original plan said v0.2 would be graphs — dependency graphs, project graphs, the whole resolution layer.

But after researching it, I realized graphs are useless at this stage. There is no real workspace to resolve yet. No integrations to connect. The graph would just be a piece of code that does nothing because it has nothing to operate on. It would exist purely to satisfy the roadmap, not to solve an actual problem.

So I skipped it. Graphs will come later, in a future release, when there are enough moving parts to make resolution meaningful. For now, the real next step is integrations — the things that actually fill the workspace. That became the new v0.2 target.

And the first question was: how do integrations even enter the system?

The answer started with a problem I kept hitting in earlier rewrites — three separate registration paths. Integrations had one way in, adapters had another, and runtimes were their own thing. Every time I added something, I had to remember which path it belonged to. It was manageable at the scale of v0.1, but I could already feel it becoming a mess.

So I asked: what if everything entered the same way?

The Unit System

That is the core idea behind what I am calling the Unit System. One array in the config. One resolver in the Kernel. Three typed helpers — defineIntegration(), defineAdapter(), defineRuntime() — for type safety. But underneath, they all produce the same thing: a VelnoraUnit.

The Kernel does not care what kind of unit you are. It collects them all, resolves dependencies, and initializes in the correct order. Kind only matters for when you init — runtimes first, then adapters, then integrations — and for the specific hooks you expose.

This felt right immediately. The config went from three separate concepts to one flat array. And the Kernel went from three separate loaders to one resolver.

Dependencies Without Imports

The part that took the most thinking was inter-unit communication. Units should never import each other directly — that would create hard coupling and break the whole plugin model. But they need to talk to each other. A Kubernetes integration needs Docker. A Spring Boot integration needs a JVM runtime.

The solution is a capability-based system. Each unit declares what it provides (capabilities) and what it requires. The resolver matches them by string. If you require 'docker', any unit that has 'docker' in its capabilities array satisfies it.

But here is where it gets interesting — the type safety.

I built a global type registry using TypeScript declaration merging. When you install @velnora/integrations-docker, its type declarations automatically register DockerApi into Velnora.UnitRegistry. Then when you call ctx.query('docker') inside another unit, TypeScript knows the return type is DockerApi. No imports. No type casting. Just install the package and the types flow.

Hard dependencies (requires) return the API directly. Soft dependencies (optionalRequires) return T | undefined. The generics on the define helpers infer the literal strings from the arrays, so TypeScript knows exactly which queries are safe and which might be undefined.

This is the kind of thing that makes me love TypeScript. The type system is doing real architectural work here — it is enforcing the dependency contract at compile time.

Composite Units

One design decision I am particularly happy with: composite units. A single unit can bundle child units inside itself using a units[] array. The user adds one thing to the config, and the Kernel unpacks everything.

Docker is the perfect example. As a user, you call docker() and you get both the integration (build images, push, create networks) and the runtime (Docker Engine). One function call. The Kernel flattens the tree, resolves dependencies across all of them, and inits in order.

This keeps the config clean. The user does not need to know the internal structure of what they are adding. They just add docker() and everything works.

First Interfaces: RuntimeUnit & PackageManager

With the design in place, it was time to write actual types. The first two interfaces I implemented were RuntimeUnit and PackageManager.

A RuntimeUnit defines what a language runtime looks like to the Kernel — its toolchain, its supported package managers, and a resolvePackageManager() method that figures out which one to use for a given project directory. The PackageManager interface captures the basics: install, add, remove, and how to resolve the lock file. Nothing fancy — just enough contract for the Kernel to work with any runtime without knowing its internals.

`defineRuntime` — The First Helper

With the interfaces in place, the next step was defineRuntime() — the first of the three typed factory helpers.

The reason this one came first is simple: runtimes are the bottom of the stack. Everything else depends on them. An adapter needs to know what runtime it is orchestrating. An integration needs to know what language capabilities are available. If the runtime layer is not solid, nothing above it can be trusted.

defineRuntime() is a thin function. You pass it your runtime definition — name, version, capabilities, toolchain, package managers — and it gives you back a VelnoraUnit. That is it. No magic. No hidden state. The function exists purely for type inference — so TypeScript can capture the exact literal strings you declared in requires and capabilities, and carry that information all the way through to ctx.query() later.

This is the pattern all three helpers will follow. defineAdapter() and defineIntegration() will look almost identical in shape. The only difference is the kind-specific fields each one adds. But the contract is the same: you define what you are, what you provide, and what you need. The Kernel handles the rest.

What Is Still Open

There are questions I have not answered yet. Should capabilities support versions — like 'jvm@21'? How should the resolver pick between multiple providers of the same capability when both Node and Bun provide 'javascript'? Should there be lifecycle hooks for cross-unit events?

These are real design questions, not implementation details. They will shape how the Unit System scales. But the core is solid: one array, capability-based resolution, type-safe queries, composite unpacking, and now the first real types and factory in place. The runtime layer has a shape — the rest of the unit kinds will follow the same pattern.

Static Serving, H3, and the Last Piece of v0.1

Veys Aliyev — Wed, 18 Feb 2026 06:20:45 +0000

Last post, the Kernel was booting, the Host was listening, and projects were being discovered and routed. The skeleton was alive — but it had no skin. The Host could tell you about a project, but it could not actually serve one. That is what changed this week.

Static Serving from `src/`

The Host now serves files from src/ — just serving. No fallback logic, no integration detection. I did not even try to find any integration today because they do not exist yet at all. The entry point is src/index.html. Simple.

For later, this will be moved to the fallback section — once integrations are real, static serving becomes the baseline when nothing else claims the request. But for now, it is the only thing running.

I also added a simple JSON endpoint — $path/__json — to see a small JSON about the app itself. Just for debug, or maybe later for the app. It depends. It may be needed or it will be removed. Future releases will show.

The Real Story: H3

But the real story here is H3.

H3 is the HTTP framework I chose for Velnora's Host early on, but this was the first time I actually went deep with it. And the experience was something different.

If you come from Express — req, res, next() — H3 will feel weird at first. There is no req and res. You get an event object. You do not call res.send(). You return the response. If you return nothing, the next handler runs. That is it.

Middleware is not a stack you push onto. It is a set of event handlers composed together. The framework decides what runs. You just define handlers and compose them.

For the first few hours, my muscle memory kept fighting it. I kept reaching for Express patterns that do not exist here. The documentation is good but minimal — the UnJS ecosystem assumes you read source code. That is fine, but it is a different experience.

Once I stopped mapping H3 onto Express and started thinking in its own terms, things clicked. The code got shorter. The composition got cleaner. Static serving slotted in naturally alongside the Vite middleware.

Static serving is now the baseline. Every project in a Velnora workspace gets it for free. No config needed.

The Last Piece: `velnora init`

With serving working, there was one thing left for v0.1 — a way to start a workspace from nothing.

I built the velnora init <directory> command. The directory is required for now. Later, when the questionary is implemented — including questions from integrations — it will be optional or changed. But the decision here was deliberate: keep it minimal, keep it honest. The init command does not pretend to know what your workspace looks like yet. It just gives you the two files that make a valid Velnora workspace — a config and a package.json — and gets out of your way.

The rest is manual for now, alas. This is where the questionary will live later. But for v0.1, scaffolding an empty workspace is enough to close the loop.

v0.1 — The Skeleton Is Complete

And with this, v0.1 is done. There is nothing flashy to show — no UI, no dashboard, no demo. But the pipeline is real. The Kernel boots, the Host serves, discovery works, and velnora init scaffolds a workspace. That is the whole point of v0.1: prove the pipeline exists.

I will tag it as v0.1, but I will not publish yet. There is no rush. The code is there, the tag marks the milestone, and that is enough for now.

Next: I am going to analyze the v0.2 release scope to decide which task comes first. The skeleton is standing — now it needs muscle.

Building a Type-Safe Runtime from Scratch: Kernel, Host & Inferred CLI Types in Velnora

Veys Aliyev — Sat, 14 Feb 2026 20:18:59 +0000

Starting the Schemas

So, discovery is working. Now we need to define what we are discovering.

This is where the schemas come in.

The goal is to have a strict contract for every part of the system. If Velnora detects a package, it needs to know exactly what that package is capable of.

The first question was: what does a discovered project actually look like at runtime? I needed a Project interface — a strict contract that captures everything the system needs to know about a package.

But package.json alone isn't enough. It gives you the name, version, and dependencies — but nothing Velnora-specific. Where does the adapter config go? The framework hints? The build targets? Polluting package.json with custom fields felt wrong.

So the Project interface pulls from two sources of truth:

packageJson — the raw package.json, stored as-is so adapters and plugins can inspect dependencies without re-reading the file.
config — the resolved VelnoraAppConfig from velnora.config.ts (or an empty object if none exists). This is where all Velnora-specific metadata lives.

On top of that, each project gets:

A stable, path-based name derived from the workspace root (e.g., packages/app-one).
A human-readable displayName from package.json (e.g., @example/app-one).
The absolute root path and a routable path for the Host.

Two Levels of Configuration

The configuration itself works at two distinct levels:

VelnoraConfig (Global): Lives in the workspace root. Defines the rules for the entire repo — plugins, shared defaults, and global overrides.
VelnoraAppConfig (App-Specific): Lives inside each project folder. Defines the specific framework, build targets, and unique needs of that application. This is what ends up in Project.config.

By separating them, we get strict typing for each context while keeping the overall system cohesive.

The Pivot to Execution

But as satisfying as it was to define these interfaces, I realized something.

It is okay to have perfect types, but right now, running the app is the first priority.

There is no point in building a complex config parser if the core runtime isn't spinning up the application yet. So I decided to simplify.

I am shifting focus:

First: Make the app run.
Then: Parse velnora.config.ts and apply the fine-grained configs.

The schemas are defined, but the implementation of their full power can wait. Execution comes first.

Kernel & Host Implementation

So that is exactly what I did. I went ahead and implemented the Kernel and Host—the two core runtime pieces that boot up Velnora. The Kernel orchestrates everything: loads the config, resolves projects, and hands off to the Host. The Host spins up the HTTP server and mounts adapter middleware.

But as soon as the runtime started taking shape, I hit a wall. Typing issues.

The dev command needs options like --host, --port, --mode, --root. These options are parsed by the CLI, but they are also needed deeper in the system—by the Host when it starts listening, and by the Kernel when it calls bootHost(). So the question becomes: where do the types live?

The obvious answer would be to use something like Commander.js and just pass the parsed result around. But here is the problem: libraries like Commander have insane adoption—almost every Node.js CLI uses it—yet the typing story is practically nonexistent. You define commands, options, arguments… and then you get back any or loosely typed objects. You lose all the safety the moment you try to pass parsed options to another part of your system.

@velnora/cli-helper & The Lazy Developer's Split

I wanted both: great runtime ergonomics (chainable API, descriptions, defaults) and full type inference (so that when I define --port <number>, the result type knows port is a number, not string | undefined). That is why I built @velnora/cli-helper—a thin, Commander-like API that infers the full option type from the definition using inferCommandType<typeof command>.

With that in place, the lazy developer in me took it one step further: split the CLI into two separate packages. Same practice from previous versions.

@velnora/commands (the helper package) — exports the command definitions and their inferred types.
@velnora/cli — imports those commands and executes them. Thin wrapper. No business logic.

The commands package defines each command and exports both the command object and its inferred type:

export const devCommand = program
  .command("dev")
  .description("Start the development server in watch mode.")
  .option("--host <string>", { description: "Host to run the development server on" })
  .option("--port <number>, -p", { description: "Port to run the development server on" })
  .option("--watch, -w", { description: "Enable watch mode", default: false })
  .option("--mode <development|production>", { description: "Set the mode", default: "development" })
  .option("--root <string>", { description: "Root directory of the project", default: "." });

export type DevCommandOptions = inferCommandType<typeof devCommand>;

View the full source on GitHub

By exporting DevCommandOptions from the commands package, I use it as the typing for the Host application and the Kernel's bootHost() functionality. No duplication. The types are inferred directly from the command definition—if I add a new flag, the entire chain updates automatically.

@velnora/commands  →  defines commands + exports types (DevCommandOptions)
       ↓
@velnora/kernel   →  imports DevCommandOptions for bootHost()
       ↓
@velnora/host     →  imports DevCommandOptions for server startup
       ↓
@velnora/cli      →  imports commands, executes them, passes options down

This is the kind of lazy that pays off. One source of truth for the command shape, and TypeScript does the rest.

v0.0.1 — It Runs 😄

Not ready for publish (don't get excited), but it runs. And that matters.

Here is what velnora dev gives you today. A request to the root / returns a JSON overview of the entire workspace:

{
  "velnora": true,
  "projects": [
    {
      "name": "packages/app-one",
      "displayName": "@example/app-one",
      "path": "/@example/app-one"
    },
    {
      "name": "libs/lib-one",
      "displayName": "@example/lib-one",
      "path": "/@example/lib-one"
    }
  ]
}

This is temporary—eventually the root will serve the Velnora dashboard. But right now, it proves the pipeline works: CLI → Kernel → Host → discovered projects → HTTP response.

And for each project path, the Host returns a small status object:

{
  "name": "libs/lib-one",
  "displayName": "@example/lib-one",
  "root": "<project-root>/libs/lib-one",
  "status": "registered"
}

Discovery works. The Kernel boots. The Host listens. Projects are registered and routed. It is not much—but it is real. The skeleton is alive.

Building v0.1: The 4th Gen & Notion Shift

Veys Aliyev — Wed, 11 Feb 2026 19:00:19 +0000

I am currently working on Release 0.1. Recently, I completed the project discovery phase. I wouldn't say I hit "hard walls," but a significant amount of time went into refactoring. In fact, I completely closed the GitHub project board and have fully moved to Notion for task management.

The bulk of the work has been a massive refactor. You can see the start of it in this commit. I re-created the utils, types, and cli packages with a new structure.

Why rewrite it?

You might ask: Why are you rewriting it? To be honest, this is the 4th time I've rewritten it.

I found hard issues in the previous build. But the real problem was that I was stuck without a proper task management system. I was coding without a map. The current build targets Notion as the source of truth. The new rule is simple: Document first, then code.

Before I wrote a single line of code for this refactor, I spent almost a week just documenting what it would be. It makes you think: What is actually going on? Why didn't I start this way earlier? The truth is, I just wasn't that type of person. I wanted to build, not plan. But now, alongside the project, I am growing too.

Fighting Gravity

I am also fighting with Antigravity. It is powerful (accessing code and web simultaneously), but it struggles with context.

In my session, I set the context for "project discovery", but after a few prompts, it loses the plot and jumps forward to future tasks like Adapters or tsconfig syncers. It runs forward to be fast, even when I just need to review the previous step.

I found a workaround: Resetting.

I create a new session and feed it the artifacts from the old session as data. This forces it to stop running forward and just think on the provided data.

The Flip Side (Notion AI)

But here is the contrast. The same Gemini models, running inside Notion?

Voila.

It is working so well. The context holds. The logic flows. It feels like a completely different tool. I have to say it: I love @NotionHQ for the product they are building. Thanks to them.

Discovery & Detection (Core Working)

And just like that, the core discovery logic is functioning.

The core rule is simple: we look for the workspaces field in package.json. That is the entry point for working with monorepos.

The logic follows two steps:

Find the root: Locate the root package.json with the workspaces definition. Its directory becomes the workspaceRoot.
Parse and Detect: Scan the packages, parse their configs, and map the structure.

The result looks something like this:

[
  {
    name: '@example/app-one',
    root: '.../packages/app-one',
    config: { name: '@example/app-one', version: '0.0.0-dev.0' },
    configFile: '.../packages/app-one/package.json'
  },
  {
    name: '@example/lib-one',
    root: '.../libs/lib-one',
    config: { name: '@example/lib-one', version: '0.0.0-dev.0' },
    configFile: '.../libs/lib-one/package.json'
  }
]

It’s real. It’s detecting. It’s working.

This is just the basic detection logic. In later releases, I will work on making it truly understand the project, not just find it. But for now, it's a start.

Why Velnora Exists — The Silence Before the Obsession

Veys Aliyev — Sat, 07 Feb 2026 09:31:00 +0000

For a long time, my writing focused on Docker, Kubernetes, and CI—the tools that promised to tame complexity.

And they did—at least at first.

Deployment pipelines replaced fragile scripts. Containers replaced snowflake servers. Infrastructure became reproducible.

But the deeper I went, the more something felt off.

We weren’t eliminating complexity.

We were moving it upward.

In frontend development, raw HTML/CSS/JS gave way to frameworks like React, Angular, and Vue. Codebases became cleaner. But applications grew heavier—more tooling, more configuration, more layers.

The same pattern showed up in infrastructure.

Every layer I mastered—containers, clusters, pipelines—shifted the chaos somewhere else:

Fix deployment → integration breaks

Fix containers → config explodes

Fix configuration → observability becomes painful

That was when the silence started.

I wasn’t stuck.

I was investigating.

The Rejected Project That Started It All

I’ve never been satisfied with “it works.”

When I wrote about Docker, I wasn’t just using it—I was digging into how it actually worked. That instinct pulled me away from blogging for almost two years.

The simple answers stopped being enough.

Why did building software feel heavier every year… even though our tools kept improving?

It didn’t start as a big architectural vision.

It started as a rejected diploma project.

During my master’s degree, I proposed building a custom bundler. My professors didn’t accept it—maybe it was too ambitious, maybe too broad.

So I kept going on my own.

I tried to rebuild Vite just to understand how modern tooling really works.

That’s when reality hit:

Bundlers aren’t just complex.

They’re bottomless.

So I reframed the problem.

Instead of replacing Vite, I asked:

What if I built above it?

What if Angular and NestJS—two frameworks that normally live in separate worlds—could share a single build pipeline?

I stopped trying to be the engine.

I started building the glue.

Walking Away—and Coming Back Different

Obsession is rarely linear.

There were months when the glue didn’t stick. I convinced myself I had solved the problem—until I saw how much complexity still sat underneath.

Tooling fighting tooling.
Layers stacked on layers.

I stepped away.

Went back to writing safer DevOps posts.

Tried to convince myself that the industry stack was good enough.

But the satisfaction was gone.

The feedback felt quiet.

Like I was contributing noise instead of signal.

That’s when I realized something:

If I didn’t build this, I would spend my career managing complexity instead of removing it.

So I closed the blog.

Stopped chasing validation.

Went back to code.

This time, with a different question:

Why is DevOps a separate phase at all?

Why does every project require developers to leave business logic behind just to configure Dockerfiles, pipelines, manifests?

Every time we do that, we’re not solving a user problem.

We’re solving the computer’s.

That was the pivot.

What if infrastructure became a side effect of writing software?

What if a system understood your code deeply enough to generate containers, configs, and CI pipelines automatically?

In December 2024, I pushed the first commit.

That was the real beginning.

What Is Velnora?

Before diving into architecture—one confession.

The project wasn’t always called Velnora.

Originally, it was Fluxora.

It sounded… fine.

Too fine.

Like another state management library.

This wasn’t about state.

It was about orchestration.
Velocity.
Systems thinking.

So Velnora was born.

Velnora is a meta-framework for systems.

If React manages the lifecycle of a component—mount, update, unmount—

Velnora manages the lifecycle of an application:

Resolve → Build → Deploy → Run

It sits above frameworks and below infrastructure.

React. Angular. NestJS.
Docker. Kubernetes.

Velnora is the missing layer between them.

At its core is a layered plugin architecture. The kernel understands graphs and lifecycles. Everything else—TypeScript compilation, dev servers, cloud targets—is implemented through adapters.

Today it speaks Vite.

Tomorrow? Something else.

Velnora resolves monorepos into dependency trees, unifies builds across ecosystems, and generates infrastructure automatically.

Once that layer exists, we stop writing glue code.

We start building platforms.

This is where the origin story ends.

Next comes the real work: deep dives into architecture, orchestration engines, and the core runtime.

Let’s make building software lighter instead of heavier.
This post is part of an ongoing series documenting the design and evolution of

• GitHub: https://github.com/Velnora/velnora

• Notion Space (roadmaps, design notes, community):
https://www.notion.so/velnora/invite/476be70c8d26fad67beda510c00fe0b61e4512a5

If you want to see how Velnora is taking shape—from architecture experiments to production-grade tooling—you’re welcome to follow the journey or get involved.

DEV Community: Veys Aliyev

Taking a Break — See You When I'm Ready

Why Now

Where Things Stand

Not Goodbye

Configuration System Overhaul

Where We Left Off

The Problem

Building the Pipeline

Merge Rules

Presets and extends

Freeze and Validate

Putting It to Work

What Is Next

One Context, One Registry, and Knowing When to Stop

First Things First: Loading the Units

One Context to Share Them All

Expose, Query, Done

A Helper for the Lazy

The Pause

What Is Next

Filling the Unit System: IntegrationUnit, AdapterUnit, and the Full Boot Sequence

IntegrationUnit

Two Phases, Two Contexts

defineIntegration

Init Order

AdapterUnit — The Middle Layer

The Full Boot Sequence (In Theory)

A Note on AI and How I Work

What Is Next

Filling the Unit System: IntegrationUnit, AdapterUnit, and the Full Boot Sequence

IntegrationUnit

Two Phases, Two Contexts

defineIntegration

Init Order

AdapterUnit — The Middle Layer

The Full Boot Sequence (In Theory)

A Note on AI and How I Work

What Is Next

One Array to Rule Them All: Designing Velnora's Unit System

The Unit System

Dependencies Without Imports

Composite Units

First Interfaces: RuntimeUnit & PackageManager

defineRuntime — The First Helper

What Is Still Open

Static Serving, H3, and the Last Piece of v0.1

Static Serving from src/

The Real Story: H3

The Last Piece: velnora init

v0.1 — The Skeleton Is Complete

Building a Type-Safe Runtime from Scratch: Kernel, Host & Inferred CLI Types in Velnora

Starting the Schemas

Two Levels of Configuration

The Pivot to Execution

Kernel & Host Implementation

@velnora/cli-helper & The Lazy Developer's Split

v0.0.1 — It Runs 😄

Building v0.1: The 4th Gen & Notion Shift

Why rewrite it?

Fighting Gravity

The Flip Side (Notion AI)

Discovery & Detection (Core Working)

Why Velnora Exists — The Silence Before the Obsession

Presets and `extends`

`defineIntegration`

`defineIntegration`

`defineRuntime` — The First Helper

Static Serving from `src/`

The Last Piece: `velnora init`