DEV Community: Home Officer

Building PicoSSG: 'Just Enough Code'

Home Officer — Fri, 16 May 2025 16:50:47 +0000

This is the story of how PicoSSG came to be - from its humble beginnings as a minimal static site generator to its current form.
It's a journey about finding the sweet spot between features and simplicity, about writing "just enough code" to get the job done without unnecessary complexity.

The Genesis of PicoSSG

The static site generator (SSG) landscape is crowded with feature-rich but increasingly complex solutions.
As I looked at and used tools like lume, 11ty, lektor, or jekyll,
I found myself drowning in configuration options, plugins, and middleware.
What started as a simple desire to convert Markdown content into HTML had evolved into learning complex frameworks with steep learning curves.

I wanted something radically simple – a tool that would do just what I see an SSG needs to do: markdown, templating, and simple data handling.
The vision was clear: process templates and markdown files predictably, with minimal dependencies and a non-magic transformation process.

On a spring day in April 2025, the very first lines of code emerged with a
commit message that says it all: "The simplest processor, I think." This established the minimalist approach that would guide the entire project.
Just a few lines of code to process nunjucks templates and nothing more.

The second commit was a simple test
to ensure the processor worked as expected, I just have this testing in my blood.
I mean how can one write software that grows and becomes bigger than what one can hold in their head without testing?

Even the testing must be simple, so I just compared the output with the expected output using the diff command, and that's how
PicoSSG still works.

The Minimal and Maximum Feature Set

From day one, I defined a clear boundary around what PicoSSG would and wouldn't do. The minimal feature set was non-negotiable:

Markdown processing - For content-focused writing without HTML clutter
Nunjucks templating - For layout flexibility and component reuse (introduced in the project's first week)
1:1 file mapping - Direct correspondence between source and output files, preserving structure without hidden transformations
Simple JS configuration - A single entry point for extending functionality through JavaScript

Just as important were the deliberate limitations - features PicoSSG would never implement:

Do the job without configuration and plugins
No hidden magic or implicit transformations
No dependencies beyond absolute necessities

The power of PicoSSG would come not from feature abundance but from its extensibility through a simple JavaScript interface.
Need to process data? Write a function preprocess() or postprocess() in _config.js, there is no more.
Need custom template filters, extend nunjucks (not picossg!)? Create them in _njk-custom/filters.js.
This approach maximizes flexibility if needed while keeping the code small.

v1 – The Minimal Viable Product

A critical early feature was component inclusion. Rather than creating a complex component system,
PicoSSG adopted a simple convention: files starting with underscore (_) would be excluded from output but available for inclusion.
This elegant approach allowed for reusable components without special handling.

Testing was also simple but effective - a straightforward comparison between generated output and expected results.
By the end of the first day, a basic test setup was in place that would evolve but remain fundamentally simple.

Within 24 hours of the project's birth, PicoSSG had a README
and was taking shape as a usable tool, albeit with limited features.

Evolving the Foundation: v2

About a week into development, a breakthrough came with the message "Now the front-matter block parsing is completely dynamic".
This allowed metadata to be associated with content without complex infrastructure.
The decision process is documented in ADR-001,
which compares different approaches and ultimately selects front-matter for its compatibility with other tools and clean syntax.

The extension processing pipeline also matured during this period. The next morning brought a key insight
that established the right-to-left processing of extensions, allowing combined file types like .html.md.njk to be processed in sequence.
Processing simply stops when there is no more "known" extension to process. Theoretically, one could also build a file such
as index.html.md.njk.md.md.md.njk. Not sure that makes sense though :).

After a weekend of experimentation, custom filters became possible,
and by the following evening, the project added two default filters: md and mdinline
for Markdown processing within templates.

Architectural Decisions That Shaped PicoSSG

Several key architectural decisions shaped PicoSSG's development, many documented as Architecture Decision Records (ADRs):

ADR-001 explored different approaches to handling mixed Markdown and Nunjucks content, ultimately selecting front-matter as the simplest approach that maintained compatibility with other tools.
ADR-002 made the important design decision to allow user processors to modify the files map directly, optimizing for performance and memory efficiency at the cost of potential side effects.
ADR-003 documented the choice of markdown-it over alternatives like marked, based on careful evaluation of edge cases and built-in features like URL linking.

The decision to avoid framework dependencies and stick to a minimal set of npm packages was not formally documented but is evident throughout the codebase. This approach kept the tool lightweight and reduced potential points of failure from external dependencies.

v3 – Maturing the Codebase

Version 3.0 represented a significant maturation of PicoSSG while remaining true to its minimalist principles. In mid-May,
preparations for this release were underway.

A major improvement came in the metadata handling. Two weeks after the project began, a subtle but important change
restructured how data was passed to templates, making it more convenient while maintaining access to the original structure. Later that same day,
another refinement further simplified template data access.

As the project approached its third week, the pre/post processing capability was significantly enhanced,
allowing user-defined functions to transform content before and after the main processing pipeline. This expanded what users could do without adding complexity to the core.

Just days before the v3 release, performance improvements appeared with a change that parallelized file writes
for better efficiency: "Make the writing of the files as parallel as it can be :)."
Maybe it was just me proving I know Promises a bit :). But I have to say adding await in front of every async operation
does not feel right most of the time, even though there is a lot of room for improvement also in this project.

With clarity that comes from real-world usage, the directory structure was
reorganized to make the project more intuitive for newcomers.

The Philosophy in Action

Throughout PicoSSG's development, the philosophy of "less code, not smarter code" remains evident. At one point, a commit message proudly declared: "I gladly removed (more) code." This reflects the core belief that the best code is often code you don't have to write or maintain.

The 1:1 file mapping isn't just an implementation detail but a fundamental design principle that creates predictability. Users can look at their source directory and immediately understand what the output will be, without hidden transformations or magic.

The project embraces convention over configuration without hiding complexity. Rather than extensive configuration options, PicoSSG uses simple conventions (like files starting with underscore being excluded) that are easy to remember and reason about.

This minimalist approach leads to more maintainable and understandable code. The entire build process in build.js is under 300 lines, making it possible for users to read and comprehend the entire codebase if needed - something impossible with larger SSG frameworks.

Looking Forward

The roadmap for PicoSSG's future is outlined in the CHANGELOG.md, with plans for continued refinement rather than feature explosion. Ideas like adding size information and processing times represent the kind of thoughtful additions that add value without complexity.

The most important challenge going forward will be maintaining the balance between adding useful capabilities and preserving the simplicity that makes PicoSSG special. Each potential feature must be evaluated against the core philosophy: does it add enough value to justify the additional code and complexity?

Examples like JSCraftCamp.org's 2025 site and picostitch.com demonstrate that PicoSSG is already capable of building real-world sites with its minimal feature set. This validates the core premise - that for many static sites, "just enough code" is indeed enough.

In a world where software tends toward bloat and complexity, PicoSSG stands as a reminder that sometimes, less is truly more.

You see more code that can be removed? Let me know, please.

How to Control Strict Mode

Home Officer — Sun, 05 Nov 2023 20:09:00 +0000

I was surprised to see that the worker threads run in non-strict mode by default. This should rarely happen, because when using ES modules (ESMs), classes or "use strict" then the engine forces strict mode. I didn't know this in the beginning. I have been working on the katas I use for this site in the javascript-katas repo which uses ESMs and type=module, my default. This makes the entire nodejs project, any npm ... command run use strict mode. Escaping from strict mode is not easily possible, but one way to run code in non-strict mode is by using a worker thread.

I always like to understand where things originate, so let's read about strict mode.

Strict Mode – When and Why?

Strict mode was introduced in ES5 (in 2009).
In the specification it says strict mode was added

in the interests of security, to avoid what [...] consider to be error-prone features, to get enhanced error checking

and

The strict variant also specifies additional error conditions that must be reported by throwing error exceptions

So strict mode was introduced for making JS safer.

Strict Mode?

Actually the worker I used was just a mean to solve my actual problem, which was running tests for the arguments kata. In order to do that I needed to run the tests in non-strict mode, so let's have a look at the strict mode.

Where does the strict mode play a role now? I had been diving deep into the "function API", digging in the very first ES1 spec and all versions beyond to find out when was what introduced or deprecated (deprecation happens rarely in JavaScript). So I came across arguments and when I wrote the following test:

const fn = function() {
  const arguments = 'arg';
  return arguments;
}
assert.equal(fn('the argument'), 'arg');

It failed with "Uncaught SyntaxError: Unexpected eval or arguments in strict mode", which was not due to the test code itself, but the rest of the code I ran in the worker thread. The above test only got injected and makes only a small part
of the entire code run in the worker. The code has an import in it, which turned all the code to be run in strict mode.
And as the error says arguments is not allowed in strict mode.

So I want to control when to turn on strict mode. But for that let's understand strict mode a bit better first.

What forces Strict Mode?

As mentioned above "use strict" turns on strict mode, but in this case there was none in the worker code yet, so what turned it on? In the ES6 spec chapter "Strict Mode Code"
the following lines were newly added which force strict mode to turn on:

Module code is always strict mode code.

All parts of a ClassDeclaration or a ClassExpression are strict mode code.

So the import turned it on.

How to Control Strict Mode?

So I rewrote the code to not use import and it ran in non-strict mode.

Now I can control strict mode, I just have to add "use strict" at the top of the code. Even better, I can put "use strict" at the beginning of a function body, and it makes
only this function run in strict mode. It must be the first statement in this function, see the code below for some exploration. Oooh, I see new katas arising.

'use strict'
const fn = function() {
  const arguments = 'arg';
}

The above fails with the error message we know from above "Unexpected eval or arguments in strict mode".

const fn = function() {
  'use strict'     // "use strict" inside the function, test still fails.
  const arguments = 'arg';
}

The above fails too, for the same reason. Here only the function is run in strict mode, but that's also where arguments is used, so it fails.

const fn = function() {
  const arguments = 'arg';
}
'use strict'     // "use strict" NOT at the beginning of a function it gets ignored, test passes!

Passes.

const fn = function() {
  if (true) {
    'use strict'     // "use strict" at the start of a scope, but NOT at the beginning of a function it gets ignored, test passes!
    const arguments = 'arg';
  }
}

And this one passes too, because the "use strict" strings are not at the beginning of a function. I was irritated in the beginning, because I expected it to be at the beginning of a scope, so after the {, but I was wrong. The spec also states this explicitly:

if the function code begins with a Directive Prologue that contains a Use Strict Directive.

in human words, this means the function must start with a "use strict" string. The scope is not mentioned there. The spec defines three more cases in very hard to read words. These are 1) the global code, 2) eval code and 3) Function code, when either starts with a "use strict" string, then the entire code is run in strict mode.

With this I did not only learn what strict mode restricts, but also how to control it. And all the magic is gone.

💡 To turn on strict mode, you can use "use strict" in the four described ways, classes or modules.
That's how strict mode can be (manually) turned on or forced to be on.

JSKatas 🥋 Continuously Learn JavaScript. Your Way.

Home Officer — Mon, 28 Aug 2023 11:40:59 +0000

This article explains what jskatas.org is. In short it is: "Continuously Learn JavaScript. Your Way."

No matter if you are beginner or an expert, a slow or fast learner.
The site jskatas.org aims to allow anyone to discover and learn unknown or new parts of JavaScript. You can also consolidate your JavaScript knowledge or extend your skills and sharpen them.

Learning with jskatas requires you to actively work with and on the language. There is no lean-back content to "just consume" and hope to have acquired knowledge, this is NOT what jskatas offers, and also does not want to offer.

Content

Learn (With Tests)
Re-Learn
(All of) JavaScript
At Your Level and At Your Speed

Learn (With Tests)

JSKatas strives to allow you to learn the language JavaScript profoundly and complete. The approach to learn is oriented around tests.

The katas are structured closely with how the language evolves.
Categories like "ECMAScript 6 (ES2015)" which had been introduced
provide a versioning scheme for the language. JSKatas structures its learnings using those categories and will allow you to track and learn all parts of JavaScript.

The learning itself can be called test-driven, because all one does is working with tests all the time. Tests are an essential part of programming. How can you continuously prove that code works if there are not coherent and expressive tests that can verify the functioning at any time? Why not apply this approach for learning a programming language? That was the thought when jskatas was created.

A test is made up of a good test description explicitly describing what the test is proving or trying to prove. Each test description you find on jskatas strives to be explaining what the code (the test) is teaching. Each test on jskatas represents a tiny bit of knowledge. For example: 'isInteger' is a static function on 'Number'. This piece of info is knowledge you can take away as soon as you read the test description. To make this knowledge really stick the according test is failing and the learner is supposed to solve it. Sometimes solving is a number of tries and thought processes, or call them learnings. Once learned by having read and proven by making the initially failing test pass, the knowledge might stick easier and once needed will be easy to recall and apply.

Re-Learn

Re-learn is the part that I am most excited about and that I find most useful about jskatas and, I believe that this part is far underevaluated by many. Actually I am not really happy with the term "re-learn", I am not sure if it captures the intent best. Let's explore what it means.

I use jskatas to re-learn parts of JavaScript that I either did not use for a long time, that I never used, that I forgot or parts where I am not sure how they really work. Often I had come back to do the Map-katas because I used Map sporadically. Another one that I often get wrong, even after many years of JavaScript is the Array method sort(). So I wrote the ES1 kata for sort(). I came back to it at least twice already again to re-learn how sort() works. The last time was just last week. The sort() function is in JavaScript since ES1, for a long time already, but it's not that intuitive that I get it right all the time. It might just be me.

JSKatas allows you to jump in whereever you want and either re-learn a part of JavaScript or harden your existing knowledge. There is no entry or exit point on jskatas, any point can be a starting and ending point for learning. There are no fixed lessons or plans you have to follow when learning. There are only pieces of knowledge that can be arranged and re-arranged any time depending on the current interest. That's why jskatas is also ideal for re-learning and hardening ones JavaScript knowledge.

In the future test plans and guides might be provided, to give guidance on how to learn, what to learn next, where to start and/or where to continue. But this is still some time out. Even given these guides would exist, learning can still start, continue and end anywhere with any kata. Such a guide is easy to arrange depending on the desired learning goal. And yet it can make use of the entire pool of katas.

(All of) JavaScript

As mentioned before JavaScript is very well structured, versioned and named, in it's own way though. "ECMAScript 1 (ES1)", "ES5", "ES6" or "ES2015", the names make the evolution of JavaScript easy to understand and allow jskatas to easily structure all the knowledge.

Due to this crystal clear and simple structure of the JavaScript knowledge it is also very easy to measure how much of JavaScript one can learn using jskatas, and also how much jskatas provides to be learned. Currently I would claim that 80% of ES6 can be learned using jskatas. But how much of all JavaScript, that is left to be made measurable correctly. This is not done yet.

That's why the "All of" in the headline of this paragraph is set in parantheses. JSKatas does not allow to learn all of JavaScript yet.
But measuring it is not that difficult using the approach of providing the knowledge as jskatas does it.

At Your Level and At Your Speed

The level of knowledge and the speed of learning is so very different among people, that everyone has their own way of learning. One person knows all about arrays, but not all about string, the next one knows half of each. Offering these people the same learning materials is not efficient.

On jskatas you determine the speed at which you solve the katas that provide the knowledge. Let's see an example. The Array API katas for ES6 at some point consisted of eight katas.

The Array.from() kata consists of five tests, or five pieces of knowledge. You can always decide how much of the kata you do, if you use it for re-learning or if you want to learn all the kata provides for this topic.

Every tiny test is a progress. One test can take as little as five seconds to solve. So even re-learning might not be a huge time invest. And you can stop learning even within a kata whenever you like.

So the depth and intensity is up to you, your discipline, interest, drive and endurance. JSKatas allows you to learn at your level and your speed.

Conclusion

Are you up for trying a different approach to learning JavaScript? One where you have to be actively learning, where you are steering your progress and you determine the speed? Try solving some tests jskatas and learn or learn again what you do or didn't know yet.

Continuously Learn JavaScript. Your Way.

Discover and extract dependencies

Home Officer — Tue, 20 Mar 2018 00:03:11 +0000

While refactoring some badly tested code, a pattern of how I extract dependencies emerged. The actual intention was to improve the testability. In this case dependency injection is the tool that helped me. Read here to find out the steps I found to separate the dependencies.

The pattern that emerged (the quick version)

From this article you may learn that those steps are all that is necessary in order to get a better feeling on the dependencies of your code, how to separate them and make the code easy to test.

The steps are:

Write a first test
Find and use first dependency in test
Isolate dependencies
Provide production/default dependencies

And you end up with

fast and small tests
separated dependencies
maybe hints for how to modularize your code

The task

loadStudent function flow

I want to show how to separate dependencies that might not been obvious at first. And by adding tests I will "feel" them. And I will be pushed to separate them out. Which makes my code easier to test and also make me understand what (external) dependencies the code has.

I broke down the original code, to really make the actual dependencies stick out. The code loads some data, a student in this case. To speed up performance the student is first read from a cache, if that fails it is loaded from a (slower) backend.

Let's get started.

This code was missing tests. So I will start to add them. The starting point was the following code.

import { fetch } from './backend';

const cache = {};
const loadStudent = ({ studentId }) => {
  if (!cache[studentId]) {
    cache[studentId] = fetch({ studentId });
  }
  return cache[studentId];
};

First test

The first test I wrote was for the cache (see the commit). Actually I am not sure it's the right test to write, since the fetch is more important. But anyways. I follow the code's flow.

describe('Load a student', () => {
  it('from the cache', () => {
    cache[42] = 'student 42';
    const student = loadStudent({ studentId: 42 });
    assertThat(student, equalTo('student 42'));
  });
});

The first thing that jumps out is the sharing of the global cache variable. The production code and the test share it now through the access of a global variable. Scary. This is not good. In this case I want to have the cache under control, so I need to inject it. That is my first conclusion and the first dependency I found. NOTE: first dependency cache.

Isolate first dependency

I rewrite the test (and make it fail), I pass the cache into the function as a parameter (see the commit). I isolate the first dependency. At least for the test it is isolated now.

it('from the cache', () => {
  const cache = { 42: 'student 42' }; // <<< no more globals :)
  const student = loadStudent({ studentId: 42, cache });
  assertThat(student, equalTo('student 42'));
});

To make this test green I need to change the production code. I need to
use the cache as given via parameter.

I am going to change the production code, the function loadStudent() without having it fully covered with tests. The fetch() method is not tested yet at all. True. I am fine with that for now.

const loadStudent = ({ studentId, cache }) => {
  if (!cache[studentId]) {
    cache[studentId] = fetch({ studentId });
  }
  return cache[studentId];
};

No more global cache variable. Great for testability. But actually the real cache functionality got lost. Since there is no global cache anymore. Right. That is a real issue. I will cover this in a second. Hold on! Let's clean up a bit first.

Separating dependencies

First I would like to refactor the code a little bit. The parameters are nice and the destructuring makes it nice to have named parameters. But I think that studentId and cache are two different kind of parameters. The studentId is the actual parameter that this function requires in order to do something useful. And the cache is an injected dependency. I want to make that clear in the function. So I split them (the commit).

const loadStudent = ({ studentId }, { cache }) => {
  // ...
};

And since I am a fan of explicitness I prefer to not destructure the second parameter, but to name the entire thing, like so (commit):

const loadStudent = ({ studentId }, dependencies) => {
  // ...
};

This will bubble through the code and inside the function cache will need to be replaced by dependencies.cache. Which is more to write but every reader of the code will benefit from it. It will be clear that the cache is a dependency and is not a main concern of this function. And how the cache works is nothing of importance in here. I personally like that and think it adds value to the code for any future reader.

Discover second dependency, the `fetch()` function

Let's tackle one of the open issues, which is testing the fetch() function. It is a global function, currently. So we are treating it as a nasty global function for now, and just overriding it in the following test (commit).

it('fetch the student if not in the cache', () => {
  let emptyCache = {};
  fetch = () => 'student 23';
  const student = loadStudent({ studentId: 23 }, { cache: emptyCache });
  assertThat(student, equalTo('student 23'));
});

We know now that fetch() is used inside of loadStudent(). And that knowledge is not in our test, that is nasty too. We need to make that obvious.

Inject the second dependency

We make this obvious by (just say it with me), yes, correct: injecting the dependency (commit).

it('fetch the student if not in the cache', () => {
  const emptyCache = {};
  const dependencies = { cache: emptyCache, fetch: () => 'student 23' };
  const student = loadStudent({ studentId: 23 }, dependencies);
  assertThat(student, equalTo('student 23'));
});

See fetch() is passed in the dependencies object. And no global is overridden anymore.

Provide production dependencies

Now we have all the dependencies identified. We have cache and fetch() (even though fetch is a pretty bad name). Those two dependencies can be injected, the function works using them. Now we should not just have the tests run, but also the production setup. And for that we need to provide the dependencies to it too.

How? Let's try an integrated test for it, one that takes a working cache and a working fetch() function as given (commit).

describe('Load a student', () => {
  it('from the cache', () => {
    const student = loadStudent({ studentId: 42 });
    assertThat(student, equalTo(''));
  });
});

As you can see, this test assumes 1) there is no student with the ID 42 and 2) a fetch for this student returns an empty string. Yep, we are assuming to have these external dependencies under control that we know those things.

Deploying this and having it run in a real CI environment there might be a bit more setup to make in order to get those integrated tests provided with the right data. And it might also be a bit more work to get them stable. That's why one should very well figure out what the right set of (mostly happy path) tests is. And if you throw many of them at your code, do also think that they must stay maintainable! This one here serves as an example for understanding that a safe software might not only consist of tiny and small tests (I am preventing the polluted name "unit tests").

To get this test green, we set up the default dependencies that our production environment will use. There is many other ways of injecting dependencies. The following worked quite well for me until now (commit). Though remember to try to keep the dependencies to be injected as tiny as possible and it will serve you well.

const defaultDependencies = () => {
  return { fetch, cache };
};

const loadStudent = ({ studentId }, dependencies = defaultDependencies()) => {
  // ...
};

As you see above, I define the defaultDependencies above the function. Mostly those consist only of some imported items. One could go further and move this out and just inject a structure into this file. I saw it working well until now with this less generic, more explicit approach and allowing the reader (of the code) to see what the dependencies consist of, right where they are used.

Why a function defaultDependencies() and not just a simple object? Simple answer, a function makes it lazy. Until the dependencies are not needed they don't get resolved, this might dribble down the call stack. And it also allows for configuring a dependency, if necessary.

What's left?

The variable cache is a very simple, very stupid cache now. Which is quite cool. But thinking about a cache, there might be more to it. I might want to create a simple API for the reading from and writing to the cache.

The fetch() as such is a very generic name. But it could be named better, something like readFromBackend() or loadStudentFromStorage(). That there might just be the simple fetch() function behind it, is secondary.

Maybe making it asynchronous would be a nice add-on. It would be very easy, but unfortunately this involves also changes in the test code. But that is the nature of JavaScript, it can not simply hide asynchronicity in code.

Conclusions

Separating dependencies can be done by writing tests for untested code. It looks like it blows up the code? Think again! It also decouples your code in the places where you might not want it coupled. Decoupling is just like every person using a different glass when drinking from the same bottle, in order to not share all germs. It's pure hygiene.