A practical debugging story about push-to-talk speech-to-text, AI CLI, Cinnamon, X11, Whisper, dotool, ydotool, and the shortcuts I should have avoided.

The Goal

I wanted a very simple thing: hold one key, speak a prompt, release the key, and have the text appear inside the terminal where I run AI CLI. Not a voice assistant.

Not a meeting transcription tool.

Not a cloud dictation product.

Just push-to-talk for AI prompts.

The final result worked. But getting there involved a surprisingly long chain of Linux desktop details: X11 versus Wayland, clipboard backends, old ydotool syntax, a Voxtype upgrade, GPU acceleration getting disabled, systemd user services, and finally the boring truth that microphone quality matters.

The Hardware Shortcut

In my case the hotkey is F16.

On my keyboard, that is not labeled “F16”. It is the key with the “X” symbol in a group of four keys that look a bit like PlayStation-style symbols.

This is actually a good setup. Extra keyboard keys often emit F13 to F24, which are useful because they rarely conflict with editors, terminals, browsers, or desktop shortcuts.

Finding Out I Had Already Started

Before installing anything new, I searched my existing home directory for dictation-related tools and configuration. That turned out to be the right move.

I already had a Voxtype configuration:

~/.config/voxtype/config.toml

The important pieces were already there:

[hotkey]
key = "F16"
mode = "push_to_talk"

[whisper]
model = "base"
language = "it"

[output]
mode = "type"

So the problem was not starting from zero. The problem was making the setup reliable enough to use all day.

The First Temptation: Paste Mode

At first, I did not want Voxtype to type character by character. I wanted it to copy the transcription to the clipboard and paste it into the terminal in one shot.

This is because those AI CLI tool works better when you paste stuffs.

The attractive configuration was:

[output]
mode = "paste"

It looked cleaner. It sounded more robust. On Linux Mint Cinnamon, which is an X11 desktop, it turned into a long debugging session.

Why Paste Was Harder Than Expected

The generic error was not very helpful:

Output failed: All output methods failed.
Ensure wtype, dotool, ydotool, wl-copy, or xclip is available.

After running Voxtype with verbose logging, the real issue became clearer. On my system:

• wtype is useful on Wayland, not on my X11 session.
• wl-copy is also Wayland-oriented.
• xclip works for the X11 clipboard.
• dotool can type text successfully.
• ydotool exists, but the distro package did not match the syntax Voxtype wanted to use.

One failed workaround was using mode = "clipboard" plus an external paste command. It did trigger paste, but it pasted the previous clipboard content instead of the fresh transcription.

If your workaround pastes the previous clipboard value, it is not a solution. It is a race condition.

Upgrading Voxtype

I was running Voxtype 0.6.2. A related X11 clipboard issue had already been closed upstream, so upgrading was the next reasonable step.

Since Voxtype was installed from a local .deb, a normal apt upgrade was not enough. I installed the newer package manually:

cd ~/tmp

curl -A 'Mozilla/5.0' -L \
  -o voxtype_0.7.5-1_amd64.deb \
  https://github.com/peteonrails/voxtype/releases/download/v0.7.5/voxtype_0.7.5-1_amd64.deb

sudo apt install ./voxtype_0.7.5-1_amd64.deb

voxtype --version

After the upgrade, Voxtype did improve its X11 behavior:

Using xclip for X11 clipboard

But paste mode still failed for me because of the next layer: ydotool.

The ydotool Problem

Voxtype 0.7.5 tried to send the paste shortcut like this:

ydotool key 29:1 47:1 47:0 29:0

On my system, the Ubuntu/Mint ydotool package interpreted that badly and produced:

2442

The same tool worked when called like this:

ydotool key ctrl+v

That told me the problem was not simply “ydotool is missing”. The problem was version and syntax compatibility.

Constraint: I did not want to install random tools with Cargo or manually copied binaries. For this setup, I wanted packages or reversible local config only.

The Practical Decision: Stop Chasing Paste

At this point, paste mode had consumed enough time. The stable solution was to go back to typing output with dotool.

This is less elegant than a single atomic paste, but it works reliably for Codex CLI.

[output]
# 2026-06-19: paste mode is not reliable on this X11 setup; use dotool typing instead.
mode = "type"
fallback_to_clipboard = true
driver_order = [ "dotool" ]
type_delay_ms = 0

This was the key practical lesson: for a terminal prompt, reliable simulated typing is better than fragile paste magic.

The Upgrade Made Transcription Slow

After upgrading Voxtype, transcription suddenly felt much slower. My first suspicion was that I had accidentally deleted or damaged the Whisper config.

I checked the configuration and it was still correct:

[whisper]
model = "base"
language = "it"
translate = false

The real issue was the backend. Before the upgrade, Voxtype was using the Vulkan binary. After the upgrade, the wrapper selected the CPU backend unless GPU mode was enabled again.

The useful check:

voxtype setup gpu

The desired output:

Active backend: GPU (Vulkan)
Binary: /usr/lib/voxtype/voxtype-vulkan

To enable GPU acceleration:

sudo voxtype setup gpu --enable

Running Voxtype as a User Service

Once the configuration worked, I enabled the user service:

systemctl --user enable --now voxtype.service

To check whether it is running:

systemctl --user is-active voxtype.service
systemctl --user status voxtype.service --no-pager

For live logs, this was the command that worked on my system:

journalctl --user-unit=voxtype.service -f

This one did not show logs for me:

journalctl --user -u voxtype.service -f

Disabling Desktop Notifications

Voxtype can show a desktop notification containing the transcribed text. That is useful while debugging, but distracting in daily use.

[output.notification]
on_recording_start = false
on_recording_stop = false
on_transcription = false

Then restart:

systemctl --user restart voxtype.service

Accuracy: The Software Was Not the Whole Story

Once the pipeline worked, I noticed that Italian recognition was still not perfect. For example:

Real audio:     Però non mi sembra funzionare molto bene
Voxtype output: Per anno mi sembra funzionare molto bene

The current model was base, which is fast but not always accurate on short Italian utterances. The first model upgrade to try is:

voxtype setup --download --model small
voxtype setup model --set small --restart

But if the microphone is bad, a bigger model will only help so much. Before blaming Whisper, record the actual microphone input:

pactl list sources short

parecord --duration=5 /tmp/mic-test.wav
paplay /tmp/mic-test.wav

If that recording sounds distant, noisy, clipped, or echoey, the transcription will suffer. This is especially true with a room microphone or the wrong default input device.

Useful Commands

Voxtype status and configuration

voxtype --version
voxtype config
voxtype setup check
voxtype setup gpu
voxtype setup model --list

Manual debug mode

systemctl --user stop voxtype.service
voxtype -vv daemon

Service management

systemctl --user enable --now voxtype.service
systemctl --user restart voxtype.service
systemctl --user status voxtype.service --no-pager
journalctl --user-unit=voxtype.service -f

Input and backend checks

command -v dotool ydotool xclip wl-copy wtype
id
ls -al /dev/uinput
pactl list sources short

Clipboard and typing tests

printf 'TEST\n' | xclip -selection clipboard
xclip -selection clipboard -o

sleep 3; printf 'type Test dotool\n' | dotool
sleep 3; ydotool key ctrl+v

Tips and Tricks

• Do not run voxtype daemon manually while the systemd user service is already active.
• On Cinnamon/X11, be suspicious of solutions that depend on wtype or wl-copy.
• Use F13 to F24 style macro keys when possible. They avoid shortcut conflicts.
• Backup ~/.config/voxtype/config.toml before every experiment.
• If paste mode starts printing numbers like 2442, suspect ydotool syntax compatibility.
• If an upgrade makes transcription slow, check the GPU backend immediately.
• If recognition is bad, test the actual microphone recording before changing five software settings.

Final Working Configuration

This is the pragmatic configuration that worked for me on Linux Mint Cinnamon with Codex CLI:

[hotkey]
# "X" key from the four-symbol macro-key cluster on my keyboard
key = "F16"
mode = "push_to_talk"

[whisper]
model = "base"
language = "it"
translate = false

[output]
# Paste mode was unreliable on this X11 setup; dotool typing is stable.
mode = "type"
fallback_to_clipboard = true
driver_order = [ "dotool" ]
type_delay_ms = 0

[output.notification]
on_recording_start = false
on_recording_stop = false
on_transcription = false

Conclusion

The final solution is not the most elegant theoretical setup. It is the one that works.

I can now hold the F16 macro key, dictate a prompt, release it, and have the text appear inside Codex CLI. Everything runs locally. No cloud dictation. No browser extension. No extra GUI.

The remaining work is not Linux plumbing anymore. It is microphone quality and maybe a better Whisper model. That is a much better problem to have.

And now I can go back to my AI CLI terminal and start dictating my prompts… uhm… I am the “dictator” now! :-P

I was on a train, with about 90 minutes to spend.

I was reading a book called How to Save an Hour a Day.

At some point, the book started talking about the Eisenhower Matrix:
the classic way of organizing tasks based on importance and urgency.

In theory, nothing new.

I already knew the concept.
I use Todoist.
Over the years, I’ve tried more productivity tools than I can remember.

Task managers, kanban boards, calendar-based workflows, note-taking systems pretending to be task managers, and task managers pretending to be life operating systems.

But this time…
one detail caught my attention.

The book suggested assigning a numeric value to both importance and urgency.

Not just putting a task into a quadrant.

A number.

That small difference changed the problem.

The Problem With Most Todo Lists

Most todo lists are very good at collecting things.

They are less good at helping you decide what deserves attention now.

You can add labels, projects, dates, colors, flags, sections, priorities, filters, and recurring rules. But in many tools, “priority” is still something you manually choose.

High. Medium. Low.

Or maybe P1, P2, P3, P4.

That works, but it always felt a bit too static to me.

Because a task is not urgent or important in isolation.

A task becomes more or less relevant depending on several factors:

• how important it is;
• how urgent it is;
• when it is due;
• whether it has already been started;
• how much attention it requires right now.

The Eisenhower Matrix is useful because it forces you to separate importance from urgency.

But many digital tools flatten that distinction again.

They ask you to choose a priority, instead of helping you calculate one.

The Missing Piece: Due Dates

While thinking about importance and urgency, I realized there was another thing I never fully liked in task managers: how due dates are handled.

In many apps, a due date is mostly a label.

It tells you when something is due, but it does not always influence the actual order in which you should work.

Of course, you can sort by due date. But that creates another problem: a low-value task due tomorrow may appear more important than a high-value task that needs real focus.

So I started thinking about a third factor.

What if the due date was not just displayed, but actually contributed to the priority calculation?

That became the core idea:

importance + urgency + due date = operational priority

Not a perfect scientific model.

Just a practical one.

The kind of model that helps you answer a very simple question:

What should I work on now?

Building the First MVP

At that point, I was still on the train.

I had about 90 minutes.

The news about Claude Opus 5.8 had just come out, and I wanted to try it properly on a small but real project.

So I started building.

The first MVP ran inside Claude’s canvas. It was rough, but it already had the essential idea: create tasks, assign numeric values for importance and urgency, add due dates, and calculate a working priority.

It was not meant to be a polished product.

It was a way to test whether the idea made sense once it became interactive.

And it did.

When I got home, I continued with Codex and turned the prototype into a small installable PWA.

The funny part is that the slowest part of the process was not building the application.

It was waiting about 30 minutes for DNS propagation and configuring the Google OAuth keys.

What Urgenzo Does

The result is Urgenzo:

https://urgenzo.com

Urgenzo is a lightweight PWA for managing tasks by calculated priority.

The current version includes:

• task priority based on importance, urgency, and due date;
• offline mode;
• optional Google Drive sync;
• automatic merge of local data after login;
• Pomodoro timer;
• multilingual interface;
• installable PWA experience.

The Google Drive sync was an important design choice.

I did not want to start with a central database, user accounts, billing, subscriptions, or yet another backend for a tiny personal productivity tool.

Instead, if users choose to sign in with Google, their data is saved in their own Google Drive account.

If they prefer not to sign in, they can use the app offline and keep everything on your device.

Why Another Todo App?

This is the obvious question.

The world does not need another generic todo app.

And I agree.

Urgenzo is not trying to replace Todoist, Notion, Things, Trello, Linear, or any other mature productivity system.

It started from a very specific irritation:

I wanted a task list where priority is not just selected manually, but calculated from separate values.

Importance should be one thing.

Urgency should be another.

Due date should matter too.

That small distinction was enough to justify building a tool around it.

Sometimes the best reason to build something is not that the market lacks tools.

It is that none of the tools you already use think exactly the way you want to think.

What I Learned

A few things stood out from this small experiment.

First, constraints help.

A train ride is a good product manager. You do not have infinite time, so you focus on the core mechanic.

Second, AI coding tools are extremely useful when the project is small, concrete, and easy to test manually.

The important part is not asking an AI to “build an app”.

The important part is having a clear behavior in mind and iterating aggressively.

Third, shipping still involves the boring parts.

DNS. OAuth setup. PWA updates. Icons. Copy. Edge cases. Buttons that look wrong. States that feel awkward.

These are not glamorous, but they are where a prototype becomes something usable.

What’s Next

Urgenzo is still early.

There are many things that could improve: better filtering, smarter priority tuning, recurring tasks, export options, keyboard shortcuts, and more refined mobile interactions.

But the first version is live, installable, and already useful.

That is enough for now.

You can try it here:

https://urgenzo.com

Feedback, bug reports, and honest criticism are welcome.

The Problem

If you’ve upgraded to Linux Mint 22 with the Cinnamon desktop environment, you might have encountered an annoying bug: after the first logout and subsequent login, the SSH agent stops working. The SSH_AUTH_SOCK environment variable is no longer set, making SSH key authentication impossible.

Symptoms include:

• Slow terminal startup (tens of seconds)
• $SSH_AUTH_SOCK empty or unset
• systemd sessions stuck in “closing” state
• gnome-keyring and ssh-agent processes lingering from previous sessions

The Root Cause

The issue is caused by a regression in Linux Mint 22 where systemd --user processes and related services (like gnome-keyring-daemon) are not properly terminated on logout. These processes remain active between sessions, preventing the new session from properly initializing the SSH agent.

Note: This is a confirmed bug discussed in the Linux Mint community. You can find the reference thread on GitHub.

The Solution

The solution leverages LightDM’s native session-cleanup-script mechanism, which automatically executes a cleanup script at every graphical logout.

Step 1: Create the Cleanup Script

Create the file /usr/local/sbin/cinnamon-session-cleanup with the following content:

#!/bin/bash
# Script to clean up lingering systemd user processes on logout
# Fixes SSH agent issues in Linux Mint 22

# Log file for debugging (overwritten each logout)
LOG_FILE="/tmp/cinnamon-cleanup-$USER.log"

# Overwrite log file
echo "$(date): Starting Cinnamon session cleanup for user: $USER" > "$LOG_FILE"

# Get user ID from the username
if [ -z "$USER" ]; then
    echo "$(date): ERROR: USER variable is not set" >> "$LOG_FILE"
    exit 1
fi
USER_ID=$(id -u $USER 2>/dev/null)
if [ -z "$USER_ID" ] || [ "$USER_ID" -eq 0 ]; then
    echo "$(date): ERROR: Invalid or root USER_ID ($USER_ID) for user $USER" >> "$LOG_FILE"
    exit 1
fi
echo "$(date): Cleaning up processes for user $USER (UID: $USER_ID)" >> "$LOG_FILE"

# Kill lingering systemd --user process
SYSTEMD_PID=$(pgrep -u $USER_ID "systemd" | head -1)
if [ -n "$SYSTEMD_PID" ]; then
    echo "$(date): Killing systemd --user process (PID: $SYSTEMD_PID)" >> "$LOG_FILE"
    kill -TERM "$SYSTEMD_PID" 2>> "$LOG_FILE"
    sleep 1

    # Force kill if still running
    if kill -0 "$SYSTEMD_PID" 2>/dev/null; then
        echo "$(date): Force killing systemd --user process" >> "$LOG_FILE"
        kill -KILL "$SYSTEMD_PID" 2>> "$LOG_FILE"
    fi
fi

# Clean up any lingering ssh-agent processes
SSH_AGENT_PIDS=$(pgrep -u $USER_ID "ssh-agent")
if [ -n "$SSH_AGENT_PIDS" ]; then
    echo "$(date): Killing ssh-agent processes: $SSH_AGENT_PIDS" >> "$LOG_FILE"
    kill -TERM $SSH_AGENT_PIDS 2>> "$LOG_FILE"
fi

# Clean up gnome-keyring-daemon
KEYRING_PIDS=$(pgrep -u $USER_ID "gnome-keyring")
if [ -n "$KEYRING_PIDS" ]; then
    echo "$(date): Killing gnome-keyring processes: $KEYRING_PIDS" >> "$LOG_FILE"
    kill -TERM $KEYRING_PIDS 2>> "$LOG_FILE"
fi
echo "$(date): Cleanup completed" >> "$LOG_FILE"

Set the correct permissions:

sudo chown root:root /usr/local/sbin/cinnamon-session-cleanup
sudo chmod 755 /usr/local/sbin/cinnamon-session-cleanup

Step 2: Configure LightDM

Create the configuration file /etc/lightdm/lightdm.conf.d/99-cleanup.conf:

[Seat:*]
session-cleanup-script=/usr/local/sbin/cinnamon-session-cleanup

Important: After creating the LightDM configuration, you need to restart LightDM for the changes to take effect. You can either:

Option 1 — Restart LightDM (recommended):

sudo systemctl restart lightdm

Warning: This will immediately terminate your current graphical session. Save all your work first!

Option 2 — Reboot the system.

Without restarting LightDM or rebooting, the cleanup script won’t be executed on logout.

Step 3: Test the Solution

After restarting LightDM or rebooting, logout and log back in.

After login, verify everything works:

# Check if SSH_AUTH_SOCK is set
echo $SSH_AUTH_SOCK

# Verify the socket exists
ls -la $SSH_AUTH_SOCK

# Check the cleanup script log
cat /tmp/cinnamon-cleanup-$USER.log

Success: If $SSH_AUTH_SOCK is set and the socket exists, the problem is solved. The log will show which processes were terminated during the previous logout.

Troubleshooting: If the log file /tmp/cinnamon-cleanup-$USER.log doesn't exist after logout, it means the cleanup script was not executed. This usually indicates that LightDM wasn't restarted after creating the configuration file.

Why This Solution Works

The solution leverages LightDM’s native session-cleanup-script mechanism, which:

• Executes automatically at every graphical logout
• Runs with root privileges (necessary to terminate systemd processes)
• Receives the $USER variable set to the user logging out
• Is a stable and documented feature of LightDM

The script cleanly terminates:

1. Lingering systemd --user processes
2. Orphaned ssh-agent processes
3. Stuck gnome-keyring daemons

This allows the new session to properly initialize all services, including the SSH agent.

Non-Working Alternatives

During the analysis of this problem, several alternatives were considered that do not fully solve the issue:

• Script in ~/.bash_logout: Only works for terminal logout, not graphical logout
• Wrapper for cinnamon-session-quit: Complex and fragile to updates
• Direct patching of system scripts: Lost with every package update
• Workaround in ~/.bashrc: Doesn't fix the cause, only the symptoms

Advantages of This Solution

• ✅ Native: Uses standard LightDM mechanisms
• ✅ Reliable: Guaranteed to execute on every logout
• ✅ Persistent: Survives system updates
• ✅ Clean: Doesn’t modify system files
• ✅ Debuggable: Complete log in /tmp/cinnamon-cleanup-$USER.log

Conclusions

The SSH agent bug in Linux Mint 22 is caused by systemd processes that aren’t properly terminated on logout. The solution using LightDM’s session-cleanup-script definitively solves the problem in a clean and elegant way, without workarounds or fragile patches.

This solution has been tested on Linux Mint 22 with Cinnamon 6.2.7 and works perfectly. If you’ve encountered the same problem, try this solution and let me know how it goes!

Or: The Day I Became a “Developer” by Being a Good Product Manager

TL;DR

I built a fully functional Progressive Web App for travel planning in less than 24 hours without writing any code myself. The secret? No build process. No backend. No complexity. Just static files and local storage.

Instead of wasting time on infrastructure, I acted as a product manager while Claude Code handled implementation. The result? A production-ready app with offline support, Google Places integration, route optimization, and mobile-first design. Ship fast, iterate later.

The Challenge: “I Need a Travel Planner App… Yesterday”

Like many of you, I’ve been frustrated with existing travel planning apps. They’re either too complex, require expensive subscriptions, or don’t work offline when you actually need them while traveling. I wanted something simple:

• Add points of interest (POIs) to my trip
• See them on a map with real-time visualization
• Calculate optimal routes between locations
• Work 100% offline after first load
• No accounts, no cloud, just local storage

The problem? I’m not a developer. I understand technology, I can read code, but asking me to set up a modern JavaScript development environment? That’s where I usually give up.

Enter Claude Code: My AI Pair Programmer (Who Does All the Programming)

I’d heard about Claude Code, Anthropic’s coding assistant, and decided to give it a shot. My approach was different from typical tutorials — I wouldn’t write any code. Instead, I would:

1. Be the Product Manager: Define features clearly
2. Be the QA Tester: Test everything thoroughly
3. Be the Designer: Provide UI/UX feedback
4. Be the User: Use the app and report issues

Claude Code would be my entire development team.

The Secret Weapon: CLAUDE.md — My Development Contract

Before writing any code, I did something that changed everything: I created a detailed specification document called CLAUDE.md. This wasn't just documentation - it was a contract between me and my AI developer.

The document included:

• Project Overview: Clear description of what RouteMyWay should do
• Core Features: Detailed list of functionalities
• Tech Stack: My chosen architecture (Preact + HTM + Signals)
• Project Structure: Exact file organization
• Implementation Examples: Code snippets showing the preferred style
• Phase-by-phase Task List: Breaking down the work into testable chunks

The game-changer was the task list at the end:

## Phase 1: Core Foundation ✅
- [ ] Create project structure
- [ ] Setup basic HTML with CDN links
- [ ] CSS styles
- [ ] Create basic app.js with Preact initialization
- [ ] Test that app loads without errors

## Phase 2: State Management 📊
- [ ] Implement store.js with signals
[... and so on for 13 phases]

My instruction to Claude Code: “Stop at the end of each phase so I can test the UI”

This approach meant:

1. I always knew what was being built
2. I could test incrementally (no big bang integration)
3. Claude Code had clear context for every decision
4. We caught issues early, not after 1000 lines of code

The Productivity Hack: SHIFT+TAB for Warp Speed Development

Here’s a Claude Code power user tip that cut development time in half:

SHIFT+TAB toggles between two modes:

• Plan Mode: Claude explains what it will do before doing it
• Auto-Accept Mode: Claude makes changes immediately without confirmation

It’s almost mandatory to use SHIFT+TAB to make this work efficiently. My workflow:

1. Start in Plan Mode for architectural decisions
2. Switch to Auto-Accept (SHIFT+TAB) once we agree on approach
3. Let Claude Code fly — implementing exactly what we discussed at maximum speed
4. No reviewing every single edit — I trust the plan we made
5. Test the result at phase completion

This is crucial because reviewing 50 individual file edits is exhausting and kills momentum. By agreeing on the plan upfront and then switching to auto-accept, I maintained flow state while Claude Code executed at full speed. Without auto-accept mode, you’ll spend more time reviewing code than actually building — defeating the whole purpose of AI-assisted development.

Important: This only works because of the CLAUDE.md specification and phased approach. You need clear guardrails before unleashing auto-accept mode. But once you have them, SHIFT+TAB is your best friend for rapid development.

The Architecture Discussion That Set Everything Up

With CLAUDE.md as our guide, the first conversation was smooth. I came prepared with a specific architecture in mind:

Me: “I want a travel planner PWA with Preact + HTM + Signals. No build process, just static files I can serve anywhere. Use Leaflet for maps, LocalForage for storage.”

Claude Code: Acknowledges and implements the architecture exactly as specified

This was my key insight — I knew modern tools that work without build processes:

• Preact + HTM: React-like development without JSX compilation
• Signals: Simple state management without Redux complexity
• CDN loading: No npm, no node_modules, no webpack
• Static files: Deploy anywhere, edit with any text editor

But the most crucial decision? No backend. This wasn’t about being fancy — it was about speed:

The 24-Hour Magic Formula:

• No build process = Start coding immediately (save 2–4 hours)
• No backend API = Skip authentication, databases, deployments (save 8–12 hours)
• No npm/webpack = No dependency hell or build configs (save 2–3 hours)
• CDN libraries = Just add script tags and go (save 1–2 hours)
• Local storage only = No server state to manage (save 4–6 hours)

Total time saved: 17–27 hours of typical development overhead!

What we built instead:

• LocalForage: IndexedDB storage that works offline
• No user accounts: No authentication complexity
• No API to build: Just integrate existing services (OpenStreetMap, Google Places)
• Simple hosting: Just rsync to any static server
• No database: Your data stays on your device

This “local-first” approach meant we could focus 100% on user experience instead of wrestling with servers, databases, and deployment pipelines. We went from idea to working app in 24 hours because we didn’t build what we didn’t need.

The philosophy is simple: Get a working prototype FAST, then add features later. Need user accounts? Add them in v2. Want cloud sync? Ship it next week. But on day one? Ship something that actually works!

Claude Code perfectly implemented my architectural vision. The lesson? Coming with a clear technical direction accelerates everything.

The Development Process: A Real Conversation

Here’s what our actual workflow looked like:

Hour 1–4: Core Structure

Me: “Create the basic app structure with trips and days”
Claude Code: Creates file structure, implements basic components
Me: “The trip cards need edit and delete buttons”
Claude Code: Adds the features
Me: “Actually, I want inline editing for trip names”
Claude Code: Refactors to support inline editing

Hour 5–8: The Map Integration

Me: “Add a map view with POI markers”
Claude Code: Integrates Leaflet, creates map component
Me: “The markers are too small on mobile”
Claude Code: Adjusts sizes and adds touch-friendly interactions

Hour 9–12: Search Functionality

Me: “I need to search for POIs”
Claude Code: Implements OpenStreetMap Nominatim search
Me: “Can we add Google Places for better results?”
Claude Code: Adds optional Google Places API integration
Me: “It’s making too many API requests!”
Claude Code: Implements grid-based caching system

Hour 13–16: Route Optimization

Me: “Add route calculation between POIs”
Claude Code: Implements nearest-neighbor algorithm
Me: “It should return to base at the end”
Claude Code: Adds circular route logic

Hour 17–20: Mobile UI Fixes

This is where it got interesting. Real users (me) testing on real devices:

Me: “The FAB button is hidden behind Android’s navigation bar”
Claude Code: Adds safe area insets and dynamic viewport heights

Me: “Buttons are too small for fingers on mobile”
Claude Code: Implements 44px touch targets per iOS Human Interface Guidelines

Me: “The daily view UI is terrible on mobile!”
Claude Code: Creates responsive card layout for small screens

Hour 21–24: Polish and PWA Features

Me: “Add offline support and make it installable”
Claude Code: Implements service worker with Workbox
Me: “Version updates aren’t working properly”
Claude Code: Adds version management and update notifications

The Deployment Magic: From Localhost to Production in Minutes

Here’s where the no-build architecture really shined. My deployment process:

Local Development: Simple Python HTTP server

python3 -m http.server 8000

That’s it. No npm install, no build watch, no hot reload complexity.

Version Management: The PWA Update Magic

Here’s the clever part — PWAs cache everything for offline use, which creates a problem: how do users know there’s a new version? My solution connects version management to PWA updates:

// Auto-generated version file - DO NOT EDIT MANUALLY
const APP_VERSION = '1.0.10';
const BUILD_TIMESTAMP = '2025-07-22T21:12:04Z';

This simple file solves multiple problems:

For PWA Installation:

• Service worker includes version.js in its cache manifest
• Each deployment changes the version number
• Changed version = changed file hash = service worker update trigger
• Users who installed the PWA get automatic update notifications

How it works:

1. User installs PWA (it caches version.js with “1.0.23”)
2. I deploy new version (Makefile bumps to “1.0.24”)
3. User opens PWA next time
4. Service worker sees version.js changed
5. Shows “Update available!” notification
6. User clicks update, gets latest version
7. Without this trick, PWA users would be stuck on old versions forever since everything is cached offline!

1My Makefile: Dead simple deployment

# Route My Way - Simple deployment

VERSION_FILE = public/js/version.js
CURRENT_VERSION := $(shell grep "APP_VERSION" $(VERSION_FILE) 2>/dev/null | cut -d"'" -f2 || echo "1.0.0")

# Increment version and deploy
publish:
 $(eval NEW_VERSION := $(shell echo $(CURRENT_VERSION) | awk -F. '{print $$1"."$$2"."$$3+1}'))
 @echo "// Auto-generated version file - DO NOT EDIT MANUALLY" > $(VERSION_FILE)
 @echo "const APP_VERSION = '$(NEW_VERSION)';" >> $(VERSION_FILE)
 @echo "const BUILD_TIMESTAMP = '$$(date -u +%Y-%m-%dT%H:%M:%SZ)';" >> $(VERSION_FILE)
 @echo "Version: $(CURRENT_VERSION) → $(NEW_VERSION)"
 
 rsync -avz --delete --progress public/ www.routemyway.com:/var/www/public/

One command updates version, deploys files, and triggers PWA updates for all users!

The Service Worker Integration:

// Import version from auto-generated file
importScripts('/js/version.js');

This is crucial for PWAs because:

• Regular websites: Users refresh and get new version automatically
• PWAs: Everything cached offline, users might never get updates
• This trick: Automatic update notifications for installed PWAs

Production: Static Nginx hosting

• No Node.js server
• No PM2 process manager
• No Docker containers
• Just static files served fast

The result? Deploy in literally 5 seconds:

make publish

From localhost:8000 to https://www.routemyway.com/ in one command.

No CI/CD pipeline, no build artifacts, no deployment slots. Just files copying to a server.

The Surprising Parts

1. Debugging Without Seeing

Claude Code can’t see the screen or run the code. Every bug had to be described:

• “The tourist information centers aren’t showing”
• “Console shows ‘setAsBase is not defined’ error”
• “The cache seems ignored when I move 50 meters”

Yet it successfully debugged complex issues through description alone.

2. Handling My Frustration

Yes, I got frustrated. When the Google Places API wasn’t working after multiple attempts, I actually wrote: “please update to the f***ing beta version of the new api”

Then immediately followed with: “yeah I’m sorry Claude you make me nervous sometimes”

Claude Code calmly fixed the issue without taking offense. Try that with a human developer! The ability to vent frustration and then apologize to an AI that just keeps helping? Priceless.

3. Architecture Decisions That Scaled

The initial architecture decisions (no build process, CDN-based libraries, signal-based state) held up throughout development. We never had to refactor the fundamental structure.

The Technical Achievements

Without writing a single line of code myself, we built:

1. Complete PWA Features:

• Offline support with intelligent caching
• Install prompts for home screen
• Auto-update detection via version.js
• iOS and Android optimizations

2. Advanced Functionality:

• Dual search APIs (OSM + Google Places)
• Grid-based POI caching to minimize API calls
• Route optimization with return-to-base
• Real-time location tracking

3. Production-Ready UI:

• Responsive design that actually works
• 44px touch targets for mobile
• Safe area handling for modern devices
• Proper mobile viewport management

4. Developer-Friendly Architecture:

• No build process needed
• All state in signals (reactive)
• Clean component structure
• Proper error handling
• Version auto-increment via Makefile
• 5-second deployments with rsync
• Service worker updates on version change

The Mistakes We Made (And Fixed)

1. Over-engineering Mobile UI: First attempt at mobile optimization made desktop worse
2. Cache Key Design: Initially included zoom level, causing unnecessary API calls
3. Button Placement: Moved buttons to the left on mobile, broke desktop layout
4. API Integration: Tried using deprecated Google Places API three times

Each mistake was caught by testing and fixed through conversation.

Lessons Learned

1. Write a Spec First (CLAUDE.md is Your Best Friend)

Before asking for any code, write a detailed specification. Include examples, architecture decisions, and a phased task list. This one document saved hours of back-and-forth.

2. Demand Incremental Testing

“Stop at each phase so I can test” — This single instruction prevented countless bugs. Never let an AI write 500 lines without testing.

3. Be a Product Manager, Not a Coder

The clearer my requirements, the better the output. Vague requests led to wrong implementations.

4. Describe Problems Precisely

“It doesn’t work” wastes time. “Console shows X error when I click Y” gets instant fixes.

5. Trust Your Architecture

When you choose an architecture (like my no-build approach), stick with it. It saved hours of setup time.

6. Mobile-First Really Matters

Most issues appeared on mobile. Should have tested mobile earlier.

The Result

In 24 hours, without writing code, I have:

• A fully functional PWA deployed at https://www.routemyway.com/
• 100% Lighthouse PWA score
• Works offline after first load
• Installs on iOS and Android
• Actually useful for my next trip

Could You Do This?

Absolutely. You need:

1. Clear thinking about what you want
2. Patience to test and describe issues
3. Basic understanding of how web apps work
4. Claude Code subscription
5. SHIFT+TAB keyboard shortcut memorized (this is almost mandatory!)

You don’t need:

• Programming experience
• Development environment
• Build tools knowledge
• Years of training

Pro tip: The difference between a 24-hour project and a 72-hour project? Using auto-accept mode once you trust your plan. Seriously, SHIFT+TAB is almost mandatory — without it, you’ll spend 80% of your time clicking “Accept” buttons instead of building. Plan first, then let Claude Code execute at full speed.

The Future of Development?

This experience made me reconsider what “development” means. If I can build a production app by describing what I want, what does that mean for:

• Experienced developers: Focus on architecture and complex problems
• Product managers: Directly build prototypes and MVPs
• Entrepreneurs: Test ideas without technical co-founders
• Education: Teach problem-solving, not syntax

Try It Yourself

The app is live at https://www.routemyway.com/ — try it out!

Want to build something similar? Here’s my advice:

1. Start with a clear problem you personally face
2. Write a detailed CLAUDE.md specification first
3. Choose “boring” architecture (no backend = no complexity)
4. Demand phased development with testing breaks
5. Be specific about requirements
6. Test everything on real devices
7. Don’t be afraid to say “this sucks, fix it”

Remember: Every feature you don’t build is a feature that can’t break. My app has no servers to crash, no database to corrupt, no API keys to leak. It just works.

Useful Resources:

• Claude Code Documentation
• Preact Getting Started
• Progressive Web Apps Guide
• LocalForage Documentation

Conclusion

I built a real app in 24 hours without coding. Not a prototype, not a demo — a production app I’m using for my trips.

The secret wasn’t AI magic. It was radical simplicity:

• No build process = No setup time
• No backend = No server complexity
• No database = No schema design
• Just HTML, CSS, and JavaScript from CDNs

This infrastructure choice saved 20+ hours of typical setup time. That’s why we could build a complete app in 24 hours.

The barrier to building software has fundamentally changed. The question isn’t “Can I build this?” anymore. It’s “What should I build?” and more importantly: “What can I ship TODAY?”

Remember: You can always add complexity later. But you can’t ship later if you’re still configuring webpack.

What will you build in your next 24 hours?

Follow me for more no-code development adventures and buildless PWA projects!

See also: https://medium.com/@antoniogallo.it/creating-a-buildless-javascript-application-with-preact-htm-and-signal-f99386ad36d4

You can find me at: https://www.antoniogallo.it/

Appendix: Actual Conversation Snippets

For the skeptics, here are real exchanges from our development session:

On caching issues:

Me: “cached poi seems ignored when i just move by a miserable 50 meter on the map”
Claude Code: [Implements 1.1km grid cells for consistent caching]

On mobile UI:

Me: “the thumb is 60x60 can it be large on card?”
Claude Code: [Updates to 120px images on mobile cards]

On architecture:

Me: “No build process required! Just serve static files”
Claude Code: [Designs entire app around CDN-loaded modules]

This wasn’t magic. It was clear communication plus capable AI.

The deprecation of preact-router left a gap for those of us who rely on Preact for building lightweight and efficient web applications.

While preact-iso has emerged as a powerful alternative, it unfortunately does not support hash-based navigation.

This posed a significant challenge for projects that rely on hash navigation, such as hybrid apps using WebViews in frameworks like Ionic and Cordova.

Additionally, while there are other routing solutions available, such as wouter and react-router, these options often come with a level of complexity and size that I wanted to avoid.

My goal was to create something minimalistic and specifically tailored to Preact, making use of preact-signals for reactive state management and htm for a JSX-like syntax without the overhead.

Thus, I set out to build a custom router that meets these specific needs:

1. Compatibility with Hash and URL Navigation: Ensuring seamless support for both hash-based navigation and standard URL navigation to cater to a wide range of web applications and hybrid apps.
2. Lightweight and Minimal: Avoiding the bloat and complexity of larger routing libraries, providing a lean solution (66 lines of code) for developers who value simplicity and performance.
3. Designed for Preact: Specifically tailored to work smoothly with Preact, leveraging preact-signals for an optimal development experience.

This custom router addresses the unique requirements of developers who need a simple yet powerful routing solution for Preact applications, both in the browser and in hybrid app environments.

Example using HTM in place of JSX:

<${Router} prefix="/#" fallback=${PageNotFound}>
    <${Route} path="/" component=${PageLogin}/>
    <${Router} path="/uno/*" prefix="/#/uno" fallback=${PageNotFound}>
        <${Route} path="/uno/" component=${PageUno}/>
        <${Route} path="/due/*" component=${PageDue}/>
        <${Route} path="*" component=${PageNotFound}/>
    <//>
    <${Route} path="/due/*" component=${PageCorsi}/>
<//>

And you can navigate in those ways:

<a class="btn" href="#/due/alfa/">TEST2</a>
<button class="btn" onclick="${()=>{route('#/due/alfa/')}}">TEST2</button>

You can grab the library from github:

GitHub - badpenguin/preact-signal-browser-router: A barebone hash and url router for browsers using preact+signals

About Me

I have got 40+ years experience in Open Source technologies. I am a Developer, Speaker and Trainer. Please check my Linkedin profile or https://antoniogallo.it

In the era of modern web development, the complexity of build tools can sometimes become a barrier for beginners and those who prefer to keep things simple (K.I.S.S.).

However, with the emergence of libraries like Preact, HTM, and Signal, creating a buildless JavaScript application has become not only feasible but also efficient.

This approach allows developers to set up a project quickly without the overhead of build configurations, making the development process faster and more straightforward.

Why Choose Preact, HTM, and Signal?

• Preact: A fast 3kB alternative to React with the same modern API, Preact provides the thinnest possible Virtual DOM abstraction on top of the DOM. Its simplicity and small size make it ideal for buildless setups where every byte counts.
• HTM: Hyperscript Tagged Markup (HTM) allows you to use JSX-like syntax directly in the browser without transpilation. HTM pairs beautifully with Preact to offer a developer-friendly template making experience without a build step.
• Signals: A state management library that works seamlessly with Preact, offering a simple and efficient way to handle application state with fine-grained reactive programming.

Setting Up a Buildless Environment

You can start from my skeleton App from github here:

https://github.com/badpenguin/buildless-pwa

The whole buildless concept is based on 2 pillars:

1. ES Modules and ImportMap — in place of a bundler;
2. A template literals library, HTM — in place of JSX.

So your browser must be compatibles with ImportMap, this is not always the case. That’s why I suggest to add this polyfill at the beginning:

https://github.com/guybedford/es-module-shims

i.e.:

<script async src="https://ga.jspm.io/npm:es-module-shims@1.7.3/dist/es-module-shims.js"></script>

After that you will notice a couple of check for support of “fetch” and other functionalities also.

No matter that this skeleton will work on modern browsers: I suggests you to always check for the device’s capabilities.

Out there it’s full of strange older devices like old “Smart TV”, and crazy JVM; so it does not hurt to display them that their browser is too old.

Here it comes the importmap.

Here we specify to the JS engine where it can find any library that we will try to import.

The importmap in the HTML file declares dependencies directly, pointing to a bundled version of Preact, HTM, and Signal that can be loaded via script tags.

This setup bypasses the need for a bundler or module loader during development.

 <script type="importmap">
      {
        "imports": {
          "preact": "/app/dist/standalone.js",
          "preact/hooks": "/app/dist/standalone.js",
    "htm": "/app/dist/standalone.js",
          "@preact/signals": "/app/dist/standalone.js",
          "@preact/signals-core": "/app/dist/standalone.js",
          "preact-router": "/app/dist/preact-router.module.js"
        }
      }

 </script>

You can specify remote libraries aswell but I prefer to always use a local copy. Expecially if I’m going to bundle this webapp also into a mobile app using a WebView like Cordova.

Did you noticed standalone.js?

I’ve a few libraries packed all togheter in a single file. Thanks to this project:

https://github.com/mujahidfa/preact-htm-signals-standalone

In only 22KB I got Preact with hooks and signals + HTM template library.

Now we’re ready to bootstrap our main application component:

 <script type="module">
  import {h, render} from 'preact';
  import {MainApp} from '/app/main.js';

  window.onload = function() {
   console.log('* onload');
   const app = h(MainApp);
   render(app, document.getElementById("main"));
  }
 </script>
<div id="main"></div>

If you’re familiar with React this is just “hello world” for you.

Notice that the main component is into a separate file, main.js, loaded locally. The “/app/main.js” can actually be an absolute or relative URL, not a file path.

The splash screen example

AS bonus I’ve included a simple splash screen as an example of using “Signals”.

This will be visible while our application is initializing.

Make sure to put all the CSS and the HTML for your splash screen inside the main index.html (don’t relay on external files).

Also if possibile include image inline as base64 to avoid any external HTTP request, otherwise we will loose the concept of “preload” here.

 <style>
  #preload {
   color: #6d1153;
   background: #fff;
   padding: 1rem;
   position: fixed;
   top: 0;
   left: 0;
   right: 0;
   bottom: 0;
   display: flex;
   flex-direction: column;
   align-items: center;
   justify-content: center;
   text-align: center;
   font-family: sans-serif;
   font-size: 18px;
   line-height: 1.7;
  }

  #preload img {
   display: block;
   margin-bottom: 2rem;
  }

  #preload p, #preload h1 {
   color: #333;
  }

  #preload a {
   color: #FF1978;
  }
 </style>
<div id="preload">
 <h1>Loading...</h1>
 <p>For more info please visit: <a href="https://www.antoniogallo.it/">www.antoniogallo.it</a></p>
</div>

In main.js I will show you in detail how this gets hidden.

Developing with HTML instead of JSX

And this is the “Main” component:

import {html} from 'htm';
import Router, {route} from 'preact-router';
import {signal} from '@preact/signals';
import {effect} from '@preact/signals-core';

export function MainApp() {
 console.debug('- render MainApp');
 return html`
  ${$loading.value ? null : html`
   <${Router}>
    <${PageHome} path="/"/>
    <${PageNotFound} default/>
   <//>`}
 `;
}

As you can see it does not use JSX but the HTM library.

HTM syntax is used for creating JSX-like components directly in the browser, and Signal manages the state changes reactively, updating the UI in response to user interactions.

In this component until $loading is TRUE then nothing will be rendered (NULL), i.e. our div#preload will be still visibile in place of div#main.

When the loading is completed it will finally render our page according to the preact-router’s settings.

The $loading variable is an object created with preact-signal:

export const $loading = signal(true);

You can create your own initialization function to pre-populate your main component and finally set this variable to FALSE when you’re finished:

setTimeout(function(){
 console.log('- loading completed.');
 $loading.value = false;
}, 1000);

Using “effect ” and “dispose” we can intercept “una tantum” when $loading changes its value and hide the splash screen:

const dispose = effect(() => {
 if ($loading.value) {
  return;
 }
 console.debug('- app ready');
 // Hide Preload
 const preloadDiv = document.getElementById("preload");
 preloadDiv.style.display = "none";
 dispose();
});

Since $loading is used inside our “Main” component too, it will automatically trigger the re-render of our Main component.

Creating a simple counter with Signal and HTM

This is very straightforward example. First create your variable:

export const $counter = signal(0);

and then manipulate it with those two buttons:

const PageHome = function() {
 console.debug('- render PageHome');
 return html`
  <div class="page active ">

    <div class="flex-row">

     <a class="btn" onclick="${() => {
      $counter.value--;
     }}">\u00AB</a>

     <span class="counter">${$counter}</span>

     <a class="btn" onclick="${() => {
      $counter.value++;
     }}">\u00BB</a>

    </div>

  </div>`;
};

TIPS: in HTM you cannot use HTML entities like » because those will be rendered as written. The trick is to use the \u0000 syntax instead.

So that’s all.

Feel free to add your Manifest.json and your favourite ServiceWorker implementation to create a full working PWA.

Benefits of a Buildless Approach

• Simplicity: There’s no need to maintain webpack, Rollup, or other build configurations, which simplifies the setup and reduces the potential for build-related issues.
• Speed: Changes are reflected immediately upon refreshing the browser, speeding up the development cycle.
• Focus on Code: Developers can focus more on coding rather than on tooling, which is especially beneficial for small projects or during the initial stages of development.

Drawbacks to Consider

• Scalability: As the project grows, the lack of a build system might limit optimization options like tree shaking, minification, and advanced bundling strategies.
• Browser Compatibility: Relying heavily on modern browser features may limit the application’s compatibility with older browsers.

Conclusion

Utilizing Preact, HTM, and Signals for a buildless JavaScript application provides an excellent balance between modern development practices and simplicity.

This approach is particularly appealing for developers looking to create lightweight applications or prototypes rapidly.

While it may not suit every project, especially large-scale applications, it offers a compelling option for those prioritizing quick setups and fewer dependencies.

About Me

I have got 40+ years experience in Open Source technologies. I am a Developer, Speaker and Trainer. Please check my Linkedin profile or https://antoniogallo.it

To avoid this I created a WordPress theme that leverage the Gutenberg editors and then, parsing all the blocks, generates a working EPUB file and a LibreOffice ODT file using PHPWord.

I assume you will read other basic tutorial and getting started about PHPWord, i’m not going to cover those topics. I wish you just to describe all the problems I found and how I did solved them.

Output Format

As soon as I tried to add more complex formatting beside simple paragraphs: images, tables, blocks i discovered that the PHPWord driver for exporting into LibreOffice’s format is not complete.

So, first advice i wish to give is to switch to DOCX.

$objWriter = IOFactory::createWriter( $phpWord, 'Word2007' );
$objWriter->save( $zipRealFileName );

Document Metadata

Of course we are going to publish a book on Amazon so its important to fill-in all the document’s metadata:

$properties = $phpWord->getDocInfo();
$properties->setCreator( get_ebook_author() );
$properties->setCompany( get_ebook_author() );
$properties->setTitle( get_ebook_title() );
$properties->setDescription( get_ebook_description() );
$properties->setCreated( get_ebook_date_created() );
$properties->setModified( time() );

Twips? What’s that?

Almost all the function call of PHPWord requires a parameter to be expressed in twips. But no worries, there is a Converter class that has lots of static method that helps you to convert value from the correct source:

Converter::cmToTwip(2)
Converter::pointToTwip( 1.75 )
Converter::inchToTwip( 0.5 )
Converter::pixelToTwip( 800)

Document Size

Setting document is simply done with:

$paper = new Paper();
$paper->setSize( 'A4' );

this will convert your constant into width and height using a lookup table. However only a few strings are configured by default.

However our book on Amazon is 8x10" so I had to patch the Paper class to add support for that size.

After you have created the paper object then you can define the style’s settings for the default section of page:

$duecm = Converter::cmToTwip( 2 );

$sectionMargins      = array(
   'marginTop'    => $duecm,
   'marginLeft'   => $duecm,
   'marginRight'  => $duecm,
   'marginBottom' => $duecm,
   'breakType'    => 'continuous',
   'pageSizeW'    => $paper->getWidth(),
   'pageSizeH'    => $paper->getHeight(),
);

Then use those settings to create the first section of the document:

$section = $phpWord->addSection( $sectionMargins );

Default Font

The default font is easy… the tricky part is that setDefaultFontSize() will not accept a float value, you have to edit the method and comment the line where they use intval() to convert the value to integer.

$phpWord->setDefaultFontName( 'Libre Baskerville' );
$phpWord->setDefaultFontSize( 8.5 );
$phpWord->setDefaultParagraphStyle( array(
   'lineHeight' => 1.3,
) );

Titles / Headers

To configure the default built-in styles of the document for the headers: Title, Title 1, etc. You just use addTitleStyle(). The first parameter is the header starting with “null” for the main one and then 1, 2, 3, etc.

$phpWord->addTitleStyle( 3,
   array(
      'name'  => 'Droid Sans',
      'size'  => 15.5,
      'color' => 'e07743'
   ),
   array(
      'pageBreakBefore' => false,
      'spaceBefore'     => Converter::cmToTwip( 0.8 ),
      'spaceAfter'      => Converter::cmToTwip( 0.2 ),
      'keepNext'  => true,
      'lineHeight' => 1,
   )
);

Fixing Elements

Ok its now time to fix some weird issue I got with Elements.

Tables

Those are probably the most complicated things. I managed to have them working but the formatting cannot be very complex. Converting HTML to tables didn’t worked, i.e. addHtml(). You have to use the method that I will explain below.

First of all we need a few styles.

Lets define a style for the table that is 100% width and centered:

$stileTabella             = array(
   'width'            => 100 * 50,
   'unit'             => 'pct',
   'cellMarginBottom' => Converter::cmToTwip( 0.5 ),
   'alignment'        => JcTable::CENTER,
);

If you want borders and a little more spacing also add:

'borderSize'       => 1,
'borderColor'      => '333333',
'cellMargin'       => Converter::cmToTwip( 0.5 ),
'cellSpacing'      => Converter::cmToTwip( 0.5 )

Then we need a style for the rows:

$stileRiga = array( 'tblHeader' => false, 'cantSplit' => false );

Its important here:

• tblHeader — will make the table first row to repeat when the table is split onto another page;
• cantSplit — will prevent the table from splitting, i.e. false=don’t split; true=split;

For cells we don’t need particular styles, only if you want to add some general formatting, i.e. like centering them.

Ok to create a table the important thing to remember is to always give the cell a width value, the first parameter, if you use null as on some example it won’t work.

So the correct way is:

$cellWidth = Converter::cmToTwip( 5 );

$table = $section->addTable( $stileTabella );
$table->addRow( null, $stileRiga );
$cell = $table->addCell( $cellWidth);
$cell->addText('this is my column content');

So, its up to you to calculate the correct $cellWidth.

Well you have the pageWidth, remove the margin and then divide by the number of columns.

Switching from one column to two column

To switch to two column text layout and then back to one column, Ijust created two styles that needs to be applied to sections.

$styleSingleColumn = array( 'breakType' => 'continuous', 'colsNum' => 1 );

$styleTwoColumn    = array(
   'breakType' => 'continuous',
   'colsNum'   => 2,
   'colsSpace' => Converter::cmToTwip( 0.5 )
);

$twoColSection = $section->addSection($styleTwoColumn);

$oneColSection = $twoColSection->addSection( $styleSingleColumn );

Image flow and captions

In LibreOffice we have text flow of the image that can be “separated” like we when we use display:block on an IMG tag. In Docx this is not supported. The only way to achieve this is to create a table with a single row and a single cell and add the image and the caption inside of it.

Avoid Breaking of Content

Not sure if this work everywhere in the document but at least works for the image inside the table’s cell with its own caption. The trick is to use addTextRun() instead of addText() and use the “keepLines” option:

$textrun = $cell->addTextRun( array(
   'keepLines' => true,
   'alignment' => 'center',
) );

Boxes with Borders

Having boxes (container or text) with borders does not seems supported. The trick, again, is to use tables and add the border directly to the cells.

In this case we create a style for the cell:

$cell = $table->addCell( $cellWidth, array(
   'bgColor'         => 'afded8',
   'borderLeftColor' => '000000',
   'borderLeftSize'  => Converter::pointToTwip( 1.75 ),
   'valign'          => 'center',
) );

This is the result:

HTML Lists

When converting an HTML fragment with an UL or OL list i got the first line always breaking onto another line.

I found a workaround by just adding a text break before and after it:

$section->addTextBreak( 1 );
Html::addHtml( $section, $innerHtml, false, true );
$section->addTextBreak( 1 );

HTML Paragraph: strange whitespace

I got very weird whitespace issue when converting HTML paragraps into the docx using:

Html::addHtml( $section, $innerHtml, false, true );

It seems the addHtml() when parsing via DOMDocument has problem with the newlines that WordPress adds inside the HTML fragment.

I resolved by replacing back those newslines with spaces and removing duplicated whitespaces:

function fix_gutenberg_newlines($html) {
   $html = preg_replace("/\r/m", "", $html);
   $html = preg_replace("/\n/m", " ", $html);
   $html  = preg_replace("/\s\s+/m", " ", $html);
   return $html;
}

TOC / INDEX

This has been particularly hard to discover, it required a lot of reading of github’s issues.

First we need to set this properties:

$phpWord->getSettings()->setUpdateFields( true );

Then you need to create a numberingStyle:

$phpWord->addNumberingStyle(
   'hNum',
   array(
      'type'   => 'multilevel',
      'levels' => array(
         array( 'pStyle' => 'Heading1', 'format' => 'none', 'suffix'    => 'nothing', ),
         array( 'pStyle' => 'Heading2', 'format' => 'none', 'suffix'    => 'nothing', ),
         array( 'pStyle' => 'Heading3', 'format' => 'none',  'suffix'    => 'nothing', ),
      )
   )
);

This will trigger the display of number in the TOC, otherwise they will not appear, but without displaying automatic numbers.

If you want to use them, just change into:

array('pStyle' => 'Heading1', 'format' => 'decimal', 'text' => '%1'),
array('pStyle' => 'Heading2', 'format' => 'decimal', 'text' => '%1.%2'),
array('pStyle' => 'Heading3', 'format' => 'decimal', 'text' => '%1.%2.%3'),

Then you need to add “hNum” to your header’s style. Add:

'numStyle'   => 'hNum',

to the 2nd array of “$phpWord->addTitleStyle(…”.

The TOC work out of the box as in the official doc:

$toc = $section->addTOC();
$toc->setMinDepth( 1 );
$toc->setMaxDepth( 3 );

Conclusion

I hope that some of the issues that I run into while using PHPWord and that I described here has helped you to save countless hours.

I tried to think about other solutions to create an intermediate format (because the result needs to be manually edited before publishing) that can be converted into PDF, at the moment using PHPWord with DOCX seems the best option:

• no other libraries exists to create complex ODT or DOCX format;
• Scribus could be a possibile solution but its document format is not fully described on their wiki;
• LaTeX or Postscript are not something that normal user can edit;

So, here we are :)

About Antonio

I have got 30+ years experience in Open Source technologies. I am a Developer, Speaker and Trainer. Please check my Linkedin profile or https://antoniogallo.it

You can think of WordPress as blog engine that help non-technical peoples to design their own website without hassles using themes and plugin that are on the market.

But, there are also people like me, developers that hopefully know how to code, that love to customize it, to adapt it to the customer specific needs: to build quite amusing websites, not just blogs.

I’ve been through many WordPress themes in the latest years; i’ve learned the hard way that they may satisfy your urgent needs in the short time but in the long time they’re going to be hard to maintain.

Also, if you look at the source code of this themes you will panic. Almost 80–90% of the code is dedicated to support generic features that I will never need, or vendor’s marketing stuff (up-selling, cross-selling, newsletter, etc.) or, even worst, obfuscated code that will contain scary stuffs.

This also mean that your website is going to have a performance penalty due to the bigger source code, the many files the server has to read from the disks, the extra SQL queries that will slow down the database, etc.

Not to mention that all those themes and plugins inject extra CSS and JS files in your HTML page slowing down even more the overall loading time of the website when the customer browse it.

The “cure” that the market created is even more scary: more plugins! We now have plugins that introduce different kind of cache systems, that try to concatenate and minify CSS and JS files, etc. They are not strictly speaking a bad thing but I hope you understand that from my point of view its seems like curing a disease with the same disease.

So, the goals I tried to achieve developing my own theme engine are:

• remove all unwanted features from WP;
• provide, out-of-the-box, only a minimum viable product;
• allow to opt-in for any extra features;
• reduce CSS and JS at the minimum; avoid JQuery;
• provide built-in alternatives for the most common used plugins;

However, the main goal I wish to achieve, it is to have a common playground for all the projects and then just use a child theme to decide witch features to enable and witch do not. About this, my experience says that it is better to start with something simple and then just add, instead of trying to remove stuffs from a complex thing.

But lets see what I did in the past 10 days…

… its a very long list of self referential features, I know. But I did it to try explain you even better what are the features that I expect to have from WordPress and why commercial themes are not good for my own use case.

Unwanted Features

For speed, security and other motivations I worked hard to clean-up some unwanted features off from WordPress as much as possibile.

In the front-end area:

• cleaned up the HEAD tags from all the things not strictly required (feed links, rsd, wlw, generator, links, emojy, oEmbed, etc.);
• removed all the extra CSS (comment, default Gutenberg CSS, etc.) except the main style.css;
• blocked some XML RPC and pingbacks;
• removed the admin bar (it causes the loading of unwanted CSS e JS in the head); an “edit” link will appear in the bottom right corner of the page if you’re logged in;
• comments, breadcrumbs and post’s meta are hidden by default;
• the author’s archive and the attachment’s pages are disabled by default;

In the admin area:

• removed menus that are not needed;
• removed dashboard items that are not needed;
• hide the upgrade notice for non-admin users;
• custom TinyMCE button bars for the classic editor;
• removed some Gutenberg blocks that are not needed;
• all the default image sizes (thumbnail, medium, medium_large, large) are removed, only the “post-thumbnail” and the “full” size are left; its up to you to use add_size() to restore them or add new fancy image’s sizes.

MVP Features

Those are the main features that I wanted to be enabled by default inside the core theme engine.

In the front-end area:

• revisited loop — almost all the elements of the page template and the loop can be overridden by using a custom action or a template file;
• error handling — if anything bad happen then an HTTP 503 status is generated, this will prevent the search engine to index your page with error and they will return later;

header( 'HTTP/1.1 503 Service Temporarily Unavailable', true, 503 );
header( 'Retry-After: 3600' );

• site layout — you can choose the page layout from each different combination of the “content” plus 2 sidebars;
• lazy load CSS and JS — using bp_register_lazyload_style or bp_register_lazyload_script you can delay the loading of non-important files after the DOMContentLoaded event;
• headers and footer widgets — you can filter how many rows and cols of widgets you want in the header and footer: up to 3 rows and 4 columns, the widget’s content will adapt using flexbox CSS automatically; see this example:

bp_set_sidebars_header(2,2);
bp_set_sidebars_footer(2,2 );

• google fonts — by just adding the constant GOOGLE_FONT with the font’s url it will be lazy loaded and the meta tags for dns-prefetch and preconnect automatically generated;

<link rel="dns-prefetch" href="https://fonts.gstatic.com"/>
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin="anonymous"/>

• google analytics — by just adding the constant GOOGLE_ANALYTICS with the GA’s ID then a snipped for loading it will be automatically included and the meta tags for dns-prefetch will be added automatically generated;
• redirect url — by adding a custom field called external_url the user will be redirected to that url when accessing the content;
• responsive video — videos are wrapped by a div with a CSS class that will make them responsive;
• preload or include main CSS — the main style.css can be included directly in the HEAD or preloaded using the new rel=”preload” syntax;

<link rel='preload' id='framework-style-css'  href='/wp-content/themes/child/style.css' type='text/css' media='all'  as='style' onload='this.rel="stylesheet"' />
<noscript><link rel='stylesheet' id='framework-style-css'  href='/wp-content/themes/child/style.css' type='text/css' media='all' /></noscript>

• archive page with content and grid style — an archive’s page will try to look as a normal page using the title and the description as content; the elements in the loop can be styled using pre-built grid CSS rules;

.wrap {
   display: grid;
   grid-template-columns: 2fr 1fr;
   grid-template-rows: auto 1fr;
}

.entry-title {
   grid-area: 1 / 1 / 2 / 2;
   padding-right: .5rem;
}

.entry-image {
   grid-area: 1 / 2 / 3 / 3;
}

.entry-summary {
   grid-area: 2 / 1 / 3 / 2;
   padding-right: .5rem;
}

In the admin area:

• support for custom logo, header and backgrounds using a widget or via the customizer;
• support for Gutenberg’s special align style: left, wide and full;
• custom login page — the login page will use the website’s own logo and will link to the homepage’s url instead of wordpress.com;
• media page — will display the info about the media dimensions;
• pages admin — a column with the featured image will be displayed and also another column with the “order” value; pages will be sorted automatically using the “order” column; in the page editor you will aso be able to edit “excerpt” and “tags” like posts;

• posts admin — will have an extra column with the featured image;
• image sizes selector — if you add custom size via add_image() you’ll be able to select them where appropriate;
• PDF overwrite — when uploading a new PDF file it will override the old one, with the same filename, instead of creating a new version;
• maximum image upload — when uploading a large image it will be automatically reduced to the default size of 1920 pixel;

Extra Features

There are more features available beside the one i mentioned above. Those are not included by default but can be automatically loaded via a filter or by calling “bp_$type_require(…)”.

Those are organized in different categories:

• lib & class — library that contains functions (or classes) that can be used by some extra features but not required inside the core;
• shortcode, metabox, widget, custom-types— typical WordPress ecosystem elements;
• feature — those files contains lots of action hooks, filters and recall other stuffs to achieve complex features;

Every category has its own special filter, or function, that a child theme can use to include or exclude them.

bp_add_features( array(
   'nav-menu-walker',
   'excerpt-readmore',
   'comments',
   'breadcrumbs',
   'child-pages',
   'social-share',
   'related-post',
   'genesis-navigation',
   'comments-open',
   'admin-page-sort-order'
) );

add_filter( 'bpf_preload_metaboxes', function ( $list ) {
   $list[] = 'subtitle';
   return $list;
} );

From all the once i developed i think its worth to mention those one:

• metabox and widget class helpers — those will help to create metaboxes and widgets easily: all the component I built uses those classes;

<?php
require_once BP_THEME_DIR . '/class/metabox.php';
require_once BP_THEME_DIR . '/class/field/textfield.php';
require_once BP_THEME_DIR . '/class/field/textareafield.php';
require_once BP_THEME_DIR . '/class/field/checkboxfield.php';


class BadPenguinSeoMetaBox extends BP_Class_MetaBox {

   protected $mb_context = 'side';

   function __construct() {
      parent::__construct( 'badpenguin_seo_metabox', 'SEO' );
   }

   protected function setup() {
      parent::setup();

      $this->addField( 'BadPenguinTextField', 'seo_title' )->setLabel( 'Title' )->setAttribute( 'size', 80 );
           

      $this->addField( 'BadPenguinTextareaField', 'seo_description' )->setLabel( 'DescriptionTitle' )->setAttribute( 'rows', 2 );

      $this->addField( 'BadPenguinCheckboxField', 'seo_robots_noindex' )->setLabel( 'Disable robots' )->setContent( 'Hide from google search engine' );
   }

}

// Bootstrap
new BadPenguinSeoMetaBox();

• navbar widget — allow to create a complete navbar with logo and mobile menù support (hambuger buttom + overlay menù) that works in pure CSS without JS;

• template shortcode — allow you to include any HTML template from the directory “parts”; if used programmatically via bp_get_template_part() (that replaces get_template_part) you can pass additional parameters to the template that can be reused inside of it;
• child pages — if a page has a hierarchy with children then, at the end of its content, a menù will appear with all of them; it can be used automatically or via a shortcode;
• embed github’s gists;
• genesis navigation next/prev — inspired by a plugin for genesis, this will add two big arrows at the center of the screen to navigate to the next or previous content; if you don’t like it there is another simpler version that will display the two links at the end of the content;
• medium content — if enabled, it will try mimic the aspect of a medium.com post. I’ve already developed a test example in past before this one: https://github.com/badpenguin/mimic-medium-typography ;
• page cover — the featured image will appear covering the whole viewport of the browser with title and subtitle, this is another extra metabox that will create a custom field that you can use to display it below the title;

• copyright — will block copy, right click and drag’n’drop of images since them are protected by copyright;

CSS Management

Having a light CSS is critical. I’ve used many CSS’s frameworks in the past since the born of the 12-columns grid systems: Twitter Bootstrap up to version 4, Foundation 4 and 5, UiKit (my favourite, check it at https://getuikit.com/ ); just to mentions only the most famous.

For those CSS frameworks the same problem I mentioned above about the WordPress commercial themes is still valid: they are huge because they need to support general purpose features.

They are no less then 70KB without counting their javascript dependency counterparts.

To avoid this I gathered all my SASS snippets and created my own customizable set of CSS rules: https://github.com/badpenguin/vanilla-css

The resulting style.css of my first website that I developed with my own custom theme was so little, 9KB (theme style + vanilla CSS), that I decided to include style.css directly in the HEAD of the page.

So, my theme’s main style.css is generated by style.scss that has some custom SASS and also include “some” of the feature from Vanilla’s CSS.

And if you develop a child theme its easier to include it via SASS directly and sets the SASS variables to customize colors and other stuffs.

JS without JQuery

The same as CSS is replicated on the javascript side. The first goal is to avoid JQuery and this is done by simple unregistering it and avoiding any script that will use it as dependency.

I developed https://github.com/badpenguin/vanilla-js to implement at least a minimal lightbox feature for gallery or single images. It has a core.js mandatory script with some DOM utilities that I use then the rest is totally optional.

Built-in plugins

So, using both Vanilla CSS and Vanilla JS i created custom features that try to resemble the core functionalities of some of the most common plugins that I’m forced to use:

• SEO by Yoast
• Image Watermark
• Lightbox
• Custom Related Post
• WP Social Sharing

and more.

SEO Functionalities

A SEO metabox will appear in the left Gutenberg ‘s sidebar. Here you can specify a custom title, description or a checkbox for disabling robots for that page.

Indexing is automatically disabled by default for attachments, tags and any other archive’s page except categories. You can use a filter to customize it.

If a featured image is present then the minimum Open Graph’s meta tags for Twitter, Facebook and Pinterest will be generated.

You an see the source code used to generate the above metabox in the previous chapter where i was talking about “lib and classes”.

Watermark Functionalities

Inspired by “Image Watermark”, this is a very simple plugin that can generate image with a text watermark, customizable using a filter. The original image is back-upped so it can be restored if you want to remove the watermark. Images that are too small (usually below 640 pixel) will not be watermarked by default.

Gallery Functionality

I’ve created a simple lightbox that will open a modal and navigate through one or more image depending on your configuration. There are arrows and a close button to click or you can navigate with the keyboard or swiping. A simple cross fade animation is used to change the slide.

You can see it in action here: https://visitaretenerife.it/quando-andare-a-tenerife/

Lazy Load Image Functionality

Every image in the site’s content and in the footer will be configured automatically. This plugin renames the src and a srcset attribute of the images to prevent the browser from loading them. Then, using a javascript intersectionObservable, the images will be lazy loaded. When entering the viewport the initial src and srcset will be restored and the image will appear.

With website with long content and lots of larges images this will speed up greatly the initial load of the page.

TOC — Table of Content

This is another typical situation where you can use 40 lines of code instead of big complex plugins. I use a shortcode to place the TOC in the preferred position, usually after a few paragraph in a big page with multiple headers, and it will automatically create named anchor for every H2 and H3 headers and create an UL > LI list with the index.

Other plugins

And in the end i replaced other classic plugins:

• related post — it just calculate the best 3 related posts and display them using a grid;
• social share — add a CSS-only sharebox that will link the most common social sharing urls: Facebook, Twitter, Pinterest, Linkedin; no javascript is used; no counter; no fuzzy.

Closing Words

While looking back at this post I got a little scared about how much work I did in the latest 10 days during my free time.

I really hope that I’ve finally got the ultimate swiss-knife for all my projects that are based on WordPress. I trust that the “on demand” API I’ve developed will help me to maintain all the projects with a single code base where, with just a small child theme, I can decided what to include and what not.

At this time, July 2019, I plan to built 3 more websites in the next 2 months with this theme framework before to release the source code on github. I wish to clean up and polish it a little before to release it to the public.

You will no wonder that the temporary name I’m using for it is “Vanilla WP”, just to continue the “Vanilla” saga of KISS projects.

So, please, stay tuned and remember my motto: “More Hard More Fun”.

About Antonio

I have got 30+ years experience in Open Source technologies. I am a Developer, Speaker and Trainer. Please check my Linkedin profile or https://antoniogallo.it

As i am every day more engaged in React development i took the chance to rewrite my personal website with Next.Js.

I want reusable React’s components everywhere

My goal is to have a common layer of React components to be used in multiple situations:

• Cordova Hybrid Mobile Application
• Progressive Web Application — PWA
• Classic SPA
• Portal with Server Side Rendering (SSR)though a custom CRM
• Static Web Site generated through a Headless CRM
• Landing Pages and other small static web site

It happens often that a customer may ask me to develop one or more of this project. So, its important to me, to reuse the same branded UI components and not just the business logic, through all of them.

The “pros” of Next.JS

I choosed Next.Js because it can be used for both SSR and also as Static Generator. It covers all my “use cases” where a simple Webpack config alone is not enough.

However it has been a little tricky to adapt it to generate Landing pages.

Next.Js is great in providing a smooth user experience for an SSR website but the cost of this its a certain amount of JS and CSS files to be loaded, and preloaded, at the first visit.

The “cons” of Next.JS

If you have one big single homepage or a landing page, then you are not interested in the preloading stuffs. You just want to “convert” the user and your focus is in making a better page.

This includes:

• optimizing CSS for rendering “above the fold” content as fast as possible;
• minimize the number of HTTP requests;
• lazy-load images and other assets;

DISCLAIMER

As going now into technical details, config files and source code then I assume that you already know or you have used Next.Js, so i will only explain the relevant parts below.

Configuring Next.JS for Typescript and SASS

If you want to use Typescript (.tsx files) and SASS (.scss file) you can do this by install a few Next.Js “plugins”.

Next.js has a config file, next.config.js, that can be used to install plugins and customize the webpack’s config.

So my initial next.config.js looks like this:

const withPlugins = require("next-compose-plugins");
const withTypescript = require('@zeit/next-typescript');
const withSass = require('@zeit/next-sass');

module.exports = withPlugins(
   [
      withTypescript,
      withSass
   ],
   { /* nextConfig options here */ }
);

You can find here https://github.com/zeit/next-plugins more plugins to install and documentation of the one used above.

With those two installed then I can create my homepage as index.tsx and my SASS file as style.scss.

Copying static web assets into the webserver root

Next.js has a “static” directory that allow you to have all the files stored there copied inside the build directory and available, once deployed to a webserver, with the url prefix “/static/”

But if you need to copy robots.txt, .htaccess and other files into the root of the webserver some trick is required.

In next.config.js we can add an option, in the nextConfig object, to hook the exportPathMap function and use that one to recursively copy the files stored in a directory choosed by us into the build directory.

This is the code i used:

const recursiveCopy = require('recursive-copy');

module.exports = withPlugins( [ ... ], 
{
exportPathMap: async function (defaultPathMap, {dev, dir, outDir, distDir, buildId}) {
   await recursiveCopy(join(dir, 'src/htdocs/'), outDir, {dot:true});
   return defaultPathMap
},

Basically, this will copy all the files, including the one starting with a dot, from “src/htdocs/” into the final build directory.

How to customize the Webpack’s config

Again, in next.config.js we can add another callback to the nextConfig object, but this time to change directly the webpack’s config adding new features.

Indeed, Next.Js does not minify CSS files out of the box, so i’ve added the OptimizeCSSAssetsPlugin plugin to the its configuration.

Also i don’t want the JS and CSS splitted in multiple chunks of files because i’ve only a single page: there is no point in making multiple HTTP requests; so i’ve added the LimitChunkCountPlugin plugin to achieve this goal.

This is what i did:

const webpack = require('webpack');
const OptimizeCSSAssetsPlugin = require("optimize-css-assets-webpack-plugin");

module.exports = withPlugins( [...],
   {

      webpack: (config, {dev, isServer}) => {

         if (isServer) {
            return config;
         }

         var isProduction = config.mode === 'production';

         if (!isProduction) {
            return config;
         }

         config.plugins.push(
            new webpack.optimize.LimitChunkCountPlugin({
               maxChunks: 1,
            })
         );

         config.optimization.minimizer.push(
            new OptimizeCSSAssetsPlugin({})
         );

         return config
      }
   }
);

Well, as you see above, we have this webpack funcion that gots called twice. This because Next.Js builds both server code and client code.

I am only interested in tweaking the config for the client when running in production mode, so i just skip the settings if the conditions are not met.

Finally i added the two plugins, mentioned above, to the plugin list and into the new Webpack’s version 4 minimizer config.

How to reduce the number of HTTP requests

Ok what’s left now? When i load my homepage in production it loads a CSS files, 3 JS files in the footer and it also preloads a bunch of JS files.

I want to do 3 things now:

• stop preloading JS code for navigation because i’ve a single page;
• load the CSS directly in the head, to save an HTTP request;
• skip including those JS files because i don’t have React code on the client side and i want everything pre-rendered at server side anyway — in this case;

Next.Js does not have a simple way to do this, we have to extend and modify the behavior of the builtin Head components.

Together with the pages in the pages directory i’ve a _document.js file. This file is used to create a custom layout, overriding the default one, and adding extra vanilla Javascript.

This is a reduced version of the one i use:

import Document, {Main, NextScript} from 'next/document';
import InlineStylesHead from "../src/components/InlineStylesHead";

export default class CustomDocument extends Document {

   setFooterTags() {
      return {
         __html: `
var WebFontConfig = {
   google: {families: [ 'Fjalla+One|Open+Sans:400,500,700' ]}
};
/* ... omissis ...  */
      `
      };
   }

   render() {
      return (
         <html lang="it">
         <InlineStylesHead/>
         <body>
         <Main/>
         {false && (<NextScript/>)}
         <script dangerouslySetInnerHTML={this.setFooterTags()}/>
         </body>
         </html>
      )
   }
}

This override the default Next.Js document in a few parts:

• First — the dangerouslySetInnerHTML attribute is used to render plain javascript code, used for lazy loading webfonts, google analytics and other stuffs;
• Second — the NextScript component is commented out, so the 3 JS files in the footer will not be included in the final output;
• Thirth — the default Head component from next/head is replaced by a custom version that extend and override functionality of the original, its called InlineStylesHead and it will stop the output of the JS preload code and it will also include the CSS directly in the html instead of a separate file

And in the end the final results is:

And the audit results looks good too:

What’s Next?

Well there is more to do.

Next step for sure will be to add a plugin to manage the optimization of the images from the static directory (actually are not optimized).

Probably i wish also to test if serving the fonts locally instead that from google server will make the rendering even faster or not.

I also want to try that if lazy loading all the images that are not strictly required above the fold or by the SEO has some benefits.

Do you want more?

Next.Js is not alone. Beside Gatsby there are a few more project to look into for inspieration or to build a React ecosystem above of it: preact-cli and prerender-loader

Show me the Source

You’ll find a working config with 2 test pages and some bonus component here:

https://github.com/badpenguin/nextjs-static-generator-boilerplate

About Me

I have got 30+ years experience in Open Source technologies. In the latest years, I had become in love with React and mobile development. Please check my Linkedin profile or personal website or Linux blog.

In August 2018 I had time to focus a lot on doing some self-marketing. I ended up doing a lot of quotes about developing React Native mobile Apps.

Usually, I just work using my personal network: word of mouth has always worked good for me, but I love to develop Apps and I wanted another App project as quickly as possible.

I’ve been asked to sign an NDA on 100% of those quotes :-(

Don’t get me wrong: I’m currently under NDA with 2 of my best customers and I also have signed some more in the past so, that has never been a problem to me but, in the long term, I’m starting to see that’s not paying off.

1. First of all, there is no value for me into it: I’ve to pay a huge fee if I reveal any info but in exchange I get nothing;
2. Often I can’t get credits for my work: I can’t tell others that I’m working for a customer or on a project; my portfolio currently lacks some of the best projects I worked for and also cannot mention the customer’s logo/name on my website;
3. Some NDA have a very long duration, sometimes several years;
4. Its a waste of time to read it every time and sometimes I’ve to translate them from English for my lawyer;
5. I’ve always acted as much as professional as I could in my career: if you don’t trust my word than probably you should try to know me well;

Isn’t that a little too much for a simple quote?

Probably I’m a little nostalgic but gentlemen word still means a lot to me. I know there is a lot of people out there ruining the market but that’s not my case.

If you want me to provide some proof of something then “just ask”… except to sign that paper: I will not.

I strongly believe:

1% of the success of a company is your idea, 99% is execution — Tyler McIntyre

and I’m here to provide the best execution as I can.

About Antonio

I have got 30+ years experience in Open Source technologies. In the latest years, I had become in love with mobile development. Please check my Linkedin profile or https://antoniogallo.it

Reference

• https://medium.com/startup-frontier/why-i-wont-sign-an-nda-4193aeda7251
• https://medium.com/startup-grind/ndas-are-for-losers-31dae14e7a92
• https://medium.com/@kpfrahm/how-to-react-if-someone-with-a-startup-idea-wants-you-to-sign-an-nda-97bf9d2335a3
• https://medium.com/@sebastian212000/nda-for-your-idea-how-about-lol-5d1a7329652e
• https://medium.com/@mboezi/a-better-use-of-your-time-than-ndas-9f97fb24b014