DEV Community: Moaaz Yahia

What If Building a Website Didn't Need a Build Step?

Moaaz Yahia — Wed, 30 Sep 2026 02:26:52 +0000

There is something strange about modern web development.

You create a page.

You write some content.

You add a few styles.

And somehow, before you can see your website, you need a build pipeline, a dependency tree, a framework, a bundler, configuration files, and a collection of abstractions standing between you and the thing you actually wanted to build.

Sometimes that complexity is justified.

For applications, large frontends, and highly interactive products, it can be essential.

But what about a portfolio?

A blog?

Documentation?

A personal website?

A content-driven site that mostly needs to do one thing well:

serve the content.

That question is what led me to build JPROT.

JPROT takes a different approach

JPROT is a Node.js site generator designed around a simple idea:

Write content. Customize the site. Run it.

No build step is required.

Your pages live as Markdown files inside content/.

content/
├── about.md
├── projects/
│   ├── jprot.md
│   └── aeroci.md
└── blog/
    └── first-post.md

You write:

---
title: "My Project"
description: "A short description"
---

## My Project

This is my project.

Save the file.

Refresh the browser.

The page exists.

There is no compilation ceremony standing between the content and the website.

The website is not the configuration file

One thing I wanted to avoid was turning the configuration file into the website itself.

JPROT keeps those responsibilities separate.

The configuration describes the site:

export default {
  title: 'Your Name',
  tagline: 'Full Stack Developer',
  description: 'A short SEO description',
  url: 'https://yoursite.com',
  lang: 'en',
  author: 'Your Name',

  nav: [
    { label: 'About', url: '/about' },
    { label: 'Blog', url: '/blog' },
  ],
}

The Markdown describes the content.

The theme describes the presentation.

Components describe reusable UI.

Plugins extend behavior.

That separation makes the system easier to understand and, more importantly, easier to change.

Start with one command

Creating a JPROT project is intentionally boring.

And I mean that as a compliment.

npm create jprot@latest my-site

Then:

cd my-site
npm start

Your development server starts at:

http://127.0.0.1:4114

You can also initialize an existing directory:

jprot init --portfolio

or:

jprot init --docs

or:

jprot init --resume

The point is not to create another complicated project generator.

The point is to get from empty directory → working website quickly.

Markdown is the content layer

JPROT uses Markdown because content should remain easy to read without the framework.

A page is still a page.

A blog post is still a blog post.

A project is still a project.

You don't need to wrap every paragraph in components just to make the content render.

But Markdown doesn't mean the system has to be primitive.

JPROT supports frontmatter, shortcodes, placeholders, project conventions, blog conventions, and components.

So you can keep writing:

---
title: About Me
description: Who I am and what I build.
---

# Hello

I build software.

while still having a structured site underneath.

Five levels of customization

This is where JPROT starts to become more than a Markdown renderer.

There are five independent ways to customize a site.

1. CSS variables

Change the design directly through:

theme/custom.css

No framework-specific styling system is required.

2. Component overrides

Need a different header?

Replace it.

Need a different homepage?

Replace it.

Need a completely different layout?

Override the component.

3. Markdown components

Components don't necessarily have to be JavaScript.

You can create a Markdown component with frontmatter and placeholders.

theme/components/

This keeps simple UI pieces close to the content model.

4. Themes

Ready-made themes can be copied into the project and customized.

5. Plugins

When you need behavior rather than styling, plugins provide an extension point.

This is where JPROT deliberately keeps its surface small.

A plugin is just a file

A plugin can look like this:

export default {
  name: 'analytics',

  setup({ on }) {
    on('html:head', (html) =>
      html.replace(
        '</head>',
        `  <script defer src="/_a.js"></script>\n</head>`
      )
    )
  },
}

Then:

export default {
  plugins: ['./plugins/analytics.js'],
}

The plugin API exposes a deliberately small surface:

addComponent
addRoute
extendMarkdown
on
config

That constraint is intentional.

A plugin system becomes difficult to maintain when every internal implementation detail becomes part of the public API.

I would rather have a smaller API that can remain stable.

JPROT is not only a generator

One of the things that changed as I built JPROT was the scope of the project itself.

It started from a very simple idea:

generate a portfolio.

But the architecture naturally grew toward something broader.

The same system can handle:

portfolios
documentation
blogs
project pages
resumes
personal websites
content-driven sites

The important part is not the category.

It is the underlying model:

Content
   ↓
Content Graph
   ↓
Routes
   ↓
Rendering
   ↓
Website

That is why I no longer think of JPROT simply as a portfolio template.

It is becoming a general-purpose system for content-driven websites.

The Content Graph

One of the internal ideas behind JPROT is the Content Graph.

Instead of treating every Markdown file as an isolated document, JPROT builds a parsed index of the site's content.

That gives the system a unified view of:

pages
posts
projects
routes
metadata
navigation

This makes features such as navigation, routing, and content-aware tooling much easier to reason about.

The website stops being a folder full of Markdown files.

It becomes a structured content system.

Development without waiting for a build

One of my favorite parts of the workflow is also one of the simplest.

Create:

content/test.md

Write:

---
title: Test Page
---

# Hello

Save.

Refresh.

Done.

The development server watches the project, so you don't need to manually rebuild the entire site just to see a content change.

For a content-heavy website, this feels surprisingly natural.

The browser becomes the immediate reflection of the files you are editing.

But JPROT still has a build

This sounds contradictory.

It isn't.

JPROT doesn't require a build step for development.

But it can export the entire site as static HTML:

jprot export --out dist

That means you can develop dynamically and publish statically.

The workflow becomes:

write
  ↓
run JPROT
  ↓
preview
  ↓
export
  ↓
deploy

So the build exists when it is useful — not because development cannot function without it.

SEO is part of the website

A website generator shouldn't make you rebuild basic web infrastructure from scratch.

JPROT includes support for:

metadata
canonical URLs
sitemap generation
feeds
JSON-LD
PWA support
configurable language and direction

The goal is not to turn SEO into a separate project.

It should be part of producing a website.

Accessibility should not be an afterthought

There is another area where I didn't want the "simple website generator" approach to become an excuse for cutting corners.

JPROT includes accessible SPA navigation features such as:

skip links
focus management
live page announcements

The site can behave like a modern SPA while preserving the fundamentals that make navigation understandable to assistive technologies.

That distinction matters.

Fast navigation is useful.

Accessible navigation is necessary.

SPA navigation without turning everything into a JavaScript application

This is another design decision behind JPROT.

A content site doesn't necessarily need to become a giant client-side application.

JPROT uses server-side rendering while providing SPA-style navigation.

The result is a useful middle ground:

Server-rendered content
        +
client-side navigation
        +
normal URLs

You get fast transitions without having to turn every page into a client-side data-fetching application.

TypeScript without forcing TypeScript

JPROT itself ships TypeScript declarations.

That means a JavaScript configuration can still receive editor assistance:

/** @type {import('jprot').JprotConfig} */
export default {
  title: 'My Site',
}

You don't have to convert the entire project to TypeScript just to get useful type information.

The tooling adapts to the project instead of forcing the project to adapt to the tooling.

The CLI is part of the system

JPROT isn't only:

jprot

The CLI covers the complete workflow.

jprot init
jprot new post "My Article"
jprot g component Hobbies --palette cards
jprot search
jprot add SomeComponent
jprot check
jprot lint
jprot export

There are also site-aware checks.

For example:

jprot lint

can look for things such as broken links, missing metadata, and duplicate anchors.

And:

jprot check

validates configuration and plugins.

That means errors can be found before deployment rather than discovered by a visitor.

And then there is the editor

I didn't want the workflow to end at the terminal.

JPROT also has a Visual Studio Code extension.

It provides:

live preview
JPROT Markdown highlighting
frontmatter highlighting
shortcode support
placeholder highlighting
snippets
project-aware preview

The preview is driven by the project's own JPROT server.

So the editor isn't running a second, approximate implementation of the site.

It is looking at the same system the project actually uses.

JPROT can also be used as a library

This is perhaps the direction I find most interesting.

You don't have to use JPROT only through the CLI.

It exposes a programmatic API:

import {
  createJprot,
  exportSite,
  runLint,
  runCheck,
  scaffoldSite,
} from 'jprot'

For example:

const app = await createJprot({
  root: '/path/to/project',
  port: 3000,
  watch: true,
})

await app.listen(3000)

Or export a site programmatically:

await exportSite({
  root: '/path/to/project',
  outDir: '/tmp/dist',
})

That opens a different door.

JPROT doesn't have to remain a command-line application.

It can become infrastructure that other tools build on.

Why not just use a larger framework?

This is probably the most reasonable question.

There are excellent frameworks already.

If you're building a dashboard, a social network, an ecommerce application, or a complex interactive frontend, JPROT is probably not what you need.

And that is okay.

JPROT isn't trying to replace everything.

It is designed around a narrower philosophy:

If your website is primarily content, don't make the content pay the complexity tax of an application framework.

You should be able to understand your project.

You should be able to open the content directory and immediately know where the pages are.

You should be able to change the design without rebuilding the entire architecture.

You should be able to extend the system without becoming dependent on its internals.

And you should be able to publish the result as static HTML when you want to.

I built my own website with it

There is one test I care about more than a feature list:

Can I actually use the thing I built?

My own portfolio is built with JPROT.

That matters to me because JPROT isn't only an experiment sitting in a repository.

It is being used to build a real website.

And the project has grown through that experience.

Every limitation becomes visible when you use your own tool.

Every awkward workflow becomes impossible to ignore.

That is how JPROT has gradually moved from a small portfolio generator toward a broader content-driven website system.

Where JPROT is going

JPROT is still young.

The current release is 0.8.1.

That number is intentional.

There is still room to change the architecture.

There are still APIs to refine.

There are still ideas to test.

But the direction is becoming clear.

I don't want JPROT to be another framework that wins by accumulating features.

I want it to remain understandable.

A system where:

Markdown
   ↓
Content Graph
   ↓
Components
   ↓
Routes
   ↓
SSR / SPA navigation
   ↓
Static export

is enough to build serious content-driven websites.

Simple on the surface.

Extensible underneath.

Try it

Install it globally:

npm install -g jprot

or run it directly:

npx jprot

Create a project:

npm create jprot@latest my-site
cd my-site
npm start

Then open:

http://127.0.0.1:4114

Add a Markdown file.

Change the CSS.

Replace a component.

Add a plugin.

Run the linter.

Export the site.

And see what happens when a website doesn't begin with a build pipeline.

It begins with a file.

JPROT

Write Markdown. Customize everything. No build step.

GitHub: https://github.com/Moaaz-i/JPROT

Documentation: https://moaaz-i.github.io/JPROT/

Example: https://moaaz-i.vercel.app/

The project is MIT licensed and built for Node.js 18+.

Before You Push: Building a Local Twin for GitHub Actions

Moaaz Yahia — Wed, 30 Sep 2026 02:14:05 +0000

Before You Push: Building a Local Twin for GitHub Actions

There is a particular kind of frustration every developer eventually learns.

You write the workflow.

You read it twice.

You check the indentation.

You push.

And then GitHub tells you that something was wrong all along.

Maybe an environment variable was missing.
Maybe an action was pinned incorrectly.
Maybe two jobs were never connected the way you thought they were.
Maybe a command worked perfectly on your machine and failed somewhere else.

And suddenly, the feedback loop becomes:

write
  ↓
push
  ↓
wait
  ↓
fail
  ↓
read logs
  ↓
change something
  ↓
push again

I wanted a different loop.

Not a fake GitHub Actions emulator that simply says everything is fine.

Something more honest.

Something that could take the workflow I had actually written, run the commands it could genuinely reproduce, isolate the jobs like separate runners, and tell me clearly when something could not be reproduced locally.

That idea became AeroCI.

A local twin for GitHub Actions

AeroCI is designed as a local twin for GitHub Actions.

The important word here is not local.

It is twin.

AeroCI attempts to reproduce the parts of a workflow that can actually be reproduced on your machine. It executes real commands in a real shell and provides the relevant GITHUB_* environment rather than pretending to simulate a successful run.

And when it cannot reproduce something?

It says so.

Not "success".

Not "probably fine".

Not a green checkmark hiding an assumption.

It says:

not simulated

That distinction is the foundation of AeroCI.

The first command is intentionally simple

You can start with:

npm install -g aeroci

cd your-project

aeroci init
aeroci check
aeroci run

init creates the local configuration and a sample workflow.

check validates the workflows against what the local runner actually requires.

And run executes them inside isolated job environments.

Interestingly, the configuration file is optional. AeroCI can run a project without .aeroci.json, using defaults where possible.

That was an important design choice.

A tool for developers should not create a new ceremony before it starts solving the problem.

The workflow should be treated as code

A workflow file may look like configuration, but it behaves much more like a program.

It has:

dependencies
execution order
environments
inputs
outputs
matrices
shells
external actions
secrets
network requirements

So AeroCI does more than execute it.

It can inspect it.

The check command validates things such as workflow structure, action pinning, secrets versus .env, the job graph, matrices, and shell availability.

Then analyze goes further.

It can identify dead steps, duplicated steps, unused outputs, the structure of the job graph, its longest chain, and a complexity score.

The goal is not merely:

"Did my workflow finish?"

It is also:

"What exactly did I build?"

That is a much more interesting question.

Isolation matters

One of the easiest ways for a local CI tool to become misleading is to let every job share the same project directory.

A job writes a file.

The next job sees it.

The test passes.

But that is not necessarily what would happen on separate CI runners.

AeroCI therefore gives every job its own copy of the project.

A matrix combination gets its own environment as well.

Your working tree remains untouched.

That small architectural decision changes the meaning of a local run.

You are no longer merely executing commands from a YAML file.

You are testing assumptions about isolation.

Secrets should not accidentally become files

There is another problem with reproducing CI locally:

secrets.

It would be convenient to simply copy .env into every sandbox.

It would also be a terrible default.

AeroCI deliberately leaves .env out of the working tree. Secrets are exposed to steps through the secrets context instead of being copied into the sandbox where an unrelated command could read them.

There is an opt-in exception for users who explicitly want excluded paths such as node_modules linked to their real directories.

And even there, the trade-off is made explicit:

if a step writes into those linked directories, it is writing into the real files.

The tool does not pretend otherwise.

The network is a separate decision

This was one of the principles I wanted AeroCI to make impossible to misunderstand:

AeroCI never uses the network without explicit permission.

But "network access" is not necessarily one decision.

There can be a difference between:

Downloading a runtime

and:

Allowing the workflow itself to open sockets

AeroCI therefore records these as separate policies.

Runtime downloads can require consent.

Workflow network access is denied by default.

The two permissions are intentionally independent.

And when the platform provides a mechanism to enforce the restriction, AeroCI actually enforces it rather than merely promising not to use the network.

On macOS it can use sandbox-exec.

On Linux it can use unshare --net.

So a command such as:

curl example.com

does not simply receive a polite warning.

It gets no network response.

At the same time, local communication such as a localhost server can continue to work.

That distinction matters.

A red result can be more useful than a green one

One of the easiest mistakes in CI tooling is to make unsupported things appear successful.

AeroCI takes the opposite approach.

Some GitHub Actions cannot honestly be reproduced locally.

Deployments.

Publishing.

Container builds.

CodeQL.

AWS OIDC role assumption.

Reusable workflow calls.

And actions for which there is no local implementation.

Instead of manufacturing confidence, AeroCI reports these as:

not simulated

The command may still be inspected or executed where possible, but the result explicitly tells you what was not verified.

That creates a useful rule:

A green local run should mean exactly what AeroCI was capable of verifying — and nothing more.

I think that is a healthier philosophy for developer tooling in general.

Debug the failure where it happened

Sometimes logs are not enough.

You know the step failed.

You know roughly where.

But you need to touch the environment yourself.

That is what:

aeroci debug

is for.

It opens a shell inside a copy of the project with the same CI environment, allowing you to rerun the failing command manually.

Instead of:

CI failed
   ↓
read log
   ↓
guess

you can move toward:

CI failed
   ↓
enter environment
   ↓
run command
   ↓
observe
   ↓
fix

That is a much shorter feedback loop.

CI should have a memory

A single workflow run tells you what happened.

A history can tell you what is changing.

AeroCI includes profiling and reporting tools for that reason.

profile keeps run history and trends against previous runs.

report can re-render a previous run, compare workflows, or show commits that touched them.

versions makes action pinning and simulation status visible.

There is also a read-only UI:

aeroci ui

Sometimes seeing a workflow as a graph is more useful than reading another hundred lines of YAML.

It is not GitHub Actions

And that distinction is important.

AeroCI does not attempt to replace GitHub Actions.

It does something narrower:

it gives your workflow a local place to be examined before you push it into a remote runner.

The remote system remains the final authority for things that inherently depend on the remote environment.

AeroCI's job is to reduce the number of things that have to be discovered there for the first time.

That is the difference between simulation and verification.

Why build this?

Because the distance between writing code and discovering that it is wrong should be as small as possible.

We have spent years shortening the feedback loop for application code.

Hot reload.

Local servers.

Unit tests.

Type checking.

Linters.

Formatters.

But CI configuration often remained strangely dependent on:

commit
→ push
→ wait

AeroCI is an attempt to bring another piece of that feedback loop home.

Not by pretending the remote environment does not exist.

By giving developers a local approximation that is explicit about its boundaries.

It can execute what it can execute.

It can inspect what it can inspect.

It can isolate what it can isolate.

And when it cannot reproduce something, it tells you.

That last part may be the most important feature of all.

The philosophy behind AeroCI

Developer tools are often judged by how much they can automate.

I think there is another question worth asking:

How honestly do they communicate what they automated?

A tool that says "passed" when it merely skipped the difficult part is convenient.

It is also dangerous.

A tool that says:

not simulated

is less magical.

But it is more trustworthy.

That is the direction I wanted AeroCI to take.

Not a fake GitHub Actions runner.

Not a promise that your laptop is GitHub.

A local twin with boundaries.

And perhaps that is the real purpose of developer tooling:

not to make reality disappear,

but to bring the useful parts of it closer.

flash-zk: a server-blind encrypted database for private AI

Moaaz Yahia — Fri, 28 Aug 2026 13:50:13 +0000

Most AI databases can read you.

This one is designed not to.

Sealed envelopes. Blind indexes. The key never lives on the server. RAG and agent memory sit on that — not on a vendor that holds plaintext at query time.

We did not ship new crypto in 1.3.1. We shipped the rule, in the open:

Default is strong. You can weaken it. It holds if you keep the key.

What gets refused next is already written. No surprise cut. No ops backdoor. No “encryption later.”

The rest is in the repo. Don’t take our word — run it.

npm install flash-zk
npx flashsh wrap-key

import { FlashClient } from "flash-zk";
const client = new FlashClient({ storagePath: "./flash_data" });

Then read the three pages. In that order.

flash-zk@1.3.1 — same engine as 1.3.0. The difference is what we will no longer let you turn off.