A← Index

Why this portfolio uses plain HTML

Why I chose static HTML for this portfolio, and where I would use a framework.

Tags
Architecture Performance Opinion

IThe Setup

I build applications with React and value its component model. This portfolio has a different job: present my work, experience, and writing.

I started the portfolio as static HTML because its main content did not need a client-side application runtime.

The site serves HTML files, stylesheets, fonts, images, and a small script. It has no application build step or JavaScript framework dependency.

That choice suits this site’s content and maintenance needs.

IIHow We Got Here

A familiar framework is a reasonable starting point, but I find it useful to review the requirements before adding it to a small content site.

For a portfolio, the important questions are how readers reach the content, how easily I can update it, and what the browser must load to show it.

The cost nobody talks about

In a client-rendered application, initial content may depend on downloading and running JavaScript. That cost matters when the device or connection is slow. Server-rendered applications can make different tradeoffs.

With static HTML, the browser can parse the document and render its content as it arrives. This portfolio does not need a framework hydration step.

The upgrade treadmill

A framework also adds dependencies and tooling to maintain. That work can be justified by the application’s needs, but I did not need it for this portfolio.

Keeping the site static reduces the tools I need to update. It does not remove the need to check links, accessibility, security, and browser behavior.

Problems you didn't have before

Interactive applications need decisions about navigation, state, data loading, and rendering. A mostly static content site can often avoid some of that application code.

For this portfolio, I chose to keep those responsibilities small.

IIIThis Site

The page content is present in the HTML source. A visitor does not need the theme or drawing controls to run before reading an article.

0
Dependencies
0
Build steps
Shared
Styles & controls

The current design uses a shared stylesheet at /assets/letter.css and a shared script at /assets/letter.js. Fonts are self-hosted. The script handles theme preferences, drawing guides, the date, and navigation to collapsed sections.

I can change these files directly without a framework compiler or bundler.

Each page has its own title, metadata, and content in the document. Search visibility still depends on the quality and configuration of that content.

The deployment configuration specifies an empty build command and the repository root as the output directory. It also includes redirects and asset-cache headers. The core settings are:

{
  "buildCommand": "",
  "outputDirectory": ".",
  "headers": [{
    "source": "/assets/(.*)",
    "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
  }]
}

Vercel serves the files directly. The asset headers specify a one-year immutable cache, so changed assets need versioned URLs or another cache-invalidation strategy.

Using standard browser formats keeps the site independent of a framework upgrade cycle. I still need to test it when I change the content or design.

IVWhat I Gave Up

The stylesheet and control script are shared, but the page shell is repeated in individual HTML files. A change to the header or footer can therefore require edits across several pages.

The repeated shell is manageable at the current size. Templates or a static-site generator could reduce that editing work as the collection grows.

There is no CMS, comment system, or site search. I add articles as HTML files. That keeps publishing direct, but leaves more editorial and consistency checks to me.

VWhen You Actually Need a Framework

For products with complex forms, collaborative features, or many shared interface components, I use application frameworks. Their abstractions can support work that this portfolio does not need.

State shared across views, frequent data updates, and optimistic interactions are reasons to consider a framework. Team conventions and existing infrastructure also affect the choice.

I want the choice to follow the product requirements and maintenance constraints.

VIOne Question

Before starting a project, I ask what the browser needs to do beyond displaying the content.

An editor or dashboard may need substantial application state. A blog may mainly need a reliable publishing workflow. Those requirements call for different approaches.

Static HTML, a static-site generator, server rendering, and a client application are all options. I compare them against the content, interactions, and team that will maintain the site.

For this portfolio, a small static site remains a useful fit.

SignedArjun