ramigs.dev

How to setup Python for local development on macOS

Sat, 29 Aug 2026 00:00:00 GMT

If you’re coming from a Node.js background, Python’s tooling has historically felt scattered, pip, venv, pyenv, requirements.txt, each solving one piece of the puzzle. In 2026, that’s consolidated around uv, a single Rust-based tool from Astral that replaces most of the old stack. This post walks through setting up a clean Python dev environment on macOS with uv + VSCode.

Why uv?

If you know Node, here’s the rough mapping:

pyenv ≈ nvm (Python version management)
venv ≈ node_modules (per-project dependency isolation)
pip ≈ npm (package installer)

uv consolidates all three into one fast binary, closer to how npm just handles everything without you thinking about it. It auto-detects the Python version per project and manages the virtual environment for you, so you never have to activate anything manually.

1. Install uv

Via Homebrew:

brew install uv

Or via the official install script:

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify it worked:

uv --version

2. Create a new project

uv can scaffold the folder for you:

uv init my-project
cd my-project

This generates pyproject.toml, .python-version, a src/ layout, .gitignore, and initializes git, all in one step.

3. Run the project

uv run <project-name>

uv automatically creates the .venv, installs dependencies, and picks the right Python version, without you having to activate anything manually. You can also drop into a REPL scoped to the project’s environment:

uv run python

4. Set up VSCode

Install these extensions:

Python (Microsoft) — core language support, IntelliSense
Python Debugger (Microsoft) — usually installs automatically alongside Python
Python Environments (Microsoft) — usually installs automatically alongside Python, unifies environment discovery across venv, uv, conda, etc.
Ruff — fast linting and formatting

Then make sure VSCode is pointing at the right interpreter:

Cmd+Shift+P → Python: Select Interpreter
Choose ./.venv/bin/python
Confirm it shows in the bottom-right status bar

5. Configure Ruff as your formatter

Add to your user settings.json (applies to every project by default):

{
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

Test it by writing deliberately messy code and saving. Ruff should auto-format it, and unused imports should get flagged by both Ruff and Pylance.

Wrap-up

With this setup, a new Python project goes from zero to running, linted, formatted, and debuggable in VSCode in just a few minutes, without juggling pyenv, pip, and venv separately. The workflow will feel familiar if you’re used to npm:

uv init ≈ npm init
uv add ≈ npm install
uv run ≈ npm run

Building a small MCP server to learn the protocol hands-on

Thu, 20 Aug 2026 00:00:00 GMT

After writing about what MCP actually is, the obvious next step was building one. payments-toolkit-mcp is a small MCP server that exposes payment-data validation as MCP tools: Luhn checksum validation, card network detection, and IBAN validation. It also exposes a static resource listing supported card networks and their prefix ranges.

Composition, not configuration

The whole server is built from the official @modelcontextprotocol/sdk, and src/index.ts is just composition. It creates a server, registers each capability, and connects a transport:

const server = new McpServer({
  name: 'payments-toolkit-mcp',
  version: '1.0.0',
});

registerValidateCardNumberTool(server);
registerDetectCardTypeTool(server);
registerValidateIbanTool(server);
registerCardNetworksResource(server);

const transport = new StdioServerTransport();
await server.connect(transport);

Each tool lives in its own file under src/tools/, and each one only knows how to register itself onto a server it’s handed. It doesn’t own the server or the transport. The validation logic itself (isValidLuhn, the IBAN mod-97 check, the IIN/BIN prefix table) lives in src/lib/, completely unaware that MCP exists. That split made the MCP-specific code trivial to write, since it’s never more than a schema and a thin wrapper around a function that already works and is easy to test on its own.

A tool is a schema plus a handler

Registering a tool means giving it a name, a Zod input/output schema, and a handler:

server.registerTool(
  'validate_card_number',
  {
    title: 'Validate Card Number',
    description:
      'Checks whether a card number passes the Luhn checksum algorithm. ' +
      'Accepts digits only (spaces/dashes should be stripped by the caller).',
    inputSchema: { cardNumber: cardNumberSchema },
    outputSchema: { valid: z.boolean() },
  },
  async ({ cardNumber }) => {
    const valid = isValidLuhn(cardNumber);
    return {
      content: [{ type: 'text', text: JSON.stringify({ valid }) }],
      structuredContent: { valid },
    };
  },
);

The model reads description to decide whether to call the tool. The input schema does its own filtering: cardNumberSchema enforces digits-only and a sane length range, so malformed input never reaches isValidLuhn in the first place.

The two-shape response (content and structuredContent) surprised me initially. content is the older, universal shape: a list of blocks a client can render regardless of what it understands. structuredContent is the newer, typed one, matched against outputSchema so a client can consume it programmatically instead of parsing text. Returning both is redundant on paper, but it’s what keeps the tool usable by clients that only implement one side.

Resources are the read-only counterpart

Tools are actions; resources are just data a client can fetch by URI. The one resource here, card_networks, is a static JSON table of card networks and their prefix ranges. It’s the same table detect_card_type matches against internally, exposed separately so a client can read it directly instead of inferring it from tool calls:

server.registerResource(
  'card_networks',
  'payments-toolkit://card-networks',
  {
    title: 'Card Networks',
    description:
      'Supported card networks and the IIN/BIN prefix ranges used to identify them.',
    mimeType: 'application/json',
  },
  async (uri) => ({
    contents: [
      {
        uri: uri.href,
        mimeType: 'application/json',
        text: JSON.stringify(data, null, 2),
      },
    ],
  }),
);

Custom URI scheme (payments-toolkit://...), a MIME type, and a handler that returns contents. It’s structurally almost identical to a tool registration, which made resources feel like a small addition once tools already clicked rather than a separate concept to learn.

Prompts are the user-invoked primitive

Tools and resources cover two of MCP’s three primitives. The third is a prompt: a reusable template the server hands the client instead of the client writing it per integration. The one prompt here, check_payment_details, takes optional cardNumber/iban arguments and returns a message telling the model which tools to call and how to format the summary. The server never calls the tools itself, it just hands back text:

server.registerPrompt(
  'check_payment_details',
  {
    title: 'Check Payment Details',
    description:
      'Validates a card number and/or IBAN using the available tools and ' +
      'reports the results in a standard summary format.',
    argsSchema: {
      cardNumber: z.string().optional().describe('Card number to validate'),
      iban: z.string().optional().describe('IBAN to validate'),
    },
  },
  ({ cardNumber, iban }) => ({
    messages: [{ role: 'user', content: { type: 'text', text: /* ... */ } }],
  }),
);

argsSchema is a flat shape of strings only, not arbitrary Zod like a tool’s inputSchema. The MCP spec has clients render prompt arguments as plain text fields. That restriction lines up with how prompts get invoked: not chosen by the model like a tool, but triggered explicitly by the user, surfaced as a slash command in Claude Code (/mcp__payments-toolkit-mcp__check_payment_details).

The gotcha: stdout is not yours

This is the one mistake the README specifically calls out, and it’s the kind of thing you’d only discover by hitting it: over the stdio transport, stdout is the JSON-RPC wire. A stray console.log doesn’t just clutter logs; it injects malformed data into the protocol stream and breaks the client’s parser. Every bit of debug output in this server goes through console.error instead, since stderr is left alone. This explains why MCP server boilerplate almost always reaches for a logger or console.error by convention rather than console.log.

Inspecting and connecting

@modelcontextprotocol/inspector gives a local web UI to call tools and read resources directly, without wiring up a client first. That’s useful for confirming schemas and responses actually round-trip before pointing a real host at the server. Once that works, connecting it to Claude Code is a single command:

claude mcp add payments-toolkit-mcp -- node /path/to/payments-toolkit-mcp/dist/index.js

/mcp inside a session then confirms the connection: seeing payments-toolkit-mcp · ✔ connected means the handshake worked and the tools were discovered. That registration defaults to local scope, tied to the project directory claude mcp add was run from, so a different project needs its own claude mcp add (or --scope user to make the server available everywhere).

Adding the HTTP transport

Stdio only works because Claude Code spawns the server itself and owns the subprocess. A server meant to be shared across multiple clients needs to run over HTTP instead, via StreamableHTTPServerTransport. Supporting both meant splitting index.ts: tool/resource registration moved into a createServer() factory, and each transport got its own module, picked at startup by a --http flag.

The part that isn’t obvious going in: an McpServer can only be connect()-ed to one transport, so serving multiple HTTP clients from one long-running process means a fresh McpServer + StreamableHTTPServerTransport pair per session, created on the initialize request and keyed by the Mcp-Session-Id header on every request after that:

if (!transport) {
  if (!isInitializeRequest(req.body)) {
    res.status(400).json({/* ... */});
    return;
  }
  transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => randomUUID(),
    onsessioninitialized: (newSessionId) => {
      transports.set(newSessionId, transport!);
    },
  });
  const server = createServer();
  await server.connect(transport);
}

Requests without a session ID that aren’t initialize get a 400.

[TIL] diagram-design

Thu, 20 Aug 2026 00:00:00 GMT

TIL about diagram-design, a Claude Code plugin (also works with Codex, Factory Droid, and Pi) that bundles an agent skill for generating diagrams — architecture, flowcharts, sequences, Gantt charts, and dozens of other types — as self-contained HTML and SVG files.

The problem it solves is one I’ve run into before: ask an AI assistant for a diagram and you get back a generic rounded-box-and-arrow illustration that looks nothing like anything else on the page it’s meant to sit in. diagram-design fixes that by onboarding your site’s actual design tokens — colors, typography, spacing — in about a minute, then using them for every diagram it generates afterward. The output is plain HTML with embedded SVG: no build step, no external dependencies, and it exports cleanly to PNG or SVG when you just need the image.

The architecture diagram in today’s MCP post is a good showcase of what it can do — same fonts, same color tokens as the rest of this site, not a generic diagram pasted in from somewhere else:

What is the Model Context Protocol (MCP)?

Thu, 20 Aug 2026 00:00:00 GMT

MCP (Model Context Protocol) standardizes how an AI model reaches outside itself — to a database, an API, a filesystem, whatever. Before it, every integration was bespoke: a custom tool definition and glue code per app, per model, per data source. MCP replaces that with one protocol both sides implement once. The usual analogy is USB-C: everyone agreeing on the same connector is what makes it useful.

Host, client, server

MCP defines three roles:

Host — the AI application itself: Claude, an IDE, an agent. It embeds the model and decides when to reach outside it.
Client — lives inside the host, one per server. It speaks MCP on one side and hands results back to the model on the other.
Server — a small process that exposes capabilities over MCP: tools to call, resources to read, prompts to reuse.

Each client maintains a single, dedicated connection to exactly one server. Want to talk to both a database and GitHub, that’s two clients running side by side inside the same host — not one client juggling two connections.

Two transports

MCP doesn’t care whether the server is a process on your machine or an API across the network — the same request/response shape works either way. What changes is the transport underneath:

stdio — for a server running locally. The host spawns it as a subprocess and talks over its stdin/stdout. No network involved, so it’s the default for anything reading local files or hitting a local database.
Streamable HTTP — for a remote server. The client POSTs JSON-RPC requests to a single MCP endpoint; the server can respond directly or upgrade that same connection to a Server-Sent Events stream when it needs to push multiple messages back. This is what a hosted, shared MCP server (GitHub’s, for example) uses today.

It wasn’t always one endpoint. The original transport — HTTP+SSE — split the two directions across separate endpoints: the client POSTed to one URL, and a server-initiated GET on a second URL opened the SSE stream for everything coming back. The spec deprecated that split in favor of Streamable HTTP’s single endpoint back in March 2025, though some older servers still speak it for backwards compatibility.

What a server actually exposes

Every server advertises the same three primitive types, regardless of transport:

Tools — functions the model can invoke (create_issue, run_query).
Resources — data it can read (a file, a row, a config value).
Prompts — reusable prompt templates the server hands the host, rather than the host hand-rolling them per integration.

That fixed vocabulary is what makes MCP a protocol rather than just a convention: a client doesn’t need to know anything about a server ahead of time beyond “speak MCP” — it discovers what’s actually on offer at connection time.

How online card payments actually work

Mon, 17 Aug 2026 00:00:00 GMT

Tapping “pay” looks instant from the checkout page, but it kicks off a chain of handoffs between the merchant, a payment provider, an acquiring bank, a card network, and an issuing bank — most of it happening before any money actually moves. Here’s the flow broken into its logical steps.

1. Card data capture

The customer enters card details (PAN, expiry, CVV) on the merchant’s site. To avoid full PCI DSS scope, this is usually done via hosted fields/iframes or an SDK so raw card data never touches the merchant’s own servers.

2. Tokenization

The card data is sent directly from the browser/app to the payment provider or a tokenization vault, which returns a token (or sometimes a “network token” issued by Visa/Mastercard directly) representing the card. The merchant stores/uses this token instead of the PAN going forward.

3. 3D Secure (3DS) authentication

Before authorization (or sometimes as part of it), the transaction may go through 3DS:

Device fingerprinting / risk data collection — browser/device data is silently collected first.
Risk-based decision (frictionless vs. challenge) — the issuer’s ACS (Access Control Server) decides, based on risk scoring and exemption rules (e.g. PSD2 SCA exemptions), whether to challenge the customer.
Challenge flow (if triggered) — customer verifies via OTP, banking app push notification, biometrics, etc.
Authentication result — a cryptographic proof (CAVV) and ECI value are returned, which shifts liability for fraud from merchant to issuer if successful.

4. Authorization

The transaction (token + 3DS result, if any) is sent to the acquirer, which routes it through the card network (Visa/Mastercard/etc.) to the issuing bank. The issuer checks funds/credit limit, fraud signals, and approves or declines. This step returns an authorization code and reserves the funds — but doesn’t move money yet.

5. Capture

The merchant “captures” the authorized amount — sometimes immediately (common for e-commerce), sometimes later (common for things like hotel bookings or shipping-dependent orders). Capture can also be partial.

6. Clearing & settlement

Batches of captured transactions are sent from acquirer to card network to issuer for clearing. Funds actually move between banks here — this is where the merchant’s bank account gets credited, typically 1-3 business days later depending on the processor.

7. Reconciliation

The merchant matches transactions, fees, and payouts against their own order records — often surfaced via webhooks/reports from the payment provider (settlement reports, fee breakdowns, chargebacks, refunds).

How much of this you actually build

Which of these steps a merchant implements directly — versus just calls into — depends heavily on the integration style:

Hosted/redirect checkout (e.g. Stripe Checkout, PayPal redirect) — almost the entire flow is abstracted away. The merchant redirects the customer out and gets a webhook back with a pass/fail result, with no visibility into tokenization, 3DS UX, or network routing.
SDK/Elements-based (e.g. Stripe Elements, Adyen Components, Braintree Drop-in) — the common middle ground. Card capture is embedded via hosted fields, and tokenization plus 3DS are triggered by a single SDK call that handles the challenge modal internally. The merchant orchestrates when things happen, not how. Capture is usually the one step still in the merchant’s hands directly — auto-capture vs. a separate API call made later.
Direct/custom integration (e.g. an API-only acquirer integration, or a direct 3DS Server implementation) — the merchant implements each step itself, potentially handling raw card data (full PCI DSS scope) and building its own 3DS challenge flow against the EMV 3DS spec. More control, but real compliance and engineering burden shifts onto the merchant.

Reconciliation (step 7) stays on the merchant regardless of tier — it’s inherently about matching provider data against internal order records. Clearing and settlement (step 6), on the other hand, are never something a merchant implements; that happens entirely between acquirer, network, and issuer.

Additional flows layered on top

Refunds — reverse part or all of a captured transaction, processed similarly through acquirer → network → issuer.
Chargebacks/disputes — issuer-initiated reversal when a cardholder disputes a charge, with a defined evidence/response window for the merchant.
Webhooks/async notifications — most providers notify the merchant asynchronously for state changes, which matters most for redirect-based 3DS challenges or delayed authorization methods.

[TIL] Local Overrides in Chromium DevTools

Mon, 10 Aug 2026 00:00:00 GMT

TIL about Local Overrides in Chromium-based DevTools.

What it is

A feature that lets you make persistent edits to a website’s files — HTML, CSS, JS, images, even network responses — directly in DevTools, and have those edits survive page reloads, without actually changing anything on the server.

Why it’s useful

Test CSS/JS tweaks against a live or staged site without touching source code or a build pipeline
Debug production issues by patching a minified file and confirming a fix works before committing it
Mock API responses by overriding XHR/fetch requests — handy for edge cases or working around a backend that isn’t ready yet
Changes persist across reloads, unlike ordinary Elements-panel edits which reset on refresh
Good for quick client demos or prototyping tweaks on a live site

How to set it up

Open DevTools and go to the Sources panel
Open the Overrides tab in the sidebar
Click “Select folder for overrides” and pick a local folder
Click Allow when DevTools asks for permission to read/write it
Edit a file directly in the Sources panel (or CSS in the Styles pane, if that CSS lives in an actual .css file) — DevTools saves the change into your chosen folder automatically
A small purple dot marks files with an active override; review them anytime from the Overrides tab. Uncheck Enable Local Overrides to temporarily disable them, or click Clear to delete all override files for good

You can also kick this off from the Network panel: right-click any request and choose “Override content” or “Override headers” — useful for mocking a specific API response or patching response headers (e.g. CORS) without hunting for the file in Sources first.

Caveats

Elements-panel edits don’t count. Editing the DOM via “Edit as HTML” in the Elements panel is not saved as an override — DevTools explicitly doesn’t track DOM tree changes there. Overrides only capture edits made in the Sources panel, or CSS edits in the Styles pane when the CSS comes from an external stylesheet (not inline in the HTML).
DevTools has to stay open. The override only serves while DevTools is attached to that tab — close it, and the next load falls back to the real file from the server.

Overrides are scoped per-origin, so once set up, they keep applying to that site (while DevTools is open) until you clear them or uncheck Enable Local Overrides.

What are micro-frontends?

Mon, 10 Aug 2026 00:00:00 GMT

A single frontend codebase works fine until several teams need to ship to the same product surface at the same time. Past that point, everyone is merging into the same build, one team’s broken deploy blocks everyone else’s release, and the app keeps growing in a direction no single team fully owns anymore.

Micro-frontends are one answer to that problem.

What a micro-frontend actually is

A micro-frontend architecture splits the UI into independently built and independently deployed pieces, each usually owned by a different team, then composes them into one cohesive app for the end user.

Think of it like a food court: independent vendors, each running their own stand, their own staff, their own hours — but customers walk through one entrance and experience it as a single food court. A vendor can swap in or out without the building itself changing, which is close to what happens when pieces are composed live, in the browser, at runtime.

How the pieces come together

Composition can happen at build time (stitched together before it ships) or at runtime (assembled live, in the browser). Runtime composition is the more common approach today, and it’s largely practical thanks to Module Federation — originally a Webpack feature, now also available in Vite through plugins — a mechanism that lets independently built bundles load and share code from each other in the browser, without a shared build step.

That’s worth separating clearly: micro-frontend is the architectural pattern; Module Federation is one tool that makes that pattern easier to pull off. The pattern itself doesn’t require it — iframes and web components are older, simpler ways to achieve the same composition, just with different tradeoffs.

What you gain

Independent deploys. Each team ships on its own schedule, without coordinating a shared release.
Stack freedom. Each piece can, in principle, use its own framework or version, decoupled from what everyone else is running.
Smaller blast radius. A bad deploy from one team affects its own piece, not the whole app.

What it costs

Version drift. Host and remote pieces can disagree on shared dependencies if versions aren’t coordinated.
Duplicated weight. Without careful sharing, the same dependency can ship multiple times across pieces, bloating what the user downloads.
UX consistency gets harder. Independently built pieces can drift apart in look and feel without deliberate effort to keep them aligned.
More moving parts. Multiple pipelines, multiple deploy targets, and more coordination overhead than a single codebase ever needed.

Is it worth it?

Only once the problem it solves actually exists. If one team already owns the whole frontend, none of the coordination pain above is happening yet — so there’s nothing to gain and only the costs to pay. Micro-frontends earn their keep at the point where multiple teams shipping to the same app has become the actual bottleneck, not before.

Takeaway

A micro-frontend isn’t a tool or a library — it’s an architectural choice to trade a simpler codebase for independent team ownership and release cadence. Module Federation is one of the mechanisms that makes that trade practical, not the thing itself. Whether it’s worth making comes down to one question: is “multiple teams stepping on each other” your actual problem yet?

Three layers of accessibility checks (and what each one caught)

Thu, 06 Aug 2026 00:00:00 GMT

Rebuilding this site on Astro was a good excuse to actually take accessibility seriously, instead of treating it as an afterthought. I ended up combining three different checks — static analysis, a runtime audit, and manual testing — and what stuck with me is that there was no overlap between them: each layer caught something the other two had no way of seeing.

Layer 1: static linting

The cheapest layer, catching issues before code even runs. This project mixes .astro and .vue files, and JSX-style accessibility linting doesn’t understand Vue templates at all — so two separate ESLint plugins were needed:

eslint-plugin-astro’s jsx-a11y-recommended config, for .astro files
eslint-plugin-vuejs-accessibility, for .vue files

The .astro side had a real gotcha: jsx-a11y-recommended doesn’t ship its own rules, it just re-exports eslint-plugin-jsx-a11y’s. That package is an optional peer dependency — without it installed, the config resolves to a no-op, silently. A deliberate test file (<img> with no alt, a <div onclick>) produced zero errors, which is exactly the kind of gap you don’t notice until it’s too late. Installing eslint-plugin-jsx-a11y explicitly fixed it.

Once it was actually linting, running it against the real codebase surfaced 9 findings — 8 of them false positives, all the same shape:

<ul role="list">...</ul>

The rule flags role="list" on a <ul> as redundant, since a <ul> already has list semantics. Except this project’s reset stylesheet does list-style: none everywhere, and removing bullets also strips the implicit list role in Safari/VoiceOver — a well-known modern-reset gotcha. The explicit role="list" puts the semantics back. Removing it, as the linter effectively suggested, would have reintroduced a real bug. Rather than scattering a disable comment across all 8 sites, the fix went into the rule config itself — no-redundant-roles takes a per-tag allowlist of roles to treat as non-redundant:

// eslint.config.mjs
'astro/jsx-a11y/no-redundant-roles': [
  'error',
  { ul: ['list'], ol: ['list'] },
],

One rule-level exception instead of eight scattered ones, and it stays correct for any <ul role="list"> added later too.

The 9th finding was real: a placeholder <a href="#">link</a> left over from early style-guide work — on /style-guide itself, a dev-only route that never ships to production — fixed by pointing it at an actual destination.

In the end, none of Layer 1’s findings were actually critical — unsurprising, since the AI tooling used to build the site had already been instructed to write accessible markup along the way, so linting mostly confirmed that rather than catching real breakage. Its real value is forward-looking rather than retrospective — configured once, it now runs on every future change automatically, catching regressions before they ever reach production.

Layer 2: runtime audit

Static linting only sees markup as written — it can’t tell you what actually gets rendered in the browser.

For that, I ran axe-core (the same engine behind Lighthouse’s accessibility score) via Puppeteer, against the real built and previewed site — not dev mode — across 7 representative pages: home, about, blog index, three different post types, and 404.

Two distinct, real issues turned up — one present on every page, the other specific to the homepage:

No <main> landmark. Page content lived in a plain <div class="page-content">. Screen reader users had no way to jump straight to it. One-line fix:

<div class="page-content">
<main class="page-content">

Zero styling impact — the CSS targets the class, not the tag.

Missing <h1> on the homepage. The homepage’s intro section never had one — just paragraphs, no heading. Fixed with a visually-hidden <h1> — the page keeps its intended visual design, but has a real, correctly-worded heading for anyone not looking at it.

Re-running the audit after both fixes: zero issues, across all 7 pages.

Layer 3: manual keyboard testing

This is the layer neither of the first two can substitute for, and it’s where the most interesting bugs turned up — all missed by every automated check I had configured, some because they only exist once a real person interacts with the page.

No visible focus indicator on a filter control. The blog index has an All/TIL/Articles filter built from three visually-hidden radio inputs (a zero-JavaScript filter using CSS :has()). Tab reached it fine, arrow keys moved between options fine, native radio semantics were all correct — but there was no visible focus ring anywhere in that interaction. The label was only styled for :hover and :has(:checked); nothing for focus, so the native ring rendered around the 1px-clipped input itself, invisible regardless. A real WCAG 2.4.7 (Focus Visible) failure — screen reader users were unaffected, since focus and state are still announced correctly, but a sighted keyboard user had no way to tell where they were:

.type-filter label:has(:focus-visible) {
  outline: var(--focus-ring);
  outline-offset: var(--focus-ring-offset);
}

This is exactly the class of bug static and automated tooling tend to miss — it requires observing actual rendered focus state, not just DOM/ARIA structure.

Wrong tab order on the scroll-to-top button. It sat as the very last element in the DOM, after the entire footer — so reaching it meant tabbing through the whole page first, defeating its entire purpose as a shortcut. Worse, the button becomes visible as soon as you scroll past one viewport — but Tab still wouldn’t reach it until cycling through everything else on the page, so it was visible long before it was actually focusable. Fixed by moving it right after the header, before <main> — safe to do since it’s position: fixed, so DOM order has zero effect on where it renders.

No warning before opening a new tab. External links (GitHub, LinkedIn) open in a new tab with no signal to screen reader users. Not a WCAG AA requirement — more of an AAA-level nicety — but trivial enough to add:

aria-label={href.startsWith('http') ? `${label} (opens in new tab)` : label}

Added along the way: a “skip to main content” link — genuinely missing, not a bug fix. First Tab stop on every page, invisible until it receives keyboard focus, jumping straight into <main>.

What’s still left

Manual VoiceOver testing still needs to be done. The rotor navigation and VO-key combinations have a learning curve, and I don’t know them well enough yet to test properly — that’ll be done in a future iteration.

The takeaway

Three types of check, three different bug classes, no overlap:

Linting guards against regressions going forward — here it mostly confirmed already-accessible markup, but it’ll catch real mistakes the next time someone (human or AI) writes one.
Automated auditing catches structural issues linting can’t see, because it needs a real rendered page to check against.
Manual testing catches interaction bugs neither can see at all, because they only exist once a real person moves through the page.

None of them substitutes for the others. If I’d stopped after the linter came back clean, the invisible-focus-ring bug and the scroll-button tab order would still be live today.

Claude Agent Skills: when a prompt deserves to be promoted

Wed, 05 Aug 2026 00:00:00 GMT

Credit / Source: Learned via Full Cycle

What a skill is

Do you find yourself explaining the same ‘how’ to the model, time after time? That’s a skill waiting to be born.

A skill is reusable procedural knowledge, loaded on demand. It’s not a one-off prompt, and it’s not code (a function) — it’s a folder with instructions, versioned in the repo.

It sits alongside CLAUDE.md/AGENTS.md and custom subagents, but answers a different question: not “what should the agent always know” (that’s CLAUDE.md) and not “who should handle this task” (that’s a subagent), but “how do I do this specific procedure, correctly, every time.”

When to create one

The single triage question:

Is this procedural knowledge reusable and stable enough to be worth a versioned file?

If that’s not clear-cut, the 3-YESes test:

Reuse — is it repetitive? (across multiple prompts, days, projects)
Non-obvious procedure — is there a “how” the model doesn’t get right on its own?
Stability — does the rule hold for days/weeks/months?

What is not a skill (common triage mistakes)

Ask	Belongs in
“Always answer in English”	`CLAUDE.md` (global preference)
“Status of the last deploy, right now”	MCP / tool (live state)
“Fix this parser bug”	A one-off prompt

Rule of thumb: one skill per responsibility, built on top of a shared base — not one skill per project trying to do everything.

Anatomy: a folder + SKILL.md

my-skill/
  SKILL.md      -> the only required file (frontmatter + body)
  reference/    -> extra context, loaded on demand
  scripts/      -> deterministic execution
  eval/         -> tests for the skill

The frontmatter (YAML at the top) has exactly two required fields:

name — the skill’s identity, matching the folder name.
description — the dispatch classifier. Third person, concrete triggers, and a “do NOT use for…” clause to keep it from over-firing.

Useful optional fields: allowed-tools, disable-model-invocation, model.

Progressive disclosure

Level	Content	When it loads
1	`name` + `description`	Always, near-zero cost
2	`SKILL.md` body	Only on a match
3	`reference/` + `scripts/`	On demand

That structure is what lets it scale: the permanent cost is Level 1 only, which is why you can have dozens of skills installed at once. Not every skill needs to climb through all three levels.

Six principles

The description is everything — concrete triggers, plus an explicit “do NOT use for” clause.
One responsibility — “review,” “test,” and “scaffold” are three separate skills, not one.
Push weight to Level 3 — keep the body short, put the rest in reference/.
Script beats prose — anything deterministic becomes a script, not a paragraph of instructions.
You’re running someone else’s code — treat it like installing software (see below).
Lean and versioned — it lives in git, changes go through a PR.

Security: treat it like installing software

Only pull skills from sources you trust.
Audit SKILL.md and any scripts/ for unexpected network calls or access outside the skill’s stated scope.
Sources that fetch URLs can come back with malicious instructions embedded in the response — prompt injection through the returned content.
allowed-tools is an extra layer of defense: only the listed tools are available to the skill, regardless of what its instructions ask for.

100 posts, a new stack: migrating ramigs.dev to Astro

Tue, 04 Aug 2026 00:00:00 GMT

🎉 This happens to be post number 100 — nice timing, landing right as this site’s migration to a new stack wraps up!

Old stack, new stack

The site launched in 2019 on Eleventy, with Gulp and Webpack handling the build. It served me well for years, but it hadn’t aged well — still pinned to Node v12, long since end-of-life and twelve(!) major versions behind where the new stack landed.

A few shots of the old site, for posterity:

The new version moves to Astro, with Vue for the few interactive pieces, TypeScript throughout, and pnpm managing all of it.

What was accomplished

All 99 previous posts migrated with the exact same URLs, so nothing that already pointed here breaks.

The whole design system was rebuilt from scratch — tokens, dark mode, typography — and the homepage and About page got updated content.

I also went through a proper accessibility pass (keyboard navigation, focus order, screen reader support via semantic HTML and ARIA) and a performance pass driven by actual Lighthouse data.

What’s new

A few things worth calling out:

Dark/light mode, remembers your choice, otherwise follows your system
An RSS feed
Reading-time estimates on every post
Jump-to-year navigation on the blog index
A TIL/Articles filter on the blog index — built with zero JavaScript, just CSS :has() selectors
A skip-to-content link, for keyboard navigation
A scroll-to-top button
Properly themed code syntax highlighting for both light and dark mode

A note on the process

Most of this migration was done with the help of Claude Code, using a single, persistent PLAN.md file as shared context across sessions — a living document that evolved with the work, tracking decisions and what had actually been verified. It let each session pick up exactly where the last one left off, and doubled as a chance to learn Claude Code more in depth, not just to get the project completed.

Closing thoughts

The old site served me well for seven years, and there was nothing wrong with it — Eleventy did exactly what a personal blog needs.

But it was time for a real update. I’ve learned a lot since then, but hadn’t really had the chance to apply it in my personal site. Plenty has changed in this space since 2019 too — CSS especially, with things like cascade layers and :has() making entire categories of JavaScript unnecessary.

If anything, this whole project reaffirmed that static sites are still a great fit for this use case: fast, simple, cheap to host, and — maybe the best part — the ability to just push to git and have the whole thing rebuild and deploy automatically is still gold.

CSS Cascade Layers: ending specificity wars

Sun, 02 Aug 2026 00:00:00 GMT

CSS Cascade Layers (the @layer at-rule) solve a long-standing pain point: specificity wars.

Before layers, overriding a third-party library’s highly-specific selector meant writing something even more specific, or reaching for !important.

Layers let us group styles into buckets and rank those buckets directly, independent of selector specificity.

Declaration order decides priority

Layers declared later win, no matter how specific the selectors are inside earlier layers:

@layer reset, base, components;

@layer reset {
  p {
    margin: 0;
  }
}

@layer components {
  p {
    margin: 20px;
  } /* wins: 'components' is declared last */
}

Even #my-id p inside reset would lose to the plain p in components — the whole layer sits higher in the cascade.

Specificity still works as normal inside a layer; layers only decide which bucket beats another bucket.

Unlayered CSS always wins

To avoid breaking existing stylesheets, any rule outside of an @layer block beats layered CSS, regardless of order:

@layer components {
  .btn {
    background-color: blue;
  }
}

.btn {
  background-color: red;
} /* always wins, unlayered */

(!important flips this: important rules inside layers beat important unlayered rules, so component libraries can still force safety overrides.)

Common patterns

Declare the layer order upfront, then fill layers in anywhere in the file (or across files):

@layer theme, layout, components;

@layer components {
  .card {
    padding: 1rem;
  }
}

Wrap third-party CSS on import so it never fights with our own styles:

@import "framework.css" layer(framework);
@import "theme.css" layer(theme);

Layers can also nest, via dot notation:

@layer framework.layout {
  .container {
    max-width: 1200px;
  }
}

Why bother

No more !important hacks to beat a framework’s specificity.
A clear, explicit architecture: reset, base, layout, components, each its own tier.
Supported natively in all modern browsers — no build step required.

Node.js Corepack: one shim for npm, pnpm and yarn

Wed, 29 Jul 2026 00:00:00 GMT

The problem

Different projects pin different package managers, and different versions of them. One repo wants pnpm@9, another wants yarn@3, a third is happy with whatever npm shipped with your Node.js install.

That means either installing every package manager globally and hoping the right version is active, or running one-off npx pnpm@9 install style commands to sidestep your global install.

What Corepack does

Corepack is a shim shipped alongside Node.js that sits in front of npm, pnpm, and yarn. Instead of installing a package manager globally, a project declares which one it needs via the packageManager field in package.json:

{
  "packageManager": "pnpm@9.12.0"
}

When you run pnpm install inside that project, Corepack reads that field, downloads and caches the exact pnpm@9.12.0 binary if it isn’t already available locally, and transparently forwards the command to it.

Move to a different project pinned to yarn@3.6.0 and the same thing happens for yarn, no reinstalling anything by hand. It solves the “works on my machine” class of problem where two projects quietly expect two different package manager versions.

Enabling is still a manual step

Corepack ships with Node.js (from 14.19 up to, but not including, 25), but it doesn’t do anything out of the box — it’s disabled by default. You need to run corepack enable once, so it can place its pnpm/yarn shims on your PATH.

The catch if you’re using nvm: each Node.js version nvm installs is its own self-contained directory, so corepack enable isn’t something you do once globally — it needs to be re-run every time you install a new Node.js version.

What’s changing in Node.js 25+

The Node.js Technical Steering Committee voted to stop bundling Corepack with Node.js starting in v25. It isn’t being deprecated — it stays maintained — but it’s no longer preinstalled. From v25 onward you install it yourself as a regular npm package:

npm install -g corepack
corepack enable

Node 24 and earlier keep shipping it as before, so nothing changes until you move to 25+.

Automating its installation on nvm

Since Corepack will soon be “just another package” to install, this is a good fit for nvm’s default-packages file: any package listed there gets installed automatically every time you nvm install a new Node.js version. Add it once:

echo "corepack" >> "$NVM_DIR/default-packages"

and every future Node.js version nvm installs will already have Corepack installed, without needing to remember to run npm install -g corepack by hand.

You’ll still need to run corepack enable for that version (the file only automates the install step, not enabling the shims), but that removes half the friction of picking up a new Node.js version.

This is the same trick covered in an older TIL about managing yarn versions via nvm — same file, same idea, just pointed at Corepack instead of a single package manager.

CLAUDE.md and AGENTS.md: correct the system, not the output

Tue, 28 Jul 2026 00:00:00 GMT

AI coding agents don’t carry any memory of your codebase from one session to the next. Every session starts cold — no idea how to run your tests, no notion of the convention you insisted on last week, no memory of the mistake you already corrected once before.

CLAUDE.md and AGENTS.md exist to close that gap: project-level files that get read automatically before the agent does anything else, so it shows up already knowing what it would otherwise need to be told again.

That also makes them different from regular documentation. Documentation is written for humans. These files are read by a model, every single session, and cost context whether they’re useful or not — so the discipline isn’t writing them, it’s keeping them focused enough to deserve that permanent seat in every request.

CLAUDE.md vs AGENTS.md

CLAUDE.md is Claude Code’s native format — it’s loaded automatically at the start of every session. It isn’t documentation; it’s short, precise instructions the agent needs before it starts working.

AGENTS.md is an open standard adopted by many coding agents, but Claude Code doesn’t read it natively.

Progressive disclosure

CLAUDE.md doesn’t all load at once. A root-level CLAUDE.md loads at the start of the session. A CLAUDE.md inside backend/ only loads once Claude is actually working in that folder. Other docs aren’t preloaded at all — they’re read on demand, when something actually points Claude to them.

CLAUDE.md guides the agent automatically; everything else should load only when necessary.

What actually belongs in it

Short, precise, and useful the moment a task starts:

Environment — how to start/stop things, which env vars matter.
Tests — the commands to run and what counts as passing.
Conventions — objective patterns, not style opinions.
Gotchas — known errors and common pitfalls.
Useful links — paths to docs for specifics, not the specifics themselves.

Managing CLAUDE.md vs AGENTS.md

Every AI coding tool looks for its own instruction file: Claude Code reads CLAUDE.md, Codex CLI (and others) read AGENTS.md, Gemini CLI reads GEMINI.md, Cursor uses .cursorrules. Maintain them separately and they drift — someone updates one and forgets the rest.

Symlink

The simplest fix:

ln -s AGENTS.md CLAUDE.md

The files become byte-for-byte identical — one source of truth, no extra tooling. It works fine on Mac/Linux, but needs Admin rights or Developer Mode on Windows, and since both files must match exactly, there’s no room for tool-specific instructions.

@import

The more flexible option. Put the shared instructions in AGENTS.md, then make CLAUDE.md a one-liner that imports it, with any Claude-only rules appended below:

@AGENTS.md

## Claude Code specific

Use plan mode for changes under `src/payment/`.

This works cross-platform with no symlink permissions to worry about, and lets you layer tool-specific instructions on top of one shared base.

Three things to watch for: @file.md pulls in the file’s entire content (avoid it for large docs — link instead and let the agent read on demand), imports inside fenced code blocks aren’t resolved, and imported headings aren’t renested under the section that references them.

Bottom line: symlink if you want strictly identical files and don’t need Windows support; @import if you want one shared source plus room for Claude-specific additions.

Takeaway

An agent that makes the same mistake twice isn’t a model problem — it’s a missing line in CLAUDE.md. Treat it less like a README and more like a place to encode every correction you don’t want to give twice.

[TIL] vite-plugin-checker

Tue, 28 Jul 2026 00:00:00 GMT

TIL about vite-plugin-checker.

Vite’s dev server transpiles files on the fly without type-checking them, so a broken type can slip right through and only get caught later, at build time or in CI. vite-plugin-checker closes that gap.

Once added to vite.config.ts, it runs your configured checkers (TypeScript, vue-tsc, ESLint, Stylelint…) in a separate process alongside the dev server, and surfaces errors in two places while you’re developing:

The terminal running vite, right next to the dev server’s own logs.
A browser overlay, so the error shows up on the page you’re already looking at, instead of staying buried in a terminal you might not have open.

Example config:

import checker from "vite-plugin-checker";

export default defineConfig({
  plugins: [
    checker({
      typescript: true,
      eslint: {
        lintCommand: 'eslint "./src/**/*.{ts,tsx}"',
      },
    }),
  ],
});

Nice for catching type and lint errors immediately during development, instead of waiting for a build or CI run to point them out.

How agents and subagents work in Claude Code

Mon, 27 Jul 2026 00:00:00 GMT

Credit / Source: Learned via Full Cycle

“Agent” gets thrown around loosely, but in Claude Code it maps to a fairly precise structure. Here’s how the pieces actually fit together.

Anatomy of an agent

Claude Code is the harness: it defines the environment, provides tools, and exposes the mechanism for instantiating agents. It doesn’t decide which agent runs, though — that call is made by the agent itself (the model), based on the task at hand.

An agent is made up of three things:

User instructions — what you actually asked for.
Predefined behavior — its scope and its own baked-in instructions.
Its own context window — separate token budget, filling up as it works.

The agent calls the model, gets results back, and uses tools/environment (terminal, files, web, a database) to act on them.

There are two ways an agent comes into existence:

Built-in agents, already shipped with the harness — Explore, Plan, general-purpose.
Custom agents, defined by you in .claude/agents/my-agent.md. You write the behavior and specialty; Claude Code creates, registers, and provides the environment for it. The file is Markdown with YAML frontmatter (name, description, optionally tools and model) followed by the subagent’s system prompt in the body — and it can live at the project level (.claude/agents/, shared with your team) or the user level (~/.claude/agents/, available across all your projects).

The harness defines the environment. The agent follows instructions, uses its own context, and calls the model.

Subagents: delegation with isolated context

A subagent is a specialized agent, instantiated by the main agent, to execute one specific task.

The main agent:

receives the user’s goal,
decides whether to delegate,
sends a specific task to a subagent (or several, in parallel),
consolidates the results.

Which subagent gets picked isn’t hardcoded, either: Claude matches the task against each subagent’s own description field and delegates accordingly.

Each subagent gets a task, a prompt from the main agent, its own tools, and — critically — its own context window. It doesn’t share the main agent’s context, and the main agent doesn’t automatically see the subagent’s internal history back — only the result, or a useful summary, lands in its context window. The full transcript isn’t gone; it’s just parked outside the main thread unless you go pull it back up.

Why the isolation matters

This isn’t an implementation detail — it’s the whole point.

The main agent’s context stays clean no matter how much a subagent had to dig around to get an answer. All that exploration cost is paid out of the subagent’s own budget, not the main thread’s.

Multiple subagents can run in parallel, each burning its own tokens independently, instead of serializing everything through one context window.

A custom subagent lets you pre-bake scope and behavior for a repeated kind of task (e.g. “review this diff,” “explore this codebase”) so you’re not re-explaining it every time.

Takeaway

An “agent” in Claude Code isn’t the model — it’s instructions + behavior + its own context window, wrapped around a model, using tools. Once that clicks, subagents stop looking like magic and start looking like what they are: regular agents, delegated a task, with a wall around their context so the main thread doesn’t have to pay for their scratch work.

[TIL] git worktree

Sun, 26 Jul 2026 00:00:00 GMT

TIL about git worktree.

It’s funny how a tool you use every single day can still surprise you. Git has so many commands tucked away that never come up in the day-to-day add, commit, push, pull loop, and you only stumble onto them when you hit the exact problem they were built for. In my case, that problem was wanting to work on two branches of the same project, side by side, without stashing or juggling a second clone.

The problem

Say I’m on main and need to try out a migration on a separate branch, without losing my current working directory. The instinct is to just copy the folder:

cp -r ramigs.dev ramigs.dev-migration
cd ramigs.dev-migration
git checkout -b migration

That works, but it’s not quite right.

Enter `git worktree`

git worktree add <path> -b <branch-name> is a single git command that does this for you. A few things that make it different from copying the folder yourself:

It creates the new folder and checks out the new branch in one step — no manual cp then git checkout.
The new folder does not duplicate .git — it’s a lightweight linked working tree that shares the same object database/history with the original repo. Only a small .git file (a pointer) lives in the new folder, not the whole history again.
Things git doesn’t track — node_modules, dist — won’t be copied either, so you’d run npm install fresh there.
Git prevents the same branch from being checked out in two worktrees at once, so main in one folder and migration in another can coexist safely with no conflicts.

So the command would look something like:

git worktree add ../ramigs.dev-migration -b migration

Run from the original repo, and that’s the entire setup step. Two folders, two branches, one shared history, no copy-pasting required.

Cleaning up with `git worktree remove`

Once the migration branch was merged into main — or if I’d decided to abandon it instead — my instinct was to just rm -rf the folder, same as I would with a manual copy. That mostly works, but it leaves git confused: the original repo still has an entry under .git/worktrees/ pointing at a directory that no longer exists, and git won’t let you delete the branch that folder had checked out until that reference is cleared.

git worktree remove <path> is the proper way to tear it down:

git worktree remove ../ramigs.dev-migration

This removes both the working directory and the administrative metadata in one step, so the original repo has no dangling references left behind. If the worktree has uncommitted changes, git refuses to remove it unless you pass --force — a small safety net against losing work you forgot about.

git worktree list is worth running before and after, just to see what worktrees are currently registered. And if you ever do end up manually deleting a worktree folder instead of using remove, git worktree prune cleans up the stale metadata afterwards.

Doing the setup with git worktree add and skipping the matching git worktree remove is the same mistake as the cp -r approach from earlier — it looks done, but it leaves git’s bookkeeping out of sync with what’s actually on disk.

Worktrees for AI agents

Worktrees aren’t just a convenience for a human juggling two branches, they’re a good fit for AI coding agents too. An agent working in the same checkout you’re using is one accidental git checkout away from yanking the branch out from under you, or clobbering uncommitted changes it didn’t know were “yours”. Give it its own worktree instead, and it gets a real working directory and its own checked-out branch, isolated from whatever you’re doing in the original, but still sharing the same object database, so nothing has to be cloned or synced separately.

That isolation is what makes it interesting for running multiple agents side by side — each on its own branch, in its own worktree, unable to step on each other. It’s the kind of building block that matters if you’re setting agents to iterate somewhat independently, which ties into Loop engineering, something I want to dig into more in the near future.

The takeaway

I’ve been using git for almost a decade and still found a command I didn’t even know I needed, and how useful it can be. That’s the fun part of tools like this — they’re deep enough that you never really stop learning them.

[TIL] AI Context Windows and Tokens

Fri, 24 Jul 2026 00:00:00 GMT

Credit / Source: Learned via Full Cycle

TIL that an AI’s Context Window isn’t measured by the number of messages or files you send, but by a hard limit on total tokens.

Think of the Context Window as the LLM’s temporary desk space.

The maximum amount of text (in tokens) the model can fit on that desk at one single moment is its context window.

Every piece of data takes up space on the same limited track:

Prompt
History
Open Files
Code Snippets
Tool Results

Every single item listed above consumes tokens. Once that total hits the hard limit, the model has to adapt.

What happens when the window fills up?

When your session runs out of token budget, the system usually handles it in one of two ways:

Sliding Window (Overwrite): The oldest tokens (like your initial prompt or early chat history) are dropped off the back to make room for new input.
Compact & Summarize: The system takes early messages and creates a condensed summary to preserve essential facts using far fewer tokens.

The big takeaway

Limits are strictly about tokens, not files or messages. Keep your context clean to ensure the model holds onto the information that actually matters!

[TIL] The 9 pillars of AI-assisted software development

Fri, 24 Jul 2026 00:00:00 GMT

Credit / Source: Learned via Full Cycle

TIL that modern AI-assisted development isn’t just about using a smart chatbot to autocomplete code. It actually relies on an interconnected ecosystem of 8 supporting pillars, all centered around one core concept: Workflow.

Here is a quick breakdown of how these components work together:

The core: Workflow

At the center of it all is your Workflow. The 8 supporting pillars exist to enable, automate, and streamline how you plan, write, test, and ship code.

The 8 supporting pillars

Tools (IDEs, CLIs): The interfaces you interact with daily (VS Code, terminal CLI tools) where AI capabilities live.
Agents: Autonomous or semi-autonomous AI actors capable of executing multi-step tasks.
Models: The underlying LLMs (like Claude, GPT, or Llama) driving the intelligence.
Documentation & Artifacts: Project specs, PRDs, context files, and design artifacts that ground the AI in your specific codebase.
Skills: Specific capabilities, rules, or system instructions assigned to AI tools to perform precise jobs.
Memory: Contextual history (chat logs, persistent project knowledge, vector databases) so the AI retains context mid-project.
Environments (Local, Remote, GitHub): Where execution actually happens—whether you’re running code locally, in a remote container, or via CI/CD pipelines.
MCP Servers (Model Context Protocol): Standardized protocol layers connecting LLMs to external data sources, databases, and APIs.

💡 Key takeaway

If you want to maximize developer productivity with AI, don’t focus solely on the models. Look at the whole ecosystem—from memory and environment setups to context protocols (MCP)—to build a seamless developer experience.

[TIL] Prompting techniques (how AI models actually "think")

Thu, 23 Jul 2026 00:00:00 GMT

Today I learned that getting a Large Language Model (LLM) to give a accurate, high-quality answer isn’t just about what you ask—it’s about how you structure its thinking process.

Researchers have developed structured prompting techniques to help models plan, reason step-by-step, and even interact with external tools.

Here is a quick breakdown of 5 essential prompting techniques every AI developer should know.

1. Zero-Shot Prompting

The Pitch: Just ask directly.
How it works: You give the model a task or question without providing prior examples or explicit step-by-step reasoning instructions.
Best for: Simple facts, standard classification, translation, and everyday Q&A where the model’s base training is sufficient.

2. Chain-of-Thought (CoT)

The Pitch: “Show your work step-by-step.”
How it works: You instruct the model to break down its internal reasoning before arriving at the final answer (often by adding "Let's think step by step" or providing examples that demonstrate intermediate steps).
Why it matters: LLMs generate text token-by-token. Giving them explicit “thinking space” allows them to compute intermediate steps instead of guessing prematurely.
Best for: Math problems, writing and debugging complex code logic, and multi-step reasoning.

3. Tree of Thoughts (ToT)

The Pitch: Explore multiple decision paths, evaluate possibilities, and backtrack when stuck.
How it works: An extension of Chain-of-Thought where the model explores a tree structure of intermediate “thoughts.” At each step, it generates multiple candidate ideas, evaluates them, and uses search algorithms to pick the best path or backtrack if it hits a dead end.
Best for: Strategic planning, complex puzzle solving, chess-like game logic, and multi-branch creative brainstorming.

4. Skeleton-of-Thought (SoT)

The Pitch: Create an outline first, then expand each point in parallel for maximum speed.
How it works: Designed specifically to reduce latency in long-form generation. The model first outputs a concise structure or outline (the “skeleton”). Then, each section of the skeleton is populated concurrently (typically via parallel API requests).
Best for: Long-form blog posts, scaffolding full codebases/project architectures, and rapid document generation.

5. ReAct (Reason + Act)

The Pitch: Think, execute an external action, observe the result, and repeat.
How it works: Combines reasoning traces with dynamic tool usage in an iterative loop.
Best for: Autonomous agents, AI coding assistants that run tests and terminal commands, and external API integrations.

[TIL] The 4 layers of modern AI tools (Prompt, Context, Harness, Loop)

Wed, 22 Jul 2026 00:00:00 GMT

When we start integrating AI tools into our daily development workflow, we often think it’s all about writing better prompts. But as we dig deeper, we realize Prompt Engineering is only layer one.

Today I learned that understanding how modern AI tools work comes down to four distinct layers:

1. Prompt engineering

What I tell the model.

This is the foundation: crafting clear system instructions, setting explicit boundaries, formatting outputs, and providing few-shot examples. It governs the immediate reasoning and output of the model.

2. Context engineering

What the model “knows” at each step.

LLMs are only as good as the information in their context window. Context engineering is the art of dynamically injecting relevant data into the prompt—via Retrieval-Augmented Generation (RAG), search outputs, memory stores, or trimmed conversation histories—without exceeding token limits or causing “lost in the middle” phenomena.

3. Harness engineering

The environment, mechanisms, and controls with which the agent operates.

The harness (or scaffold) is the runtime environment that wraps the LLM. It manages API retries, handles tool integration (calling functions or web tools), enforces structured output schemas, and manages fallback behavior if the model hallucinates or fails.

4. Loop engineering

How the system self-corrects and iterates.

Loop engineering moves past one-shot answers by putting the LLM inside an iterative feedback loop. It gives the model the ability to run trial-and-error workflows—evaluating its own work, using tool feedback, and revising its steps until it meets the final goal.

The takeaway

Layer	Focus Area
Prompt	Instructions, examples, format
Context	RAG, memory, conversation history, injected state
Harness	Tool routing, permissions, validations, safety rails
Loop	Multi-turn reasoning, self-correction, agentic workflows

Even if we’re not developing AI systems ourselves, knowing these layers helps us work more effectively with AI-assisted development tools—we’ll better understand their capabilities, limitations, and how to get the best results from them.

Smoothing Nuxt 2 to Nuxt 4 Migration with vue-declassify

Sun, 02 Nov 2025 00:00:00 GMT

Migrating a Nuxt 2 app to Nuxt 4 can be a daunting process, especially if your codebase relies heavily on class-style Vue components. I’m right in the middle of this kind of migration for a client, so these challenges are hitting close to home.

Before tackling the actual migration, I was looking for ways to do as much as possible in the current version. That’s when I found a fantastic tool that makes the transition much smoother: vue-declassify.

vue-declassify automates the conversion of class-style components into their equivalent object-style format, removing the usage of property decorators. This is a crucial first step, as Nuxt 4 and Vue 3 favor object-style and composition API patterns. By using this tool, I was able to prepare my codebase for the migration while still running Nuxt 2, reducing risk and manual effort.

The quality of vue-declassify is impressive. It manages the conversion process with accuracy, even for complex components, and the output is clean and readable. Although it needs a couple of tweaks for some scenarios, it’s still a fantastic tool.

If you’re planning a similar migration, I highly recommend giving it a try—it saves time and helps ensure a smoother upgrade path.

Transitioning to AI-assisted software development

Sun, 02 Nov 2025 00:00:00 GMT

Over the last couple of months, I’ve (finally) decided to take the leap and start using AI tools to assist my day-to-day software development work.

What began as basic prompts in Gemini—I find myself nowadays turning to Google and Stack Overflow less and less—has now evolved into using GitHub Copilot directly in VSCode. These tools have already made a noticeable impact, helping me with code explanations, code generation, refactoring, and brainstorming new ideas.

Initially, I was not only a bit skeptical about relying on AI for programming tasks, but I also wanted to let these tools mature and avoid getting caught up in the initial hype.

As I started experimenting, I found that these tools could quickly answer questions, suggest code snippets, and automate repetitive tasks. This increased my productivity and freed up more time for creative problem-solving and deeper learning.

Using Copilot Agent mode in VSCode has been truly impressive—there’s so much it can do, and it does many things exceptionally well. I feel like I’ve only begun to explore its capabilities, and I’m continually surprised by how well it understands my intent.

Today, AI is a regular part of my toolkit. I use it to generate boilerplate code, refactoring code, review pull requests, and even write documentation. The key is to treat AI as a helpful assistant—one that accelerates my work but still requires my judgment and expertise.

PS: AI assisted me in writing this post about AI. I promise it didn’t get too meta! 🤖

Vue.js: notes on Slots

Wed, 25 Dec 2024 00:00:00 GMT

Vue slots allow us to create generic components, by passing template content (custom markup) to child components.

Let’s say we have a MyButton component which we’d like to make generic. We can set a slot inside its template:

<button>
  <slot></slot>
</button>

We can then pass custom content to MyButton:

<MyButton>Submit</MyButton>

The HTML node Submit replaces the tag <slot></slot> when the component gets rendered.

Optionally, we can specify some fallback content, to be rendered when the parent does not provide content for a slot:

<button>
  <slot>Click me</slot>
</button>

We’re not limited to text, we can also pass any valid template content:

<MyButton>
  <strong>S</strong>ubmit
</MyButton>

Since we didn’t explicitly name the slot above, it will implicitly become the default slot, named default. The following achieves the same result as the above:

<MyButton>
  <template v-slot:default>
    <strong>S</strong>ubmit
  </template>
</MyButton>

Instead of v-slot:, we can use the shorthand #, as in <template #default>.

Named slots start to become useful when we want our component to provide more than one slot:

<button>
  <slot name="emoji"></slot>
  <slot>Click me</slot>
</button>

<MyButton>
  <template v-slot:emoji>👍</template>
  <template v-slot:default>
    <strong>S</strong>ubmit
  </template>
</MyButton>

Sometimes we may have some state inside our child component that we’d need the parent to be aware of (to render the content of a slot). We can use scoped slots to achieve that:

<button @mouseenter="hover = true" @mouseleave="hover = false">
  <slot name="emoji" :hover="hover"></slot> <slot>Submit</slot>
</button>

<MyButton>
  <template #emoji="{ hover }">{{ hover ? '👍' : '👎' }}</template>
</MyButton>

[TIL]: Ventoy: bootable USB drive with multiple ISOs

Fri, 06 Dec 2024 00:00:00 GMT

TIL about Ventoy, an amazing open source tool which allows to create bootable USB drives with multiple ISOs.

No need anymore to format the USB drive every time I need to install a new operating system. The same USB stick can store more than one ISO.

I’m currently storing GParted, Fedora, and Ubuntu images in the same USB stick. When I boot from it, I just need to select the desired image from the menu.

To add a new ISO, one simply needs to drag and drop the respective file to the USB stick.

Raspberry Pi 4 + Ubuntu: how to control the Case Fan

Mon, 02 Dec 2024 00:00:00 GMT

I’ve recently bought a Raspberry Pi 4 Model B, together with its official Case and Case Fan.

After installing Ubuntu Server, noticed that the fan was always running non-stop. The fan has an annoying noise, and it should only run when needed, i.e., when the Pi’s temperature rises above a certain threshold.

Contrary to Raspberry OS, where the fan is disabled by default (and can be configured from the UI via Preferences -> Raspberry Pi Configuration -> Performance), Ubuntu Server requires an extra configuration step to be performed from the command line.

After the installation is finished, make sure the system is up-to-date:

sudo apt update
sudo apt full-upgrade

Based on my experiments, this step seems to really be needed, maybe because it installs some Raspberry Pi required drivers/firmware (?).

Finally, edit the file /boot/firmware/config.txt and add the following at the end of the file:

[all]
dtoverlay=gpio-fan,gpiopin=14,temp=60000

A reboot is needed for changes to take effect.

temp is the temperature at which the fan turns on. By default, on Raspberry OS it’s set to 80º Celsius, but I’ve decided to set it to 60º Celsius.

To confirm everything is working as expected (the fan is not running non-stop anymore and turns on and off based on the Pi’s temperature) I used stressberry.

[TIL] Dynamically importing JSON in JavaScript

Fri, 08 Nov 2024 00:00:00 GMT

TIL that it’s possible to dynamically import a JSON file in JavaScript:

const json = (await import("team.json")).default;

import returns a promise, so async/await can be used. We then need to access property default, since import only supports default export.

Find out more about import() here.

Vue: v-model on custom components

Sat, 02 Nov 2024 00:00:00 GMT

In Vue.js we use v-model to achieve two-way data biding.

Using v-model on form inputs is probably its most well-known use case, where we want to keep the state of the input and some JavaScript state in sync.

However, v-model can also be used on custom components.

Let’s say we have a parent component and a child component. We have the state in the parent component but we want the child component to be able to update it.

Before Vue 3.4

We would do something like this in the parent component:

const selectedColor = ref('yellow')

<ChildComponent v-model="selectedColor" />

In the child component we would set a prop named modelValue and emit the event update:modelValue (with its respective new value) when we wanted selectedColor to be updated:

const props = defineProps(["modelValue"]);

const emit = defineEmits(["update:modelValue"]);

const updateColor = (color) => {
  emit("update:modelValue", color);
};

Note: The prop and event names must be exactly those for v-model to work as expected.

Since Vue 3.4

Starting from Vue 3.4, there’s a more convenient, less verbose way to achieve the same result. We can use the defineModel() macro.

The parent component remains the same. In the child component no need for the prop and the emit. defineModel() does it all behind-the-scenes, and we can just update the value directly in the child component:

const selectedColor = defineModel();

const updateColor = (color) => {
  selectedColor.value = color;
};

TypeScript: conditionally type a property based on another property

Sat, 26 Oct 2024 00:00:00 GMT

Let’s say we want to model a workout plan in TypeScript.

A workout plan has:

id, name, creation date, updated date
type (cardio or strength training)
a list of exercises

Depending on the workout type, the list of exercises should be typed accordingly, i.e., a cardio exercise has distance and duration, while a strength training exercise has number of sets, number of reps, and weight.

How can we achieve that?

The following is one way to do it. First, we set a base type without type and list of exercises:

type WorkoutPlanBase = {
  id: number
  workoutName: string
  created_at: Date
  updated_at: Date
}

Then, we define our workout plan type using an intersection (to extend from the base type) and a discriminated union (where we use the literal type for workoutType to specify the respective two possible types for exercises):

type WorkoutPlan = WorkoutPlanBase &
  (
    | { workoutType: "strength", exercises: StrengthTrainingExercise[] }
    | { workoutType: "cardio", exercises: CardioExercise[] }
  );

This example from Blaine Garret’s article was very helpful for my understanding.

TypeScript: union members as object properties

Wed, 09 Oct 2024 00:00:00 GMT

Let’s say we have the following string union type to define all the possible values of a status:

type Status = "Completed" | "Pending" | "Canceled";

We also have another string union type to define all the possible colors of a badge component:

type BadgeColor = "green" | "yellow" | "red";

We have the following object to map statuses with badge colors:

const statusColors = {
  Completed: "green",
  Pending: "yellow",
  Canceled: "red",
};

We’d like to type this object to make sure we will never forget to update it, in case we add or remove a status value. TypeScript should throw an error to let us know.

How can we achieve that?

We can annotate the object as follows combining an index signature with the JavaScript in operator:

const statusColors: { [key in Status]: BadgeColor } = {
  Completed: "green",
  Pending: "yellow",
  Canceled: "red",
};

Now, if we add a new status Unknown to the Status union type, TypeScript complains:

Property 'Unknown' is missing in type '{ Completed: "green"; Pending: "yellow"; Canceled: "red"; }' but required in type '{ Completed: BadgeColor; Pending: BadgeColor; Canceled: BadgeColor; Unknown: BadgeColor; }'.

If we remove the status Pending, TypeScript will also complain:

Object literal may only specify known properties, and 'Pending' does not exist in type '{ Completed: BadgeColor; Canceled: BadgeColor; }'.

If we try to assign a non-existing BadgeColor, TypeScript will also complain:

Type '"blue"' is not assignable to type 'BadgeColor'.

How to set up Sass in a Vue.js Vite project

Sun, 06 Oct 2024 00:00:00 GMT

First, install sass-embedded:

yarn add -D sass-embedded

Note that sass-embedded should be installed, not sass; otherwise you’ll get the warning Deprecation [legacy-js-api]: The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0.

Then, add the following property to the UserConfig object in vite.config.ts:

css: {
  preprocessorOptions: {
    scss: {
      api: 'modern-compiler'
    }
  }
},

You can now update the extension of your .css files to .scss and use <style lang="scss"> in your .vue files.

Vite dev: automatically open app in the browser

Sat, 05 Oct 2024 00:00:00 GMT

When running the vite dev server (commands vite, vite dev, and vite server), it’s possible to specify the option --open so that the app opens automatically in the browser.

BROWSER and BROWSER_ARGS can also be used to pass additional settings, either as environment variables or as process.env arguments.

For example, in my case I want to open Firefox Developer Edition, so in package.json I use:

"dev": "BROWSER='/Applications/Firefox Developer Edition.app' vite --open"

[TIL] Unix shebang

Sat, 14 Sep 2024 00:00:00 GMT

TIL how the Unix shebang is actually used.

You know that first line in shell scripts starting with !#, typically something like #!/bin/bash or #!/bin/zsh? That’s the shebang.

When a script is used as an executable (i.e., had its execute permission x set and is being executed as ./my-script), the operating system’s program loader is instructed to run the shell interpreter (bash or zsh, for example), passing the rest of the script file content as the first argument to the interpreter.

This means that the file extension is not actually used by the interpreter. Even though the presence of the extension has become a common convention (its presence might provide some visible clue about the file type), some argue that extensions should not be used at all. The rationale behind it is that the user of the script should not care or need to know about how it was implemented.

[TIL] Git: commit early, commit often

Sun, 08 Sep 2024 00:00:00 GMT

Just another gentle reminder to “commit early, commit often”.

Yesterday I got reminded of this the hard way, when loosing a reasonable amount of work due to an accidental git restore ..

My IDE was closed at that time, so wasn’t even able to use its undo functionality to recover my changes 😭.

GitHub Actions: trigger a workflow_dispatch workflow from another workflow

Tue, 11 Jun 2024 00:00:00 GMT

Let’s say you have your deploy pipeline set as a GitHub Action workflow, which is triggered manually (using the workflow_dispatch event) and allows you to select to which environment you want to deploy.

On certain occasions you might be interested in deploying to all environments. Instead of having to manually trigger the pipeline for each environment, you could create a new workflow and use the action benc-uk/workflow-dispatch, allowing you to trigger this workflow only once and deploy to all environments, as such:

name: Deploy to all environments pipeline

on:
  workflow_dispatch:

jobs:
  deploy:
    name: "Deploy to all environments"
    runs-on: ubuntu-latest
    steps:
      - name: Invoke Deploy pipeline workflow for dev
        uses: benc-uk/workflow-dispatch@v1
        with:
          workflow: deploy-pipeline.yaml
          inputs: '{ "environment": "dev" }'
      - name: Invoke Deploy pipeline workflow for staging
        uses: benc-uk/workflow-dispatch@v1
        with:
          workflow: deploy-pipeline.yaml
          inputs: '{ "environment": "staging" }'
      - name: Invoke Deploy pipeline workflow for production
        uses: benc-uk/workflow-dispatch@v1
        with:
          workflow: deploy-pipeline.yaml
          inputs: '{ "environment": "production" }'

Another cool thing about this action is that it your workflows will run in parallel, since they’re triggered behind-the-scenes via REST API calls.

Open Props review

Thu, 06 Jun 2024 00:00:00 GMT

How I discovered Open Props

Recently, we were given a mission to fully replace the frontend design in one of my client’s applications - a typical user dashboard, built on Nuxt 2.

We were handed new Figma designs, which totally differed from the previous designs, so we had no way other than deleting the existing CSS/Sass code entirely and re-style the frontend from scratch.

The previous version of styles were not in very good shape. The project had gone through several design iterations in the past, with the participation of various developers and without much thought having ever been put into CSS architecture and conventions.

We began researching how we could use this opportunity to implement a design system that could help us materialize the new Figma designs (pixel-perfect was a requirement) more efficiently, while achieving more modular and maintainable codebase.

We came across Open Props and after studying its documentation and watching some YouTube videos, we ended up deciding to integrate it in our project.

Open Props is a CSS framework that provides built-in CSS custom properties with sensible values.

Installing Open Props

We used the most recent version available at the time of implementation, 1.6.21.

Since we were still using an older version of Nuxt (which uses PostCSS 7 by default), we faced some initial difficulties, but in the end we managed to integrate Open Props, by upgrading to PostCSS 8 (and supported by @nuxt/postcss8 and postcss-html). We also used postcss-jit-props, so that only used variables got included and shipped.

Autocomplete in VSCode for Open Props variables (and project global variables) was pretty straight-forward to achieve by using the CSS Var Complete extension and following the documentation.

Using Open Props

One of the cool things about Open Props is that it is incrementally adoptable, meaning you can load only the modules that are actually used.

We began by loading the normalize.light.min.css stylesheet to normalize the styles between the different browsers and set some sensible defaults.

Besides the normalize module, we’ve ended up actually not using any of the other modules. We discovered that our new design didn’t match the Open Props values, so we ended up having to create our own design tokens, which were nevertheless heavily inspired by Open Props.

We haven’t still implemented - or given instructions on how to implement - animations, but I can foresee us using the animations.css, durations.css, and easings.css modules. We’ll try to coordinate with the designer so that we can make use of these already existing Open Props sensible values, avoiding having to come up with our own.

Verdict

Although I can see tremendous value in this tool, I came to the conclusion that it really didn’t fit our use case - a pixel-perfect implementation of an already existing design.

It did however heavily influence the structure and implementation of our design system and respective design tokens.

As mentioned above, we had some difficulties with the installation, but that’s probably more on us using a legacy version of Nuxt. I believe that with current versions of the most popular frontend frameworks the integration should be seamless.

All in all, I think this tool could be extremely helpful for someone that does not have an already existing design and needs to more quickly create something that looks consistent (and end up with more maintainable CSS), by letting Open Props guide the design.

[TIL] CSS: detect user request for light/dark themes

Sat, 09 Mar 2024 00:00:00 GMT

TIL about the prefers-color-scheme CSS media feature, which allows to natively detect if a user requested light or dark themes (typically through an operating system or user agent setting).

It can be used as such:

@media (prefers-color-scheme: dark) {
  body {
    background: var(--bg-color-dark);
  }
}

Chrome DevTools has a very useful toggle that allows emulating different prefers-color-scheme values.

Learn more about prefers-color-scheme here.

Fully uninstall an application on macOS

Sun, 21 Jan 2024 00:00:00 GMT

Unfortunately, not all applications provide a clean, full uninstall.

On macOS, one generally deletes the .app file from /Applications. But many applications leave behind support files (cache, preferences, etc.), so might be a good idea to go through the following folders and delete the respective leftovers:

/Library
/Library/Application Support
/Library/LaunchAgents
/Library/LaunchDaemons
/Library/Preferences
/Library/PrivilegedHelperTools
~/Library/Application Scripts
~/Library/Application Support
~/Library/Caches
~/Library/Cookies
~/Library/Group Containers
~/Library/Launch Agents
~/Library/Logs
~/Library/Preferences
~/Library/Saved Application State

GitHub Actions: how to set a value conditionally

Tue, 16 Jan 2024 00:00:00 GMT

How to conditionally set a value in GitHub Actions:

env:
  TOKEN: github.event.inputs.env == 'dev' && secrets.DEV_TOKEN || secrets.PROD_TOKEN

If github.event.inputs.env == 'dev' evaluates as true, TOKEN will have value secrets.DEV_TOKEN; otherwise it will have value secrets.PROD_TOKEN.

What I do when my PR includes commits that are already in main

Fri, 12 Jan 2024 00:00:00 GMT

Sometimes I have an open PR (branch my-pr) and I need to sync it with latest main. I usually do the following:

git checkout main
git pull origin main
git checkout my-pr

If there are merge conflicts, for some reason that I haven’t exactly figured out, commits that are already in main get included in my PR, when pushed.

Might not be the most elegant solution, but one which works effectively for me. After fixing merge conflicts, committing, and pushing, I do the following:

git checkout my-pr
git checkout -b my-pr-v2
git push origin my-pr-v2

Now, when opening the PR only my PR commits will be included. I can now close the PR that has branch my-pr.

Alternatively, I’ve read that it’s also possible to edit the PR via GitHub UI, change the base branch to another branch and back to main, but I haven’t tried this solution myself.

Integrating GitHub CLI in my workflow

Sat, 30 Dec 2023 00:00:00 GMT

As the end of the year rapidly approaches, I’ve been reflecting and looking for ways to increase my productivity in the next year.

For some time I’ve been considering integrating GitHub CLI in my workflow, aiming to reduce the back and forth between the terminal and the GitHub web UI.

Since I interact with pull requests pretty much everyday, several times a day, that’s where I’ll focus mainly.

Listing some useful commands below for reference.

Open repository in the web browser

gh browse

List open PRs

gh pr list

Get status of relevant PRs

gh pr status

View PR in the browser

gh pr view --web

Checkout a PR

gh pr checkout

Accepts PR number or branch name.

Create a PR

gh pr create

It’s also possible to skip the interactive PR creation, by directly specify the title and body:

gh pr create --title "PR title" --body "PR body"

Other options:

To mark PR as draft use option -d.
To open the web browser to create the PR use option -w.

Close PR

gh pr close

Other options:

To leave a closing comment use option -c.
To delete the local and remote branch after close use option -d.

The entire list of available commands and respective documentation can be found here.

[TIL] Specify node version in package.json

Thu, 28 Dec 2023 00:00:00 GMT

One way to minimize “it works on my machine” type of issues and bad surprises related to incompatibilities (especially in team contexts) is to be very specific (and if possible, ideally enforce) about the software versions that are used across the entire stack.

TIL about engines.node in package.json. As stated in the documentation, it’s used to “specify the version of node that your stuff works on”.

When engines.node is specified, someone that tries to yarn install (and not using a compatible node version) will get an error similar to The engine "node" is incompatible with this module. Expected version "v20.10.0". Got "16.20.2".

Run the following command to set engines.node according to the current node version:

npm pkg set engines.node=$(node -v)

[TIL] VSCode: Two file management extensions

Tue, 26 Dec 2023 00:00:00 GMT

TIL about two file management VSCode extensions for increased productivity:

Thanks for this tip James Q Quick!

[TIL] Manage yarn via nvm

Wed, 06 Dec 2023 00:00:00 GMT

TIL that it’s possible to manage via nvm, not only node versions, but also yarn versions.

The advantage of doing so (instead of one single installation via brew, for example), is that you’re able to pin a specific yarn version to each node version.

For already installed node versions, make sure you’re using the intended version (i.e., which node should print something like $NVM_DIR/versions/node/v20.10.0/bin/node) and then run npm install -g yarn.

For future node versions you’ll install, there’s a way to automatically install yarn alongside node, without needing to explicitly install.

We can use nvm’s default global packages from file while installing.

To do so, create a text file at $NVM_DIR/default-packages:

yarn

Now no more old versions of yarn 🎉, you’ll get the latest every time you install a new node version.

You can also explore the possibility of adding other npm packages that might interest you, such as @vue/cli or nuxi, for example.

Source:

Stack Overflow answer

Migrating to Cypress.js 13 is awesome DX

Fri, 01 Dec 2023 00:00:00 GMT

Today I’ve successfully migrated Cypress.js to v13.6.0 in two projects (one from v12.17.3, the other from v9.7.0), pretty much flawlessly and in a matter of minutes.

In a nutshell, what I did:

update to new version in package.json
yarn install
execute cypress open
Cypress recognizes the migration, and suggests using the migration tool; follow along with the three migrations steps

And … it’s done! Well pretty much. In my case, I also started to get some conflicts with Jest, which I had to fix.

Was such a nice experience using the migration tool, take a look at the amazing UI of one of the migration steps (replacing cypress.json with cypress.config.ts, because cypress.json is no longer supported):

Thank you Cypress team, great work! We know how difficult version management can be, especially in the JavaScript ecosystem 😅.

See more about Cypress version migration here.

[TIL] VSCode: Setting the correct TypeScript version

Fri, 01 Dec 2023 00:00:00 GMT

Important update: the settings mentioned below have since been deprecated in favor of new ones, as documented in VSCode’s package.nls.json file:

# Deprecated in favor of the two settings below
# "typescript.tsdk": "node_modules/typescript/lib",
# "typescript.enablePromptUseWorkspaceTsdk": true,
"js/ts.tsdk.path": "node_modules/typescript/lib",
"js/ts.tsdk.promptToUseWorkspaceVersion": true,

Mystery solved! I finally discovered why sometimes I’d notice inconsistencies in terms of the TypeScript errors between the terminal and VSCode.

This happened because I was using different TypeScript versions. By default, VSCode uses its own TypeScript version (typically a more recent version than the one used by the project).

I’d expect that the default would be for VSCode to use the project’s version, but it seems it doesn’t.

I suggest always having VSCode use the project’s version. This can be achieved by setting VSCode to use the TypeScript Workspace Version.

This will add "typescript.tsdk": "node_modules/typescript/lib" to .vscode/settings.json and should be committed to the repository, so that the entire team can benefit from it.

You can also add the setting to your own VSCode User Settings, so that this applies to any instance of VSCode you open:

"typescript.tsdk": "node_modules/typescript/lib",
"typescript.enablePromptUseWorkspaceTsdk": true,

Now the project is in charge (not the editor), no more confusing differences 🙌.

Note: Don’t forget to check with your team before pushing the .vscode folder to the repository, because if someone is already using a .vscode/settings.json file locally, this will cause conflicts. Unfortunately, at the moment of writing, it’s still not possible to extend settings. Alternatively, you can push a .vscode/settings.json.default to serve as reference, similar to what it’s done with env.default or env.sample, for example.

[TIL] Vue Router Navigation Guards

Thu, 30 Nov 2023 00:00:00 GMT

TIL about Vue Router’s Navigation Guards, which allow us to hook into the navigation process.

For example, beforeRouteLeave can be especially useful for alerting user about unsaved changes in a form and preventing accidental/undesired navigation.

[TIL] yarn link

Tue, 31 Oct 2023 00:00:00 GMT

TIL about yarn link.

Very useful for local development. The documentation says it best:

“For development, a package can be linked into another project. This is often useful to test out new features or when trying to debug an issue in a package that manifests itself in another project.”

When you’re done, don’t forget to run yarn unlink on the child package (to remove all symlinks) and yarn install --force on the parent project (to force the re-installation of dependencies and use the package from the project’s node_modules folder again).

[TIL] git: interactive rebase

Sat, 14 Oct 2023 00:00:00 GMT

Thanks P for sharing this.

Often referred to as the “Swiss Army Knife of Git”, in broad terms, interactive rebase is used to rewrite the commit history (such as edit, delete, and squash).

In our case, we needed to delete some commits in feature-branch-B, which were originally brought over from feature-branch-A. feature-branch-A ended up being discarded, and now we needed to delete those commits, so that they wouldn’t be included when merging feature-branch-B to main.

TIL how to perform a git interactive rebase:

Make sure main is updated
git checkout feature-branch-B
git rebase -i main: editor pops up with all commits listed: remove the lines (representing commits) you don’t want (or squash them, change commit message, etc.)
git push origin +feature-branch-B to force push the new shiny commit history

[TIL] The importance of font smoothing in WebKit and Firefox

Wed, 27 Sep 2023 00:00:00 GMT

TIL that the following CSS font smoothing rules, really make a difference on Apple OSs (Firefox and WebKit-based browsers):

body {
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

Take a look at the difference with and without here and here.

Even though there are some arguments against it I still think the pros outweigh the cons, so better to set these rules.

[BOOKMARK] A CSS reset for 2023

Sun, 24 Sep 2023 00:00:00 GMT

Came across the recent blog post A (more) Modern CSS Reset by Andy Bell.

It includes a set of CSS rules with sensible declarations for reducing browser inconsistencies.

Really like that it’s quite comprehensive (without being huge), as well as the author’s breakdown of each rule. Will consider using it (at least as a starting) in my future projects.

[TIL] Nuxt 2: nuxt generate fails silently and how to avoid it

Tue, 19 Sep 2023 00:00:00 GMT

TIL that in Nuxt 2, command nuxt generate as is, exits with code 0 (success) when errors are thrown during the execution (potentially skipping the generation of routes where error is manifesting).

To avoid unexpected issues, specially in production deploy pipelines, use flag --fail-on-error.

[TIL] iTerm2: click filename to open in VSCode

Tue, 12 Sep 2023 00:00:00 GMT

TIL that it’s possible to ⌘-click a file in iTerm2 and have it open in VSCode.

To enable, open Preferences -> Profiles -> Advanced -> Semantic History and select options Open with editor... and VS Code.

[TIL] git: how to merge a remote branch locally

Thu, 17 Aug 2023 00:00:00 GMT

TIL how to how to merge a remote branch (for example main) locally, which may be useful for when you’re working on a feature branch, main has been updated, and you’d like to include those updates in your branch:

git fetch origin main
git checkout a-local-branch
git merge origin/main
git push origin a-local-branch

[TIL] Firefox DevTools: request duration

Sun, 11 Jun 2023 00:00:00 GMT

TIL how to check the duration of a request (time from start of the request until the end of the respective response) in Firefox DevTools.

It can be specially helpful for performance analysis.

To display the Duration column in the network table toolbar, open up DevTools, select the Network tab, right-click the request table header (any column), and select Timings -> Duration:

Learn more about the Network request list.

[TIL] VSCode: configure auto format on save

Sun, 11 Jun 2023 00:00:00 GMT

TIL about VSCode project configurations to enable auto format on save.

This can be specially helpful in team projects configured with eslint and prettier, where you’re interested in enforcing code conventions and standards.

From the project root, create a .vscode/settings.json file with the following:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

When a project contributor checks out the project and is using VSCode (with eslint and prettier plugins installed) auto format on save will be enabled, based on the eslint and prettier rules configured.

[TIL] Firefox DevTools: how to persist logs on page navigation

Sat, 10 Jun 2023 00:00:00 GMT

TIL about a Firefox DevTools option, which allows to specify whether the request list and logs should be cleared or not on page navigation (or page reload).

It can be specially helpful while developing/troubleshooting.

The default is for requests and logs to be cleared, so to instead have them persist, open up DevTools, click the settings cog wheel, and select Persist Logs:

[TIL] JavaScript: directly chaining catch handler to await expression

Fri, 19 May 2023 00:00:00 GMT

TIL that it’s possible in JavaScript to directly chain a catch handler to an await expression:

await fetchProfile().catch((e) => handleFetchProfileError(e));

Note that this can be done outside (and without requiring) a try/catch block.

This can be specially useful when you’d want the execution to continue and/or treat the await expression individually (i.e., not only one single catch for a block of code).

Many thanks to all contributors in this Stack Overflow thread.

[TIL] Responsive HTML element without media queries

Fri, 19 May 2023 00:00:00 GMT

TIL that it’s possible in CSS to make an HTML responsive (automatically adapt to screen width), without having to use media queries:

<div class="outside-container">
  <div class="responsive-element">
    <p>I'm a paragraph!</p>
  </div>
</div>

.outside-container {
  border: 1px solid blue;
}

.responsive-element {
  border: 1px solid red;
  width: 100%;
  max-width: 580px;
  margin: auto;
}

This is achieved with the combination of width: 100%; and max-width: 580px;, where we’re saying “width be 100% of the parent’s width, but never exceed 580px”. Notice how the element with red border adapts when screen width changes:

I'm a paragraph!

Many thanks to @Ali_Developer05 for the tweet where I got this tip from, and which I’ve been able to use at work the very next day.

VSCode: Vue 2 or Vue 3 extensions per project

Mon, 08 May 2023 00:00:00 GMT

Up until Vue 2, Vetur has been the recommended VScode extension for Vue support.

Since the release of Vue 3 (which introduces first-class TypeScript support), the official recommendation is to use Volar/Vue Language Tools instead.

I’m currently working on multiple Vue.js projects (some Vue 2, some Vue 3), using the same VSCode installation.

As recommend, tried uninstalling Vetur and using Volar instead in some of the Vue 2 projects, but faced some (apparently) minor issues, such as this one, for example.

Since fixes to such issues required updates in the code (which could impact my colleagues’ dev environments), and having nothing to complain about Vetur, I’ve decided to keep using Vetur for Vue 2 projects.

To do so, I have both extensions installed globally, and disabled on a project-by-project basis accordingly:

if project is Vue 2, disable Volar in the project’s (current) workspace.
if project is Vue 3, disable Vetur in the project’s (current) workspace.

Credit goes to this Stack Overflow answer.

Update: also noticed that for ESLint to work properly, Vue 2 projects needed the VSCode ESLint extension pinned to version 2.4.2, while Vue 3 projects work fine with the up-to-date 3.0.10. Since a single VSCode installation can’t have two versions of the same extension active at once, I achieved this using separate VSCode profiles, one per Vue version, each with its own pinned ESLint version.

Vetur itself is also pinned, at 0.37.3, since it’s the legacy Vue 2 language-tooling extension and hasn’t seen further releases.

Also, for Vetur to actually handle formatting in Vue 2 projects, I had to set it as the default formatter for .vue files in my settings.json:

"[vue]": {
  "editor.defaultFormatter": "octref.vetur",
},

On the Vue 3 projects, formatting was instead handled by Prettier, configured in each project’s .vscode/settings.json:

{
  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit"
  },
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

There are probably better ways to handle this, with a more intentional separation of VSCode profiles and extensions per Vue version, but this is how I was able to get it working. I’m happy I no longer need to support Vue 2 projects, and I’m writing this down mostly so I can come back to it in case another Vue 2 project lands on my lap.

[TIL] JavaScript: renaming variables during object destructuring

Tue, 02 May 2023 00:00:00 GMT

TIL that it’s possible in JavaScript to rename variables at the moment of destructuring.

Let’s say you have an object user, previously fetched from an API, with snake_case property names.

However, you’d like variable names to be in lowerCamelCase.

You can do the following:

const { user_id: userId, age } = user;

Variable name is now userId.

[TIL] TypeScript type predicates

Fri, 28 Apr 2023 00:00:00 GMT

Type narrowing is the process by which a type is refined to a more specific type.

The TypeScript compiler does its best to narrow types using the existing JavaScript code.

TIL about TypeScript type predicates, a way to be more explicit and have better control over type inference.

First, we define a function whose return type is a type predicate:

function isAudio(content: Audio | Text): content is Audio {
  return (content as Audio).duration !== undefined;
}

We can now use isAudio to narrow the type of a variable we’re working with, allowing TypeScript from that point on to know the more specific type:

let content = getContent();

if (isAudio(content)) {
  content.play();
} else {
  content.render();
}

Resources:

GitHub Actions: how to skip PR status checks based on changed files

Mon, 24 Apr 2023 00:00:00 GMT

Let’s say you have a pull_request GitHub Action workflow that runs unit tests and end-to-end tests on every PR that targets branch main:

name: Test pipeline

on:
  pull_request:
    branches: [main]

jobs:
  run-unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

  run-browser-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

This is a valuable software development practice, because tests (assuming they are well designed and providing reasonable coverage) are running automatically on every PR, offering immediate feedback to developers about whether changes being included are breaking something or not.

You may have also opted to configure a branch protection rule for main, requiring status checks (in this case, tests) to pass before merging is allowed:

By using this configuration, the workflow’s jobs will be executed and reported in the pull request (visible in the Checks tab and near the merge button):

The downside of this setup is that tests will have to run and pass on each and every PR, even when changed files are not source code (such as README updates and documentation contributions).

In such cases, couldn’t the test executions be skipped, providing the ability to immediately merge the PR and spare (potentially billable) workflow execution time?

Let’s see how we can achieve this!

First, let’s make use of tj-actions/changed-files and add a new step in each job to get the list of changed files (excluding markdown files):

jobs:
  run-unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Get all changed file(s), excluding the docs
        id: changed-files-excluded
        uses: tj-actions/changed-files@v35
        with:
          files_ignore: |
            **/*.md

The output of this step can now be used in subsequent steps, so that they are executed only if changed files are not markdown:

- uses: actions/setup-node@v3
  if: steps.changed-files-excluded.outputs.any_changed == 'true'
  with:
    node-version: "16.x"

In this way, jobs will still execute with a success status (which is needed for PR checks), with individual steps themselves being skipped.

Please note that the setup above can probably be optimized to not require if to be included in all subsequent steps, but instead immediately interrupt the job and exit with status 0 (no errors).

Also note that there are most likely other ways to achieve this outcome, such as for example using fkirc/skip-duplicate-actions, but I have not explored them in detail.

Also note that in case you have status checks configured like we do in this example, in order to achieve this outcome, the intervention will have to be at the job-level (and not workflow-level).

How to fix deprecated GitHub Action chrisdickinson/setup-yq

Fri, 07 Apr 2023 00:00:00 GMT

Node.js 12 actions are currently being deprecated on GitHub Actions.

If you’re using chrisdickinson/setup-yq you’re probably encountering the following warning:

Node.js 12 actions are deprecated.
Please update the following actions to use Node.js 16: chrisdickinson/setup-yq@latest.

Since this project has not been updated to use Node 16, in order to fix do the following:

remove usage of chrisdickinson/setup-yq@latest, it’s no longer needed as yq is now part of ubuntu-latest
(if needed) update usage of command yq because it works in a different way on v4 (action uses v3)

[TIL] How to help browsers offer appropriate form autofill options

Fri, 07 Apr 2023 00:00:00 GMT

TIL about HTML attribute autocomplete, which allows to specify user agent/browser permissions for providing automated assistance in filling out forms (such as login credentials and credit card details), as well as guidance on the type of information expected in the respective form fields.

Resources:

[TIL] VSCode setup for Nunjucks

Tue, 14 Mar 2023 00:00:00 GMT

TIL how to setup VSCode for a better developer experience using Nunjucks.

Useful VSCode extensions:

ronnidc.nunjucks, for syntax highlighting;
okitavera.vscode-nunjucks-formatter, for template formatting;
eseom.nunjucks-template, for template syntax, template formatting, and snippets.

Also, don’t forget to enable Emmet for Nunjucks.

Resources

[TIL] just: command runner

Thu, 09 Mar 2023 00:00:00 GMT

TIL about command runner just, which can be used as an alternative to npm scripts.

Resources

[TIL] Vuex: how to commit a mutation for a specific namespaced module

Thu, 09 Mar 2023 00:00:00 GMT

TIL how to execute a Vuex mutation inside a namespaced module, from object Store.

This can be particularly useful to initialize state when using jest:

const store = createStore();

store.commit("AuthModule/setInitialData", initialData);

[TIL] Useful k3d and kubectl commands

Sat, 29 Oct 2022 00:00:00 GMT

Listing some useful k3d and kubectl commands I’ve been using lately.

k3d

Create cluster

k3d cluster create my-cluster

Create cluster with load balancer and respective port binding (useful for testing locally)

k3d cluster create my-cluster -p "80:30000@loadbalancer"

Create cluster without load balancer

k3d cluster create --no-lb

Create cluster with specified number of control planes and worker nodes

k3d cluster create my-cluster --servers 3 --agents 3

List clusters

k3d cluster list

Delete cluster

k3d cluster list

kubectl

List all supported resource types (useful to know which version to use when writing manifests)

kubectl api-resources

Get list of nodes in the cluster

kubectl get nodes

Apply resources specified in a manifest file

kubectl apply -f pod.yaml

Get Pods

kubectl get pods

Get Pod details (useful to know which image tag/version is running)

kubectl describe pod my-pod

Port bind Pod port to localhost port

kubectl port-forward pod/conversao-temperatura 8080:8080

Delete Pod

kubectl delete pod conversao-temperatura

Delete resources specified in a manifest file

kubectl delete -f pod.yaml

[TIL] Useful terraform commands

Sat, 29 Oct 2022 00:00:00 GMT

Listing some useful Terraform commands I’ve been using lately.

Initialize a working directory

terraform init

Create an execution plan with preview

terraform plan

Execute actions proposed in a plan

terraform apply

Format configuration files into a canonical format and style

terraform fmt

More about terraform fmt.

Extract the value of an output variable from the state file

terraform output

Destroy all remote objects managed by a particular configuration

terraform destroy

More about terraform destroy.

[TIL] TypeScript: How to define a type for objects with dynamic properties

Sat, 27 Aug 2022 00:00:00 GMT

TIL how to define a type for objects with dynamic properties. By this we mean an object that can have any number of properties, with unknown property names and values. However, we know what their types should be.

Let’s take a look at an example to make this clearer.

Let’s say we want to create a type to represent dictionary objects such as:

const dictionary = {
  hello: "olá",
  goodbye: "adeus",
};

In this case, we want TypeScript to help us enforce that both property name and property value are of type string.

We can use the Record<Keys, Type> utility type, like so:

type MyDictionary = Record<string, string>;

const dictionary: MyDictionary = {};

Now, if we try to set something like the following, TypeScript will signal an error and stop us:

// Type 'number' is not assignable to type 'string'.
dictionary.one = 1;

The Record<Keys, Type> utility type is a name alias for index signatures:

type MyDictionary = { [k: string]: string };

See:

[TIL] Cypress: How to run only one test inside a spec file

Fri, 26 Aug 2022 00:00:00 GMT

TIL a Cypress tip that can help improve efficiency when creating tests.

Let’s say you have a spec file with several tests. To avoid having to execute all the tests in the file, you can temporarily use it.only(, instead of it(.

Don’t forget to revert the change when you’re done, otherwise the other tests will not execute when they should (e.g., in a pipeline execution).

See more details in the documentation.

[TIL] Useful AWS CLI commands for S3 and CloudFront

Wed, 04 May 2022 00:00:00 GMT

Listing some useful commands I’ve been using lately for AWS S3 and CloudFront.

Amazon S3

List buckets

aws s3api list-buckets

Get bucket region/location

aws s3api get-bucket-location --bucket cdn-dev

Upload file

aws s3 cp static/logo.png s3://cdn-dev/logo.png

Amazon CloudFront

Get distribution id list

aws cloudfront list-distributions --output table --query 'DistributionList.Items[*].Id'

Check details of specific distribution

aws cloudfront get-distribution --id E2FXR8603J97N3

Create cache invalidation

aws cloudfront create-invalidation --distribution-id E2FXR8603J97N3 --paths "/*"

Check status of cache invalidation

aws cloudfront get-invalidation --id I23C6NJI4OQFFP --distribution-id E2FXR8603J97N3

[TIL] VSCode: Editing files remotely over SSH

Mon, 18 Apr 2022 00:00:00 GMT

TIL about this VScode extension.

It allows accessing and editing folder and files on any remote environment over SSH.

Even though this is a great productivity tool to have in my toolkit, it should not serve as an excuse for not learning more in-depth either nano or vim 🤓.

[TIL] K8s: Difference between ingress controller and service mesh

Sun, 17 Apr 2022 00:00:00 GMT

TIL about the difference between ingress controller and service mesh.

The former is responsible for managing traffic that flows into the the application (North-South traffic).

The latter is used to mediate and secure service-to-service communication within the cluster (East-West traffic).

[TIL] VSCode: How to save without auto formatting

Fri, 01 Apr 2022 00:00:00 GMT

TIL how to save a file on VSCode without auto formatting being applied: CMD + K S.

This can be useful in situations where one is working in a repository and is not interested in having a big file auto formatted, just for the sake of a trivial change.

[TIL] JavaScript: How to update the URL without page reload

Mon, 28 Mar 2022 00:00:00 GMT

TIL that it’s possible to programmatically set the URL in the browser’s URL bar without having the browser try to load it.

This can be useful, for example in the context of a SPA, for updating the URL when a certain component is rendered or after a certain user action takes place, for analytics purposes (e.g., Google Tag Manager requires this for the History Change trigger):

window.history.replaceState(null, "", "/verified");

See more details in the documentation.

[TIL] K8s AWS: How to check Pod logs

Fri, 11 Mar 2022 00:00:00 GMT

TIL how to check Pod logs on a K8s cluster running on AWS EKS.

Requirements:

K8s cluster on AWS EKS
AWS CLI
kubectl

First, connect to the AWS account. Here, I’m doing it using Named Profiles:

export AWS_PROFILE=ramigs-dev

Update the context on your local .kube/config file:

aws eks --region eu-north-1 update-kubeconfig --name k8s-cluster

Confirm that your connection is working, by requesting the list of namespaces:

kubectl get ns

Take note of the namespace tho which the pod you want to check belongs to.

Get the list of pods:

kubectl get pods -n namespace

Check logs:

kubectl logs -f pod-name -n namespace container-name

[TIL] GitHub Actions: how to get execution status of a specific job

Wed, 09 Mar 2022 00:00:00 GMT

TIL that in GitHub Actions, one can use needs.job.result to get the execution status of a specific job.

Let’s say you have a job named invalidate-cache. You can then, in another job, check its execution status, like so:

if: needs.invalidate-cache.result == 'success'

[TIL] Vue: parsing input value as number

Mon, 07 Mar 2022 00:00:00 GMT

TIL about the Vue modifier .number on v-model, which can be used to parse the value of an <input> element as number (instead of as string):

<input v-model.number="searchFilters.amount" />

typeof searchFilters.amount will be number.

[TIL] Node: specifying the versions a package works on

Sat, 05 Mar 2022 00:00:00 GMT

TIL about configuration engines in package.json, which can be used as a best-practice for explicitly specifying under what versions of node and npm a package can be installed:

  "engines": {
    "node": ">= 6.0.0",
    "npm": ">= 3.0.0"
  },

Note:

This applies only to packages and is related to the moment a package is installed with npm install as package (e.g., from one directory up), and not npm install inside a project (which installs the dependencies of the project).

See:

[TIL] How to parse flags passed to a bash script

Tue, 01 Mar 2022 00:00:00 GMT

TIL how to parse flags passed to a bash script, using the built-in function getopts.

Let’s say you have a script named maintenance.sh, to which you’d like to pass some flags:

-e
-d
-f filename

These flags can be parsed in the script, like so:

while getopts edf: flag
do
    case "${flag}" in
        e) echo "Got flag -e";;
        d) echo "Got flag -d";;
        f) echo "Got flag -f with respective option ${OPTARG}";;
    esac
done

Notice in the arguments of getopts that f is the only flag that is followed by :, which is used to indicate that the flag is followed by a respective value.

Script can then be called as sh maintenance.sh -e or sh maintenance.sh -e -f file.json, for example.

See:

[TIL] Docker: How to execute without sudo

Tue, 22 Feb 2022 00:00:00 GMT

On certain Linux distributions, such as Ubuntu, the docker command can only be executed by the root user or by a user in the docker group.

For the sake of convenience, to not have to type sudo every time, add your user to the docker group, as so:

sudo usermod -aG docker ${USER}

Source:

How To Install and Use Docker on Ubuntu 20.04 - Brian Hogan

[TIL] Cypress custom selector commands

Mon, 21 Feb 2022 00:00:00 GMT

You may already know that it’s a good practice in Cypress to use data-* attributes (e.g., data-test, data-cy) for targeting elements.

TIL about two super useful custom selectors that can be added, to avoid always having to write [data-test="sign-up"]:

getBySel yield elements with data-test attribute that matches a specified selector
getBySelLike yield elements with a data-test attribute that contains a specified selector

To use these selectors in your tests, first add them as commands:

Cypress.Commands.add("getBySel", (selector, ...args) => {
  return cy.get(`[data-test=${selector}]`, ...args);
});

Cypress.Commands.add("getBySelLike", (selector, ...args) => {
  return cy.get(`[data-test*=${selector}]`, ...args);
});

Then, use them as so:

cy.getBySel("sign-up").click();

cy.getBySel("sign").click();

Source:

cypress-realworld-app

[TIL] How to backup a GPG key pair

Sun, 20 Feb 2022 00:00:00 GMT

TIL that after generating a GPG key pair, one should always backup the following:

key pair itself: gpg -o private.gpg --export-options backup --export-secret-keys my-key
revocation certificate: gpg --output revoke.asc --gen-revoke my-key
key passphrase: should be stored separately from the above, ideally on a password manager

Always consider carefully your security requirements for decisions regarding redundancy and backup storage location (ideally on offline media).

For more information, please check:

[TIL] Connecting Adminer to an Azure MySQL database

Sun, 13 Feb 2022 00:00:00 GMT

If you’re having SSL-related issues when connecting Adminer to an Azure MySQL database, try out this very helpful answer, with the following nuances:

no need for client key or client certificate, i.e., discard environment variables DB_SSL_KEY, DB_SSL_CERT and the respective volumes
use only DB_SSL_CA and its respective volume with the certificate provided by Azure (see more details here)

Note: these instructions assume you have Adminer running as a Docker container, but the same arguments being passed to the Adminer plugin login-ssl should apply nonetheless.

[TIL] git: how to rollback in trunk based development

Sun, 13 Feb 2022 00:00:00 GMT

TIL how to rollback when working in a trunk based development model.

“A source-control branching model, where developers collaborate on code in a single branch called ‘trunk’ (main or master, in Git nomenclature), resist any pressure to create other long-lived development branches by employing documented techniques. They therefore avoid merge hell, do not break the build, and live happily ever after.” - Trunk Based Development

Let’s say you’ve deployed branch main and discovered that you need to rollback the deploy. You can either:

leverage PRs/short-live feature branches, by directly deploying the branch you want to rollback to
if you want to rollback to a specific commit hash which is not HEAD of any of the existing branches, create a new branch from this specific commit git checkout -b rollback-2022-02-13 ad3da78 and deploy that branch

I’ve also learned that a git commit hash is a cryptographic checksum that is calculated from the state of the repository (including the hash of all the files in the repository, the hash of the previous commit, the current date and time, etc.), and contrarily to what I previously thought, not related to individual files.

[TIL] How to fix error CORS OPTIONS Missing Allow Header

Sat, 12 Feb 2022 00:00:00 GMT

TIL how to fix errors such as OPTIONS https://id.dev.nordikcoin.com/auth/questionnaire CORS Missing Allow Header and Reason: header 'authorization' is not allowed according to header 'Access-Control Allow-Headers' from CORS preflight response., which tend to manifest specially when working in local development.

Header Access-Control-Allow-Headers is a response header to a preflight request (OPTIONS).

These issues can be fixed from the server side either by setting header Access-Control-Allow-Methods: GET,PUT,POST,DELETE,PATCH,OPTIONS, Access-Control-Allow-Headers: authorization, or both.

From Postman the request may succeed, but only because Postman is more permissive than the browser and does not send the preflight request OPTIONS.

[TIL] Email delivery in Auth0

Thu, 10 Feb 2022 00:00:00 GMT

TIL that Auth0 does not guarantee the instant delivery of emails that are part of Auth0’s authentication workflows, when using their default internal email provider.

It’s necessary to configure an external email provider, such as Amazon SES, to route all emails through a high-volume email service.

[TIL] logrotate: how to prevent deletion of old logs

Thu, 10 Feb 2022 00:00:00 GMT

TIL that in a logrotate configuration file, with setting daily configured, if rotate is not explicitly set, old rotated log files will be deleted (after one rotation, it seems).

To avoid this, set rotate n, where n is the number of logs to be kept.

Haven’t found a way to completely disable deletion. Common practice seems to be setting rotate with a high number. See:

Example of the configuration file I’m referring to:

/nginx-logs/access.log
/nginx-logs/error.log
{
    daily
    rotate 30
    dateext
    dateformat .%Y-%m-%d
    extension .log
    sharedscripts
    compress
    postrotate
      sudo docker kill --signal=USR1 nginx
    endscript
}

[TIL] git: multiple line commit message

Wed, 09 Feb 2022 00:00:00 GMT

TIL how to commit with multiple line commit message in git from the command line:

$ git commit -m 'line 1
line 2
'

The use of single quotes ' instead of double " is what does the trick here.

[TIL] Style Editor in Firefox Developer Tools

Sun, 06 Feb 2022 00:00:00 GMT

TIL about the Style Editor in Firefox Developer Tools and how useful it can be to quickly view and edit all the stylesheets associated with a page. It allows also to create/import new ones and apply them to the page.

It can be specially helpful in situations where one is not able to run a project locally and only needs to work on the CSS, or when the project does not have Hot Module Replacement.

[TIL] git: moving unstaged changes to a new branch

Sat, 05 Feb 2022 00:00:00 GMT

TIL that in git, it’s possible to directly move unstaged changes and switch to a new branch, using command git switch -c new-branch.

Very useful when one forgets to create a new branch and starts to do some work on the mainline branch.

Found on this CSS-Tricks article.

[TIL] Difference between data streaming tools and message brokers

Sat, 05 Feb 2022 00:00:00 GMT

TIL about the difference between data streaming processing tools and message brokers. The former (e.g., Apache Kafka) is tailored for dynamic data being generated on a continual basis. The latter (e.g., RabbitMQ) is used to mediate communication among applications in distributed environments (microservices).

When designing a solution, it’s important to carefully consider the requirements, in order to choose the right tool for the job.

[TIL] Nuxt: hook created is executed when building as static

Fri, 04 Feb 2022 00:00:00 GMT

TIL that in Nuxt, Vue’s lifecycle hook created is executed when building a static site with generate.

For strictly client-side purposes, use mounted.

[TIL] Linux commands: recursive options instead of wildcards

Wed, 02 Feb 2022 00:00:00 GMT

TIL that in commands such as cp, scp, and zip, it is preferable to use the command’s native recursive options (e.g.,-r, -R) instead of wildcards (e.g., *). The reason is to avoid unexpected errors, such as -bash: /usr/bin/zip: Argument list too long.

[TIL] msmtp: sending emails from the command line

Wed, 02 Feb 2022 00:00:00 GMT

TIL about a very straightforward to use tool called msmtp, which allows sending emails from the command line and bash scripts.

Follow this guide for instant results.

[TIL] mv and cp file permissions

Sat, 29 Jan 2022 00:00:00 GMT

TIL that mv preserves file permissions, but cp does not.

See Moving files on Linux without mv .

Load testing with Artillery

Fri, 01 Oct 2021 00:00:00 GMT

This is the story about how my team got to know and use Artillery to load test the backend (and database) of the application we’re working on.

I’ll begin by giving a bit of context on the challenge that led us to need load testing and Artillery as the right tool for that.

I’ll then provide a brief overview on what Artillery is and how to use it to write and run load tests. I’ll also be sharing some of the insights we’ve learned along the way, plus some very useful Artillery features and testing strategies.

The challenge

So, recently we got some really good news from our product managers. The first iteration of our application in production has been a success, and as a result, new users are expected to be onboarded soon.

This means we need to make sure our application and infrastructure will be able to scale accordingly, as the number of concurrent users is estimated to increase by a factor of 50 and the database size to grow by a factor of 10.

Is our current infrastructure able to handle the expected traffic increase? How will performance be affected?

Instead of second-guessing, we decided it would be better to rely on concrete metrics that would help us make better-informed decisions.

Load testing

At this point, it was clear that we needed a tool to load test the application. After researching and gathering some in-house positive feedback, we opted to go with Artillery.

Our application is deployed on a virtual private server using Docker containers, and follows a common architecture consisting of three main components: frontend (Nuxt.js), backend API (.NET Core C#), and database (MySQL). In front of everything we have nginx serving as a reverse proxy.

Even though Artillery is more specifically tailored for backend testing, Artillery’s HTTP testing is ultimately accomplished by sending HTTP requests to a URI and checking the responses’ status and latency.

The way our application is set up allows us to load test the entire stack (including frontend and nginx), since all requests go through nginx before being dispatched to and handled by @nuxtjs/proxy. This works great for us, as it makes our load testing more closely resemble real user behavior.

In any case, even if your application is not set up in a similar way, but you’d still like to test other components of your stack, Artillery’s extensibility (through “hooks”, as we’ll see later down the article) allows you to introduce further logic in your tests (e.g., HTTP requests to the frontend).

Artillery

Artillery is an open source Node.js load testing tool. It’s designed to test the reliability and performance of backend services. It operates by simulating user behavior, allowing developers, test engineers, and SREs to verify how their backend services and infrastructure handle traffic spikes and sustained increases in workload.

Some of its key features include:

emulation of advanced (complex) user behavior
extensive protocol support (HTTP, Socket.io, WebSockets + others via plugins)
writing tests in a declarative style (YAML)
integration with external monitoring/observability services (e.g., Datadog, Honeycomb)
extensibility and customization (JavaScript)
official Docker image available

Test specification

An Artillery test script is a YAML file containing one or more scenarios. A scenario is a sequence of actions (e.g., HTTP requests) that a virtual user goes through. Here’s an example:

scenarios:
  - name: "login + home page (list products)"
    flow:
      - post:
          url: "/users/login"
          json:
            username: "{{ $processEnvironment.VIRTUSER_USERNAME }}"
            password: "{{ $processEnvironment.VIRTUSER_PASSWORD }}"

      - post:
          beforeRequest: ensureSessionCookieSet
          url: "/users/role"
          json:
            selectedRole: "CUSTOMER"

      - get:
          beforeRequest: ensureSessionCookieSet
          url: "/services"

A really cool feature we were pleasantly surprised to find: Set-Cookie support, which allows out-of-the-box session-based cookie authentication.

In the snippet above you may have also noticed beforeRequest. It’s an Artillery “hook”. “Hooks” allow custom JavaScript logic to be attached to the lifecycle of scenarios and individual requests.

Other attributes we’ve found to be very useful:

weight: which can be used to specify the probability of each scenario being executed by a new virtual user;
think: which can be used to more realistically mimic human user behavior, by pausing the execution for N seconds between requests.

Test configuration

Besides section scenarios, a test script is composed of another main section: config. This is where the test configuration (target URIs, environments, custom code, etc.) is defined:

config:
  timeout: 2
environments:
    staging:
      target: "https://staging.my.app"
      phases:
        - duration: 120
        arrivalRate: 10
    production:
      target: "https://my.app"
      phases:
        - duration: 1200
        arrivalRate: 20

Under phases we can find the core load phase attributes which determine how Artillery will generate new virtual users during test execution.

For each environment a test may execute one or more phases. Generally, you’ll find that test a may begin with a warm-up phase, followed by a ramp-up phase, and finally end with a maximum load phase.

One feature that we are not currently using (but planning to in the near future) is setting up success conditions. This enables Artillery to return with non-zero if a certain condition (response time or error rate) is not met, which may be very useful for integrating Artillery into CI/CD pipelines. Here’s an example:

config:
  ensure:
    maxErrorRate: 1

Finally, after you’ve executed the test, you may also examine the results visually, by uploading the JSON results file to the Artillery report viewer.

Wrapping up

We had a great experience using Artillery. Excellent documentation, straightforward to set up and start running tests right away.

By combining Artillery’s test results with data from an internal observability service, we were able to confirm that the higher potential for performance bottlenecks comes from the database.

We’ve found it very useful to perform several tests using different strategies (warm-up, ramp-up, and maximum load), mixing up different phase attributes and respective values, to really understand how the current infrastructure responds.

We combined all the results in an Excel sheet which we then examined to derive the points of inflection (in terms of number of concurrent users and database size) at which performance and user experience start to go below thresholds we’ve defined as acceptable.

As a next step, we’ll be adding more computational resources to the database, by migrating it to a managed database service, as we continue to use Artillery to monitor the performance improvements that result from each update we implement.

Resources

Some great resources that helped us along the way:

How to reliably clear a Linux log file

Tue, 20 Jul 2021 00:00:00 GMT

Have you ever found your Linux server running out of disk space, only to discover a single log file taking up gigabytes of storage?

Well, I have 😅. Recently, in one of the servers I’m managing, I detected a 5 GB (and steadily increasing) /var/log/maillog file.

Turned out to be an issue with an incomplete removal of a hosting control panel tool that was causing the log file to be written to every second.

After fixing the issue that was causing this non-stop growth of the log, I began looking for a way to reliably get the disk space back.

I had a sneaky suspicion that simply rm’ing and recreating the file would not be such a great idea.

Turns out my hunch was right. My investigation led me to learn that when a process opens a file - either for read or write, it’s actually holding a handle to that file’s inode.

inode is a Linux filesystem data structure that’s assigned to each created file. Its purpose is to store various metadata about the file.

If the file gets deleted by a different process, this may cause other programs that reference that inode to malfunction. Also, the disk space is not freed up until processes close their handle on it.

Moreover, file ownership and permissions will most likely get messed up, as the newly created file won’t have the same inode as the deleted file.

File truncation

Ok, so deleting and recreating the log file is not a viable solution. What can we do instead to free up that disk space?

We need the file’s inode to remain the same, so we’ll truncate its contents without deleting it.

Manually editing the file is not clean solution a at all. What if the file gets written to by another process while we’re editing it?

To truncate the log file we can rely on Linux’s standard output redirect operator to redirect the output of nothing to the file:

> /var/log/maillog

Or, we can use command truncate, which truncates the file to a precise length in bytes:

truncate -s 0 /var/log/maillog

Truncating a file is also much faster than deleting the file, recreating it, and setting the correct ownership and permissions.

Log rotation

Before we wrap up, it’s important to bring up the topic of log rotation.

In a more critical/production scenario, you may need to store the logs for archive. Log rotation helps us achieve this, by renaming and compressing old log files, making them ready to be backed up. logrotate is the Linux tool that achieves precisely this.

After you’ve backed up a rotated log file, it’s fine to just remove it and gain that disk space back.

References

Some resources that helped me write this article:

Automating database backups

Sat, 12 Jun 2021 00:00:00 GMT

We already know that backups (and even more so, restores) are of paramount importance.

The hard work we put into our projects must be safeguarded. In the context of teams and organizations this necessity becomes even more pronounced.

Nowadays, features such as codebase backup and version control are assumed as given when we use a git-based cloud provider, such as GitHub or GitLab.

Depending on how critical to the business an application is, you may want to consider further measures in assuring the codebase is backed up with appropriate redundancy.

But what about the database, and, more specifically, the data that it stores?

Once an application goes into production, its generated data has an incommensurable value. Loosing it is a scenario that an organization simply can’t afford.

On the occurrence of hardware faults, software faults, or human errors, disaster recovery plans are crucial to ensure that organizations can respond quickly to minimize any negative effects on business operations. In the context of databases, the ability to recover is fundamentally defined by ability to restore.

In this article, we’ll describe the implementation of an automated database backup process. It will execute daily, taking a snapshot of a production database, encrypting it, and securely sending it to a remote backup storage server.

Infrastructure and tools

As a general rule of thumb, before implementing a custom solution, one should investigate if the problem has already been solved.

Although many times we may find that it has been solved already, a solution that perfectly fits our requirements does either not exist or the effort to customize it is bigger than just implementing a solution of our own.

This was the case when I was asked to implement this automated database backup procedure. I didn’t find anything matching the specificities of our setup, so I had to go with a custom solution.

Let’s now examine the following diagram, an overview of the infrastructure and tools involved in the setup:

We’re working with two Linux servers:

the production server, where the database is running
the backup server, where database backups are stored

On the production server, we have a MySQL database running inside a Docker container.

Docker is an awesome containerization tool that helps standardizing development and deployment, by packaging applications and their dependencies.

On the same production server, we also have a cron job, configured to run a shell script that takes a snapshot of the database (including all the data it contains) and sends it to the backup server via SSH.

cron is a time-based job scheduler for Unix-like computer operating systems.

SSH is the de facto standard for secure remote access and data exchange between a client and a server. SSH is a vast subject. Here you can find information on how to configure it properly and manage its keys.

The purpose of this article is not to serve as a step-by-step guide (although you can pretty much use it as such) - but more as a general description of how the procedure was implemented in a real production setting, so that you can adapt it to your specific setup.

Backup script

Before executing any procedure in production, always make sure to test it beforehand in a development/staging environment.

Let’s now examine the production server shell script /root/database-backup/db-backup-production.sh. This file is the core of the backup procedure. When executed, it will access the Docker container and export a database snapshot, zip it, encrypt it with GPG, and securely copy the resulting file to the backup server.

cd /root/database-backup

today=$(date +"%Y-%m-%d")
timestamp=$(date +%s)

printf "Starting backup %s %s\n" $today $timestamp

docker exec container_database_1 mysqldump -u root --password=password123 --events --routines --triggers bd > backup_db_${today}_${timestamp}.sql

zip backup-db_${today}_${timestamp}.zip backup_db_*
gpg -c --batch --passphrase pass123 backup-db_${today}_${timestamp}.zip
mkdir -p backups
scp backup-db_${today}_${timestamp}.zip.gpg backup-repo-host.com:~/database-backups

printf "Backup completed!\n"
printf "\n"

This script is not supposed to be executed directly. Instead, we’ll rely on a secondary script /root/database-backup/run-db-backup-production.sh that will allow us to have visibility over the history and status of executions, by appending the execution outputs to a log file every time the procedure runs. These are the contents of this script:

cd /root/database-backup
sh db-backup-production.sh &>> log.txt

The backup procedure can be executed with two modes of operation:

manually, on-demand
automatically, scheduled to run at fixed times, dates, or intervals

Manual backup

To run the backup procedure manually, just execute the script:

sh run-db-backup-production.sh

Look into file /root/database-backup/log.txt for details on the execution outputs.

Scheduled backups

To have it run regularly, we’ll rely on cron.

Let’s configure a cron job to run everyday at 10 PM. To do that, execute the command crontab -e and add the following entry:

0       22       *       *       *       /bin/sh /root/database-backup/run-db-backup-production.sh

Restoring a backup

A backup has no value if we can’t restore it.

“Nobody wants backup, everybody wants restore.” - The Admin Zen

To restore a backup, follow these steps:

Access backup server

Log in to the backup storage server, navigate to the backup folder and select the GPG file backup-db_${date}_${timestamp}.zip.gpg of the snapshot you want to restore.

Copy

Copy it to the server where the database is running, using a secure method such as scp.

Decrypt

Decrypt the GPG file using the following command gpg --batch --yes --passphrase pass123 backup-db-01-21_1611250508.zip.gpg. The decrypted zip file will be written to the same folder.

Unzip

Unzip the file that resulted from the previous step, using unzip or any other archive tool at your disposal.

Restore database

Access the web interface of the database content managing tool you’re using (e.g., phpMyAdmin, Adminer) and run the SQL file that resulted from the previous step. Alternatively, if you don’t have a content managing tool installed for your database, you can also execute the SQL file through the command-line.

Verify restore

Confirm that the SQL script executed without errors and that the database has been created and populated. Also, make sure to verify that client apps that use the database continue to work as expected.

Conclusion

And, we’re done 💪.

Thank you for reading this far!

We’ve discussed the importance of regular database backups and how to automate them.

As in any process, there’s always room for improvement. The next features I’d like to implement:

Email notifications, specially in the case of failure.
Secure password management, that would allow removing database and GPG passwords from the main script. This article may be a good starting point.

Feel free to share any comment or suggestion by opening a PR on this article.

Strapi Hooks

Sat, 06 Feb 2021 00:00:00 GMT

(This article was originally published on strapi.io).

Hooks are one of the main built-in developer interfaces that we can use to customize and extend Strapi’s default functionality.

In this article, we’ll review and compare the three different types of Strapi hooks - describing and summarizing each type’s method of implementation and common use cases.

To follow this article, although not required, a basic familiarity with Strapi will definitely help better understand the use cases and code snippets. Nevertheless, this is not a step-by-step guide, so feel free to skim through or just go directly to the hooks section you’re looking for.

Let’s begin.

Content-Type Hooks

If you’re familiar with Strapi, you most likely already know what a Content-Type (or Model) is. A Content-Type is a JSON representation that is used to specify the underlying database structure of a content entity we want to store in Strapi’s database.

The first type of hooks we’ll examine are lifecycle hooks. These hooks allow us to extend Strapi’s default Content-Type functionality, by introducing custom code that will run whenever (before or after) a query is executed over a Content-Type - no matter if that’s done through the Admin Panel, an API call, or the execution of custom code that uses default queries.

“When you are building custom ORM specific queries the lifecycles will not be triggered. You can however call a lifecycle function directly if you wish.” - Strapi Developer Documentation

Use Case Examples

Lifecycle hooks are ideal for when you’d want to automatically trigger an action whenever Strapi content is queried or updated.

Lifecycle hooks can be used, for instance in an e-commerce app, to send an email notification or clear a CDN cache, when a new product is added to the store.

How to Implement a Content-Type Hook

To create a Content-Type lifecycle hook, first, you’ll have to determine to which model and to which query you would like to attach the hook. Here’s the list of the available default Strapi queries:

find: Returns a list of entries matching Strapi filters.
findOne: Returns the first entry matching some basic parameters.
create: Creates an entry in the database and returns the entry.
update: Updates an entry in the database and returns the entry.
delete: Deletes an entry (or multiple entries at once) and return its value before deletion.
count: Returns the count of entries matching Strapi filters.
search: Returns entries based on a search on all fields allowing it.
countSearch: Returns the total count of entries based on a search.

For each of the previous events, you can configure the hook to run before or after the event is executed. To do so, capitalize the first letter of the event name and prefix it with before or after.

You can now set a lifecycles key in the model file ./api/{apiName}/models/{modelName}.js with its respective lifecycle hooks.

Going back to the previous e-commerce app example, this is how a Product lifecycle hook that sends an email notification every time a new product is created could look like:

module.exports = {
  /**
   * Triggered before user creation.
   */
  lifecycles: {
    async afterCreate(data) {
      await strapi.plugins['email'].services.email.send({
        to: 'customers@my-store.io',
        from: 'noreply@my-store.io',
        subject: 'New Product Available!',
        text: 'Check out this amazing new product :)',
      });
    },
  },
};

Server Hooks

The second type of hooks - server hooks - allow us to add functionality to Strapi’s core.

When the Strapi instance boots, server hooks are loaded into the global object, becoming therefore usable anywhere in the application.

Use Case Examples

By far, the most common application of server hooks is third-party service/API integration.

Check out some of the hooks made available by the community:

strapi-hook-algolia: This hook allows you to use Algolia as a service in Strapi strapi.services.algolia.
strapi-hook-magento: This hook allows you to use the Magento 2 Rest API with Strapi.
strapi-hook-twitter: This hook allows you to use the Twitter API with Strapi.
strapi-hook-allegro: This hook allows you to use Allegro Rest API with Strapi.

The docs provide a detailed guide - using a GitHub client as an example - on how to integrate a third-party client in Strapi.

A pretty common development pattern of a server hook is to have it run an initialization function when the server boots, and then expose its functionality via methods made available either in strapi.services or strapi.hook.

As a result of being available in the Strapi global object, a server hook may also, for instance, be combined with a lifecycle hook, allowing for even further custom functionality.

How to Implement a Server Hook

The code of a server hook goes inside a file named index.js, and should follow the structure below:

module.exports = strapi => {
  const hook = {
    /**
     * Default options
     */
    defaults: {
      // config object
    },

    /**
     * Initialize the hook
     */
    async initialize() {
      // Merge defaults and config/hook.json
      const settings = {...this.defaults, ...strapi.config.hook.settings.**};

      // await someAsyncCode()
    },
  };

  return hook;
};

A server hook can be loaded either from a node module or from the local hooks folder (./hooks) in the project.

Every folder that follows the pattern strapi-hook-* and is located in the ./node_modules folder will be mounted into the strapi.hook object.

Every folder that’s inside the ./hooks folder will also be seen as a hook and mounted in the strapi.hook object.

No matter the location from where it is loaded, for a hook to run at the instance boot, it needs to be enabled and configured in your Strapi app. The ./config/hook.js file is where we enable the hook, alongside any optional custom settings:

module.exports = {
  settings: {
    'hook-name': {
      enabled: true,
    },
  },
};

Let’s now examine the implementation specificities of each server hook location.

Node Module Hook

The node module approach is useful if you’d like to publish the hook as an npm package, so that it can be easily shared across multiple projects, and make use of all the features npm provides.

A node module hook requires the following folder structure:

/strapi-hook-[...]
└─── lib
     - index.js
- LICENSE.md
- package.json
- README.md

The index.js file is the entry point to the hook. It has to follow the structure of the index.js example above.

Local Hook

A local hook is a server hook that is imported directly from the ./hooks folder at the root of your project, without having to be installed through npm. It’s useful for project-specific hooks that won’t be reused in other Strapi projects.

To add a local hook to your project, create a folder with the name of the hook and a index.js file inside it:

/project
└─── admin
└─── api
└─── config
│    - hook.js
└─── hooks
│   └─── strapi-my-local-hook
│        - index.js
└─── public
- favicon.ico
- package.json
- server.js

Webhooks

Finally, we get to the last type of hooks: webhooks.

Sunny Hsiao wrote an article specifically about webhooks, going more in-depth than I will in this general overview, so I recommend you check it out if you’d like to dive deeper into webhooks.

Webhooks are not exclusive to Strapi. An application that implements webhooks is able to notify other applications as a certain event occurs in its context.

Technically, webhooks are typically implemented as HTTP POST requests.

Use Case Examples

A webhook can be a great tool to notify third-party providers to run CI/CD operations, such as build or deploy.

Recently, I’ve come across a very interesting use case in this Strapi webinar by Charles Ouellet, where a webhook is used to rebuild a Nuxt static site whenever the content is updated in Strapi.

How to Configure a Webhook

The webhook configuration panel is accessible from the Admin Panel, from the sidebar, in Settings -> Webhooks.

To create a new webhook, click the Add new webhook button in the top-right of the panel:

Next, you’ll need to fill in the Create a webhook form with the following fields:

Name
URL
Request headers
Trigger events

By default, Strapi provides a set of events that can trigger a webhook. These events are related to either a Content-Type entry or to a media asset.

For Content-Type entries, we have the following events available:

create: When an entry is created.
update: When an entry is updated.
delete: When an entry is deleted.
publish: When an entry is published (available when draft and publish is enabled on the Content-Type).
unpublish: When an entry is unpublished (available when draft and publish is enabled on the Content-Type).

For media assets:

create: When a media asset is created.
update: When a media asset is updated.
delete: When a media asset is deleted.

Here’s how a sample webhook payload looks like:

{
  "event": "entry.create",
  "created_at": "2020-01-10T08:47:36.649Z",
  "model": "address",
  "entry": {
    "id": 1,
    "geolocation": {},
    "city": "Paris",
    "postal_code": null,
    "category": null,
    "full_name": "Paris",
    "created_at": "2020-01-10T08:47:36.264Z",
    "updated_at": "2020-01-10T08:47:36.264Z",
    "cover": null,
    "images": []
  }
}

You can also set additional webhook global header configurations. This is done in the ./config/server.js file and will be applied to all the outgoing webhooks:

module.exports = {
  webhooks: {
    defaultHeaders: {
      'Custom-Header': 'my-custom-header',
    },
  },
};

If it’s an Authorization header, you can use Authorization: 'Bearer my-very-secured-token', instead. This will allow the notified applications to read the header and appropriately handle verification and authentication.

Besides the explicitly configured headers, Strapi will also add another header named X-Strapi-Event, where the corresponding value is the name of the event type that was triggered.

Conclusion

As we’ve seen, hooks are a great tool for customizing and extending Strapi’s core functionality.

We’ve examined the three different types of Strapi hooks, presenting the main use cases for each type, when to use one or another, and how to implement them.

I’d like to thank malgamves for reviewing this article, as well as MattieBelt and yringler for the use case suggestions.

If you have any cool use cases of Strapi hooks you’d like to share, you’re very welcome to join the ongoing conversation in the forum.

Strapi Authentication in Nuxt.js

Tue, 25 Aug 2020 00:00:00 GMT

(This article was originally published on strapi.io).

This is a step-by-step guide on how to implement Strapi-based authentication in a Nuxt.js app.

Here’s a preview of what we’re setting to achieve:

In essence, authentication is the process through which a website or app verifies the identity of its users.

As the gatekeeper to an app, authentication needs to be secure and reliable. After all, it deals with user information, potentially the most critical data in an app.

Implementing a secure authentication mechanism from scratch is hard and can quickly become cumbersome. Where do you save the user data? Should you roll out a database and model the user content type? What about registration, login, and password reset?

But it doesn’t end there. How to securely deal with passwords? Hashing and all that fun stuff 😵.

That’s a lot to think about, when you just want to dive into the core functionality of the app you’re developing!

You could build your own authentication mechanism, but do you really need or want to? I’d say, better to rely on something that’s already built and thoroughly tested before.

Strapi is an awesome open source Node.js headless CMS, backed by a large, active community.

One of the cool things about Strapi is that it provides authentication right out of the box, with built-in admin and user content types and API endpoints to perform the main authentication operations.

On the frontend, we’ll be using Nuxt.js and relying on Nuxt’s Auth Module, which is the official zero-boilerplate authentication module for Nuxt.js.

So, in this article, we’ll be building two projects:

Backend: Strapi app to store and manage users
Frontend: Nuxt app that will use Strapi’s API for authentication purposes

The source code for both projects can be found on GitHub:

Strapi’s authentication scheme is based on email/username and password credentials, along with JWT tokens. Upon successful authentication, the response will return a JWT authentication token that will be added to subsequent API requests. The Auth Module will conveniently help us manage this workflow.

We will also be implementing some basic authorization features, such as restricting certain pages to only logged in/out users.

This guide builds on top of Chimezie Enyinnaya’s awesome work, adapting it to Strapi’s specific use case, and adding also the following features:

Email confirmation for registration
Password reset
Token expiration strategy

I won’t go into detailed explanation at every step. Instead, I’ll focus on Strapi and the new functionality. For everything else, I recommend you refer to Chimezie’s tutorial and the Auth Module documentation.

Pre-requisites

To follow this tutorial, make sure you have Node.js installed:

Node.js 12.x
npm 6.x

Although not required, a basic knowledge of Strapi, Nuxt.js, and JWT fundamentals is recommended.

Disclaimer: this tutorial was written based on Strapi 3.0.1 (stable release) and Nuxt.js 2.12.2. It should work on different versions too, but you may need to make some adaptations here and there.

Let’s get started!

Install Strapi

First things first, we begin by creating a Strapi project:

npx create-strapi-app strapi-users --quickstart

We’ve used the --quickstart flag that installs Strapi with default settings. It also tells Strapi to use SQLite as the database engine and automatically run our application.

In our installation, we used the default database, SQLite, because it doesn’t require a dedicated database server. Instead, the database is just a single file. For the sake of convenience, we’ll be using it in this tutorial, but the steps in this guide also apply to different database engines.

Once the installation is done, Strapi will automatically be launched in your browser, asking you to create an administrator account.

To finish the setup and secure your app, go ahead and create a root/admin user, by filling-in the necessary information:

From now on, you can access Strapi’s local Admin interface by visiting http://localhost:1337/admin.

Enable email confirmation

By default, the user registration process in Strapi does not include email confirmation.

To enable it, from the left sidebar of the Admin dashboard, click Roles & Permissions. Select the Advanced Settings tab, enable the “Enable email confirmation” option and save:

Email console provider

Thanks to Strapi’s Email plugin, we can have a Strapi instance send emails from our server’s local email system or from an external provider (e.g., SendGrid).

Email setup and configuration is not within the scope of this article. We just want to make sure that the emails are being fired when expected and inspect their content.

For that, we’re going to use strapi-provider-email-console, a Strapi email mock provider used in development, that instead of sending, outputs the emails to the console.

Stop the Strapi app that’s running, navigate to the project’s root directory, and install the email mock provider:

cd strapi-users
npm install strapi-provider-email-console

Once the installation is done, you’ll need to add in the provider. Create the file ./config/plugins.js and paste the following code:

module.exports = ({ env }) => ({
  email: {
    provider: "console",
  },
});

Since we’ve used --quickstart the first time we ran our Strapi app, before running it in development mode, we need to install the dependencies:

npm install

Once that’s done, start the Strapi app in development mode with the command:

npm run develop

Create a Nuxt app

Now, let’s change gears and focus on the frontend app. It will be a Server-Side Rendered “Universal” Nuxt.js app.

To get started quickly, open a new terminal and create the project using Nuxt’s scaffolding tool:

npx create-nuxt-app nuxt-auth

Go through the guide and make sure to select following options:

axios and dotenv in the Nuxt.js modules step
Bulma CSS in the UI framework step, which we’ll use to style our app

Strapi’s API URL will vary depending on the environment. So, we want to have it dynamically loaded from an environment variable.

Once the tool finishes creating the app, edit the .env file in the project’s root directory, adding a new environment variable that points to the URL of the Strapi app that’s running locally:

API_AUTH_URL=http://localhost:1337

Next, navigate to the project’s root directory and install the required Nuxt Auth module dependency:

cd nuxt-auth
npm install @nuxtjs/auth

Once the installation is done, add the module @nuxtjs/auth in ./nuxt.config.js:

modules: [
  // Doc: https://github.com/nuxt-community/modules/tree/master/packages/bulma
  '@nuxtjs/bulma',
  // Doc: https://axios.nuxtjs.org/usage
  '@nuxtjs/axios',
  // Doc: https://github.com/nuxt-community/dotenv-module
  '@nuxtjs/dotenv',
  '@nuxtjs/auth'
],

At the top of nuxt.config.js, add also the following code to load the environment variables:

require("dotenv").config();

One last step we need to do in this file. Configure the base URL that axios will use when making API requests. In our case, this corresponds to the environment variable we’ve added previously:

axios: {
  baseURL: process.env.API_AUTH_URL
},

Configure Nuxt Auth

The Auth module uses Vuex’s state management to store the user authentication status and user info.

Enable the Vuex store by creating a file ./store/index.js with the store getters:

export const getters = {
  isAuthenticated(state) {
    return state.auth.loggedIn;
  },

  loggedInUser(state) {
    return state.auth.user;
  },
};

Now we are ready to configure the Auth module. The default, general purpose authentication scheme - supporting Cookie and JWT login flows - is named local. Let’s now map its endpoints with Strapi’s authentication endpoints.

Paste the code below into ./nuxt.config.js:

/*
 ** Auth module configuration
 ** See https://auth.nuxtjs.org/schemes/local.html#options
 */
auth: {
  strategies: {
    local: {
      endpoints: {
        login: {
          url: 'auth/local',
          method: 'post',
          propertyName: 'jwt'
        },
        user: {
          url: 'users/me',
          method: 'get',
          propertyName: false
        },
        logout: false
      }
    }
  }
},

We’ve set up two endpoints:

login: authenticates the user. On successful authentication, the JWT token will be available in the jwt property of the response object.
user: retrieves the authenticated user’s info. If the user is authenticated, the JWT token will be added to the request, allowing Strapi to identify the user. Since the response object is already the user info itself, we set propertyName to false.

We’ve also disabled the logout endpoint, since logging out a user is only done locally, and doesn’t require any request to Strapi’s API. The token is simply removed the from the local storage when the user logs out.

Create a file ./components/Navbar.vue with the following code:

<template>
  <nav class="navbar" role="navigation" aria-label="main navigation">
    <div class="navbar-brand">
      <nuxt-link class="navbar-item" to="/">Home</nuxt-link>

      <a
        role="button"
        class="navbar-burger burger"
        aria-label="menu"
        aria-expanded="false"
        data-target="navbarBasicExample"
      >
        <span aria-hidden="true"></span>
        <span aria-hidden="true"></span>
        <span aria-hidden="true"></span>
      </a>
    </div>

    <div id="navbarBasicExample" class="navbar-menu">
      <div v-if="isAuthenticated" class="navbar-start">
        <div class="navbar-item has-dropdown is-hoverable">
          <a class="navbar-link">
            {{ loggedInUser.username }}
          </a>

          <div class="navbar-dropdown">
            <a class="navbar-item" href="/profile">My Profile</a>
            <hr class="navbar-divider" />
            <a class="navbar-item" @click="logout">Logout</a>
          </div>
        </div>
      </div>

      <div v-if="!isAuthenticated" class="navbar-end">
        <div class="navbar-item">
          <div class="buttons">
            <nuxt-link class="button is-primary" to="/register">
              <strong>Register</strong>
            </nuxt-link>
            <nuxt-link class="button is-light" to="/login">
              Log in
            </nuxt-link>
          </div>
        </div>
      </div>
    </div>
  </nav>
</template>

Let us make the component functional by adding the following <script></script> code:

<script>
import { mapGetters } from "vuex";

export default {
  computed: {
    ...mapGetters(["isAuthenticated", "loggedInUser"]),
  },
  mounted() {
    // Get all "navbar-burger" elements
    const $navbarBurgers = Array.prototype.slice.call(
      document.querySelectorAll(".navbar-burger"),
      0
    );
    // Check if there are any navbar burgers
    if ($navbarBurgers.length > 0) {
      // Add a click event on each of them
      $navbarBurgers.forEach((el) => {
        el.addEventListener("click", () => {
          // Get the target from the "data-target" attribute
          const target = el.dataset.target;
          const $target = document.getElementById(target);
          // Toggle the "is-active" class on both the "navbar-burger" and the "navbar-menu"
          el.classList.toggle("is-active");
          $target.classList.toggle("is-active");
        });
      });
    }
  },
};
</script>

We’ve defined the computed properties isAuthenticated and loggedInUser used in the component’s template. These are mapped from the previously created store getters.

The code in the mounted hook comes from Bulma’s Navbar documentation. Its purpose is to toggle the display of the navbar-menu when the navbar-burger icon is clicked.

The navbar burger menu is displayed on smaller screen sizes.

Default Layout

Edit ./layouts/default.vue and replace its content with the following:

<template>
  <div>
    <Navbar />
    <nuxt />
  </div>
</template>

<script>
import Navbar from "~/components/Navbar";

export default {
  components: {
    Navbar,
  },
};
</script>

Homepage

Edit ./pages/index.vue and replace its content with the following:

<template>
  <section class="section">
    <div class="container">
      <h1 class="title">Nuxt Strapi Auth</h1>
    </div>
  </section>
</template>

This is what we have so far:

Notification Component

Let’s create a Notification component to give feedback to the user.

If everything goes as expected it should display a success message. Otherwise, an error message should be displayed.

Create a file ./components/Notification.vue and paste into it the code below:

<template>
  <div :class="`is-${type}`" class="notification">
    {{ message }}
  </div>
</template>

<script>
export default {
  name: "Notification",
  props: {
    type: {
      type: String,
      default: "success",
      validator: (val) => ["danger", "success"].includes(val),
    },
    message: {
      type: String,
      default: "",
    },
  },
};
</script>

Register

Create a file ./pages/register.vue and paste into it the code below:

<template>
  <section class="section">
    <div class="container">
      <div class="columns">
        <div class="column is-4 is-offset-4">
          <h2 class="title has-text-centered">Register</h2>

          <Notification v-if="success" type="success" :message="success" />
          <Notification v-if="error" type="danger" :message="error" />

          <form v-if="!success" method="post" @submit.prevent="register">
            <div class="field">
              <label class="label">Username</label>
              <div class="control">
                <input
                  v-model="username"
                  type="text"
                  class="input"
                  name="username"
                  required
                />
              </div>
            </div>
            <div class="field">
              <label class="label">Email</label>
              <div class="control">
                <input
                  v-model="email"
                  type="email"
                  class="input"
                  name="email"
                  required
                />
              </div>
            </div>
            <div class="field">
              <label class="label">Password</label>
              <div class="control">
                <input
                  v-model="password"
                  type="password"
                  class="input"
                  name="password"
                  required
                />
              </div>
            </div>
            <div class="control">
              <button type="submit" class="button is-dark is-fullwidth">
                Register
              </button>
            </div>
          </form>

          <div class="has-text-centered" style="margin-top: 20px">
            Already got an account? <nuxt-link to="/login">Login</nuxt-link>
          </div>
        </div>
      </div>
    </div>
  </section>
</template>

<script>
import Notification from "~/components/Notification";

export default {
  components: {
    Notification,
  },
  data() {
    return {
      username: "",
      email: "",
      password: "",
      success: null,
      error: null,
    };
  },
  methods: {
    async register() {
      this.error = null;
      try {
        this.$axios.setToken(false);
        await this.$axios.post("auth/local/register", {
          username: this.username,
          email: this.email,
          password: this.password,
        });
        this.success = `A confirmation link has been sent to your email account. \
        Please click on the link to complete the registration process.`;
      } catch (e) {
        this.error = e.response.data.message[0].messages[0].message;
      }
    },
  },
};
</script>

Before making the request to Strapi’s register endpoint, we make sure no token is added as a request header.

Redirect after confirmation

Before we can test the register feature, we need to tell Strapi where to redirect the user after the confirmation link is accessed.

To specify this link, from the left sidebar of the Admin dashboard, click Roles & Permissions. Select the Advanced Settings tab, paste http://localhost:3000/login in the “Redirection url” input, and save:

Configure Strapi’s Server URL

We also need to configure Strapi’s public URL. This URL will be used to prefix the confirmation link that’s sent.

Inside the Strapi project root folder, create a .env file by copying it from .env.example:

cp .env.example .env

Edit .env and add the URL environment variable:

URL=http://localhost:1337

Edit ./config/server.js and add the url property:

url: env("URL", "http://localhost:1337"),

Note that we’ve set this configuration in the development environment. In production, you’ll probably want to have SSL, so you’ll also need to install and configure an upstream proxy application, such as Nginx - and make Strapi aware of it.

Testing Register

We’re now ready to test the register feature.

Open a new terminal - so that the Strapi app is still running - and run the Nuxt app in development mode:

npm run dev

Navigate to http://localhost:3000/register and register a user:

If the registration was successful, a success message is displayed by the Notification component, requesting that the user completes the registration process by clicking the confirmation link that was sent:

If an error occurs, the error message is displayed by the Notification component we’ve created previously:

Switch to the console where Strapi is running and confirm that you see the email:

Copy the confirmation link and access it in your browser. This action completes the registration but you’ll see a “This page could not be found” error in your browser. That’s because we haven’t implemented the login page yet.

Let’s fix that.

Create a file ./pages/login.vue and paste into it the code below:

<template>
  <section class="section">
    <div class="container">
      <div class="columns">
        <div class="column is-4 is-offset-4">
          <h2 class="title has-text-centered">Log In</h2>

          <Notification v-if="error" type="danger" :message="error" />

          <form method="post" @submit.prevent="login">
            <div class="field">
              <label class="label">Email</label>
              <div class="control">
                <input
                  v-model="email"
                  type="email"
                  class="input"
                  name="email"
                />
              </div>
            </div>
            <div class="field">
              <label class="label">Password</label>
              <div class="control">
                <input
                  v-model="password"
                  type="password"
                  class="input"
                  name="password"
                />
              </div>
            </div>
            <div class="control">
              <button type="submit" class="button is-dark">
                Log In
              </button>
            </div>
          </form>
          <div style="margin-top: 20px">
            <p>
              Don't have an account?
              <nuxt-link to="/register">Register</nuxt-link>
            </p>
            <p>
              <nuxt-link to="/forgot-password">Forgot Password?</nuxt-link>
            </p>
          </div>
        </div>
      </div>
    </div>
  </section>
</template>

<script>
import Notification from "~/components/Notification";

export default {
  components: {
    Notification,
  },
  data() {
    return {
      email: "",
      password: "",
      error: null,
    };
  },
  methods: {
    async login() {
      this.error = null;
      try {
        await this.$auth.loginWith("local", {
          data: {
            identifier: this.email,
            password: this.password,
          },
        });
        this.$router.push("/");
      } catch (e) {
        this.error = e.response.data.message[0].messages[0].message;
      }
    },
  },
};
</script>

Navigate to http://localhost:3000/login and login with a previously registered user:

Notice the changes in the Navbar:

Logout

Let’s now add the logout method that’s triggered when the user clicks the Logout Navbar link.

Edit ./components/Navbar.vue and add the following code under mounted():

methods: {
    async logout() {
      await this.$auth.logout()
    }
  }

User Profile

Time for the user profile page.

Create a file ./pages/profile.vue with the following code:

<template>
  <section class="section">
    <div class="container">
      <h2 class="title">My Profile</h2>
      <div class="content">
        <p>
          <strong>Username:</strong>
          {{ loggedInUser.username }}
        </p>
        <p>
          <strong>Email:</strong>
          {{ loggedInUser.email }}
        </p>
      </div>
    </div>
  </section>
</template>

<script>
import { mapGetters } from "vuex";

export default {
  middleware: "auth",
  computed: {
    ...mapGetters(["loggedInUser"]),
  },
};
</script>

The auth middleware guarantees that only logged in users can access this page.

Guest middleware

If the user is already logged in, it’s probably a good idea to block the access to the register and login pages.

Create a file ./middleware/guest.js:

export default function ({ store, redirect }) {
  if (store.state.auth.loggedIn) {
    return redirect("/");
  }
}

Define the new middleware in ./pages/register.vue and ./pages/login.vue:

export default {
  middleware: "guest",
};

Password Reset

Let’s now implement a password reset mechanism.

This will be achieved with the following workflow:

In the Forgot Password Page, user submits email.
If the email is in Strapi’s user database, user receives email with a link to the Reset Password Page containing a reset code as a URL parameter.
User clicks the link and specifies a new password.
The new password is sent to Strapi, along with the reset code.
The password is updated and the user can now use it to login.

Forgot Password Page

Create a file ./pages/forgot-password.vue:

<template>
  <section class="section">
    <div class="container">
      <div class="columns">
        <div class="column is-4 is-offset-4">
          <h2 class="title has-text-centered">Forgot Password</h2>

          <Notification v-if="success" type="success" :message="success" />
          <Notification v-if="error" type="danger" :message="error" />

          <form v-if="!success" method="post" @submit.prevent="forgotPassword">
            <div class="field">
              <label class="label">Email</label>
              <div class="control">
                <input
                  v-model="email"
                  type="email"
                  class="input"
                  name="email"
                />
              </div>
            </div>
            <div class="control">
              <button type="submit" class="button is-dark">
                Email me a reset link
              </button>
            </div>
          </form>
        </div>
      </div>
    </div>
  </section>
</template>

<script>
import Notification from "~/components/Notification";

export default {
  middleware: "guest",
  components: {
    Notification,
  },
  data() {
    return {
      email: "",
      success: null,
      error: null,
    };
  },
  methods: {
    async forgotPassword() {
      try {
        await this.$axios.post("auth/forgot-password", {
          email: this.email,
        });
        this.error = null;
        this.success = `A reset password link has been sent to your email account. \
        Please click on the link to complete the password reset.`;
      } catch (e) {
        this.error = e.response.data.message[0].messages[0].message;
      }
    },
  },
};
</script>

In our implementation we’re disclosing whether the email is registered or not. The reason is to show that Strapi gives us that information. However, for applications with greater security requirements, we could also just display the success message, whether Strapi responds with an error or not - helping the prevention of phishing attacks.

The method forgotPassword sends a request to Strapi’s auth/forgot-password endpoint. If the email address exists in Strapi’s user database, an email is sent with a link to a reset password page in the frontend app.

To specify this link, from the left sidebar of the Admin dashboard, click Roles & Permissions. Select the Advanced Settings tab, paste http://localhost:3000/reset-password in the “Reset password page” input, and save:

Strapi will attach to it a URL parameter with the code that’s required to successfully reset the user password.

Reset Password Page

Let’s now create the page that will allow the user to define a new password. Create a file ./pages/reset-password.vue and paste the following code into it:

<template>
  <section class="section">
    <div class="container">
      <div class="columns">
        <div class="column is-4 is-offset-4">
          <h2 class="title has-text-centered">Reset Password</h2>

          <Notification v-if="success" type="success" :message="success" />
          <Notification v-if="error" type="danger" :message="error" />

          <form v-if="!success" method="post" @submit.prevent="resetPassword">
            <div class="field">
              <label class="label">New Password</label>
              <div class="control">
                <input
                  v-model="password1"
                  type="password"
                  class="input"
                  name="password"
                />
              </div>
            </div>
            <div class="field">
              <label class="label">Confirm New Password</label>
              <div class="control">
                <input
                  v-model="password2"
                  type="password"
                  class="input"
                  name="password"
                />
              </div>
            </div>
            <div class="control">
              <button type="submit" class="button is-dark">
                Reset Password
              </button>
            </div>
          </form>
        </div>
      </div>
    </div>
  </section>
</template>

<script>
import Notification from "~/components/Notification";

export default {
  middleware: "guest",
  components: {
    Notification,
  },
  asyncData(context) {
    if (!context.route.query.code) context.redirect("/forgot-password");
    else
      return {
        code: context.route.query.code,
      };
  },
  data() {
    return {
      password1: "",
      password2: "",
      success: null,
      error: null,
    };
  },
  methods: {
    async resetPassword() {
      this.error = null;
      if (this.password1 !== this.password2) {
        this.error = "Passwords do not match.";
        return;
      }
      try {
        await this.$axios.post("auth/reset-password", {
          code: this.code,
          password: this.password1,
          passwordConfirmation: this.password2,
        });
        this.success =
          "Password updated successfully. You can now use it to log in to your account.";
      } catch (e) {
        this.error = e.response.data.message[0].messages[0].message;
      }
    },
  },
};
</script>

One more thing before we’re able to test the password reset feature. We need to enable the Public Role permission for the auth/reset-password endpoint.

To do so, from the left sidebar of the Admin dashboard, click Roles & Permissions. Click Public and under Permissions expand the USERS-PERMISSIONS plugin. Under Auth check the option “resetpassword” and save:

Testing Password Reset

Visit http://localhost:3000/forgot-password in your browser, fill-in the “Email” input with an email that has been registered before and click Email me a reset link.

Switch to the terminal where Strapi is running and confirm that the mock email is there:

Copy the entire link and access it in your browser:

Fill-in the form and click “Reset Password”. This action will reset the user password:

Token Expiration

Awesome! We’ve done a lot, but there’s still something missing before we wrap up.

If the JWT token expires, subsequent requests to Strapi will return a 401 Unauthorized error.

To deal with this, we’ll intercept error responses in axios and check if the status code is 401. If it is, we redirect the user to the login page.

Create a file ./plugins/axios.js:

export default function ({ $axios, redirect }) {
  $axios.onError((error) => {
    const code = parseInt(error.response && error.response.status);
    if (code === 401) redirect("/login");
  });
}

In nuxt.config.js import the plugin we’ve just created:

plugins: ['~plugins/axios'],

Now, when the JWT expires the user will be gracefully redirected to the login page.

Conclusion

Hopefully you’ve found this tutorial helpful for implementing Strapi authentication in your Nuxt app!

You should now have a fully built, ready to be deployed in production authentication flow, through which users can register, login, and reset their password.

The source code for both projects can be found on GitHub:

How to set up a canonical URL in Eleventy

Tue, 04 Aug 2020 00:00:00 GMT

Cross-posting can be a great way to expose your content to new, larger audiences.

Nonetheless, it’s important to consider the implications it can have on page ranking and SEO.

When you syndicate an article for publication on different domains, setting up a canonical URL will let search engines know which page should be considered the original, and which ones duplication.

To do this, we need to include in all the duplicate versions a <link> tag pointing to the canonical URL.

Implementing this in Eleventy is pretty straight-forward.

Edit your default layout (probably _includes/layouts/base.njk), adding the following inside the <head> tag:

{% if canonical %}
  <link rel="canonical" href="{{ canonical }}" />
{% endif %}

Basically, we’re conditionally adding the <link> tag, depending on whether a key canonical exists in the front matter of the content page.

If you’re not using Nunjucks, check out the documentation of your template language to find out how to conditionally render HTML.

Then, in the front matter’s content file, simply add a canonical key pointing to the original URL, like so:

canonical: "https://dev.to/you/your-awesome-article"

Build your static site again and confirm that the <link> tag is present.

Done!

Building a Jamstack app with Nuxt, Vue and FaunaDB

Tue, 14 Jul 2020 00:00:00 GMT

(This article was originally published on dev.to).

In this article, we’ll be using a Jamstack approach to build a Repository Catalogue.

First, we’ll populate a FaunaDB database with a set of repos. For each repo, we’ll store its GitHub URL, the project’s name, logo, and main color.

Then, at build time, we’ll use Nuxt.js to fetch the repo data from FaunaDB, and use it to pre-render the Repo Catalogue app.

Finally, we’ll retrieve some highly dynamic repo info (such as number of stars and forks) from the GitHub API, and with the help of Vue’s awesome client-side hydration features, display it in each repo’s page.

Check out the working demo here.

Why a Repository Catalogue?

As developers, we all have projects we admire/find interesting/look up to, and like to keep track of.

The Repository Catalogue will serve as a collection of GitHub projects, that you can customize to display repo information that is more relevant to you.

Although we’ll be building a very concrete implementation, its main purpose is to serve as an example to the core underlying idea of this article.

Harnessing both the benefits from pre-rendering and the flexibility of dynamic sites, by generating as much as possible upfront, and loading the highly dynamic data via JavaScript when the user visits the page. We’ll see that hydration is the key that gives us the major benefit of a Single Page Application (no reloads needed to display asynchronously requested data), while also getting the speed of a statically loaded site.

“It’s usually a good idea to load as much data at build time as possible to improve page performance. But if the data isn’t needed by all clients, or too big to be sent to the client all at once, we can split things up and switch to on-demand loading on the client. This is the case for user-specific data, pagination, or any data that changes rather frequently and might be outdated by the time it reaches the user.” - Build a dynamic JAMstack app with GatsbyJS and FaunaDB

When analyzing the requirements for a Repo Catalogue, we can straight away identify two categories of data:

Data that does not change often or not at all (e.g., project name, logo, repo URL, and the repo list itself - after all, only some projects have a special place in our heart 😄, so it’s not that often we need to add or delete a repo from the catalogue.)
Data that changes frequently (e.g., repository number of stars and forks)

The former, is in our control and therefore well-suited to be stored in a Fauna’s database. Moreover, it can then serve as a data source for any client app we decide to build.

The latter comes from a third-party source and changes often, so it’s not a good candidate for database storage. It’s preferable to fetch it dynamically only when it’s needed, making sure we’re always getting the current data.

One important consideration to make, is that this does not imply that FaunaDB is only appropriate for static data. Quite the contrary, FaunaDB is great for highly dynamic data. So, it might seem an overkill to use FaunaDB for data that doesn’t change often. However, we plan to, in a next segment, let people ‘like’ and comment on our catalogue repositories. For such dynamic data, FaunaDB is a perfect fit and in the meantime, works absolutely fine for storing our repository list.

This data categorization may then lead us to question:

“Do we really need to keep making the same request, to get the same data, take those same results, run them against the same template, and only then, deliver the page to the client?”.
“What if we use the server-side build to fetch the repo collection, and serve HTML and static assets to our site’s visitors? Does that mean we are bound to fully static pages?”

In fact, we’ll see that by combining a Jamstack approach in the build step with client-side hydration, we’ll be able to enliven our static pages with highly dynamic data.

At the end, you’ll be able to take this example, adapt and apply it to your specific use case, by identifying and categorizing your data accordingly.

Jamstack

The concepts of Jamstack and “static-first” are not new and their advantages have been extensively documented before. Jamstack architectures allow us to build faster, more secure, more scalable websites.

With HTML being pre-rendered once and then statically served from a CDN, a website has the potential for great performance. Fetching data at the build stage - instead of each time a client requests a page, with minimum computing overhead.

The term “static” can be a bit misleading - that’s why we see “pre-rendered” being used interchangeably. When we build a Jamstack app, it doesn’t mean we have to compromise on dynamic content and features.

We can build the site beforehand with the type of data that does not change often, and augment it client-side, only if and when that’s needed.

Moreover, the widespread of functionality APIs, makes way for common tasks - such as authentication, e-commerce, and data storage - that used to be implemented over and over, now be delegated to the professional service providers.

FaunaDB

Fauna is a globally distributed, low-latency database, with native GraphQL support, that promises to be always consistent and always secure.

As a serverless database, FaunaDB allows applications to access data through a secure API, in contrast to more “traditional” relational databases that require you to open a connection. In that sense, FaunaDB is “connectionless” and rather behaves like an API, which fits perfectly in a Jamstack architecture. There is also no need to host and manage our own database. It requires zero server configuration and supports seamless scalability out-of-the-box.

“Because serverless technologies abstract away the problems I don’t want to deal with (setting up servers, scaling them, hosting my logic etc.) and allow me to just run my code whenever I need it to.” - Tomasz Łakomy

From a developer’s perspective this is awesome, because it allows us to be more productive and focus solely on the logic of the app we’re building.

Nuxt.js

Nuxt.js is an open-source web application framework built on top of Vue.js. It is well known for its SSR capabilities, but it can also do static.

Instead of having a Node server process each client request - eventually fetching data from an API or database in between, we’ll be using Nuxt as a static site generator to do the heavy lifting during the build stage.

Goals

What we’re setting to achieve in this tutorial:

building a pre-rendered Repo Catalogue site with Nuxt.js
building a helper app that we’ll use to seed Fauna’s database

Although it’s not the main focus of the article, the supporting fauna-seeder app will allows us to populate the FaunaDB database with a single command from the terminal. It’s just one a way of storing data in FaunaDB - in fact, you could be doing this step in a different way of your choice.

Pre-requisites

Before we move on, I’d like to mention that although not mandatory, a working knowledge of the following technologies is beneficial:

JavaScript
Vue.js/Nuxt.js
GraphQL

Before you begin, you’ll need:

Node, npm, and npx installed
A FaunaDB account

Without further ado, let’s dive in!

Modelling our data

First things first, we begin by specifying the data model. The goal is to store a collection of repos in a Fauna database.

Each repo is represented by the following fields:

project name
GitHub repo URL
project logo
project color

Writing the GraphQL schema

In this section, we’ll be creating the helper app fauna-seeder that will populate the database.

Inside this project, we’ll also store the GraphQL schema we’ll be writing to define our repo data, The schema will be used in the next step to create the database and specify what resources the database will provide.

“GraphQL is a specification for an API query language and a server engine capable of executing such queries.” - Production Ready GraphQL

Create a directory for the project and navigate to it:

mkdir fauna-seeder
cd fauna-seeder

From within the root directory, create a new git repo:

git init

Configure git to ignore the node_modules directory and the .env file:

echo "node_modules" > .gitignore
echo ".env" >> .gitignore

Then, let’s initialize a Node project:

npm init -y

This creates a package.json file where we can install the required dependencies:

npm install dotenv faunadb simple-icons

We’ve installed three dependencies:

faunadb: JavaScript driver for FaunaDB
simple-icons: Simple Icons npm package
dotenv: to store and load Fauna’s secret key from a .env file

The Fauna Query Language (FQL) is the native API for querying FaunaDB. Fauna drivers (available for several programming languages) abstract the FQL, allowing developers to programmatically interact with FaunaDB databases.

Simple Icons is a cool project that collects SVG icons and colors for popular brands. We’ll be using their npm package to get the SVG logo and the hex color code of each project, when the seeder app runs.

Let’s now write the GraphQL schema. Create a directory graphql and a schema.gql file inside it:

mkdir graphql && cd graphql && touch schema.gql

type Repo {
  projectName: String! @unique
  repoUrl: String! @unique
  svgLogo: String
  colorHex: String
}

type Query {
  allRepos: [Repo!]!
}

As you may know, GraphQL uses a typed schema to specify entities and their fields. We’ve declared the object type Repo to represent an individual repository in the collection.

A repo has a project name, a repository URL, a SVG logo, and a color. The first two fields are declared as non-nullable ! and unique @unique. This guarantees that a repo always has values for these required fields, and that there are no repeated repos in the collection.

We’ve also declared a query allRepos, to list all the repos that are stored in the collection.

Creating a Fauna database

Visit the dashboard and create a new database, named repos:

Importing the schema

Now that the database is created, we can import the GraphQL schema into FaunaDB.

When you import a GraphQL schema, FaunaDB will automatically make the collections and indexes for you to support your queries and provide you with an “instant” GraphQL endpoint to start querying.

We can upload our schema.gql file, via FaunaDB Console by clicking “GraphQL” on the left sidebar:

Then click the “Import Schema” button, which opens your browser’s file upload, and select the schema.gql file:

FaunaDB automatically created the necessary collection for the Repo entity.

Additionally, it also created the indexes that support the schema and interact with the collection:

At this point we have an empty database, ready to be populated with some repo data.

Seeding data to Fauna

Inside a Fauna database, we have Collections, Indexes and Documents. FaunaDB is a relational database that stores data in the JSON format.

“A Collection is a categorized group of data. Each piece of data takes the form of a Document. A Document is a “single, changeable record within a FaunaDB database,” according to Fauna’s documentation. You can think of Collections as a traditional database table and a Document as a row.” - Bryan Robinson

There are four ways of interacting with Fauna data:

Fauna drivers
Interactive Shell using FQL
GraphQL Playground
GraphQL API using a GraphQL client (e.g., Apollo)

Normally, after using a GraphQL schema to generate the collections and indexes - as we did, you would use the GraphQL endpoint that’s automatically provided. For learning purposes, I decided to try out a different approach and go with FQL. Although this is not the official way to interact with the data, it also simplifies our schema, avoiding the need for GraphQL mutations to define write operations.

We’ll use the JavaScript driver, that we’ve already installed in a previous step.

The driver requires a Fauna Admin Key in order to authenticate connections and write data in the repos database.

From the database’s dashboard, go to “Security” on the left-hand sidebar, and create a new key with “Admin” Role:

Copy the generated key and save it somewhere safe, as after you navigate away from this page it will not be displayed again.

Create a .env file in the root directory of the fauna-seeder app:

cd ..
touch .env

Add the environment variable FAUNA_ADMIN_KEY and paste the generated key right after the variable’s name:

FAUNA_ADMIN_KEY=

From here, we just need to reference process.env.FAUNA_ADMIN_KEY to access the key from within our code.

Let’s create a function that handles a client connection to Fauna:

cd graphql
touch db-connection.js

Add the following to db-connection.js:

require("dotenv").config();
const faunadb = require("faunadb");
const query = faunadb.query;

function createClient() {
  if (!process.env.FAUNA_ADMIN_KEY) {
    throw new Error("FAUNA_ADMIN_KEY not found");
  }
  const client = new faunadb.Client({
    secret: process.env.FAUNA_ADMIN_KEY,
  });
  return client;
}

exports.client = createClient();
exports.query = query;

The function will try do load the secret key, and in case of success, proceed with creating and returning a connection to the database. Finally, the createClient function is exported, alongside the driver’s query variable, which will allow us to seed the data in FQL’s functional, composable style.

Repo data

We’ll be using JSON to store the minimal set of repo data the seeder app requires.

Each repo is represented by three properties:

{
  "projectName": "Vue.js",
  "repoUrl": "https://github.com/vuejs/vue",
  "simpleIconsName": "Vue.js"
}

project name
GitHub repo URL
Simple Icons brand title

Create a data.json file:

cd ..
touch data.json

Using the format above, add an array of repos that will be written to Fauna’s database. You can either use the same file I’ve used or tweak it to feature your favorite projects.

Make sure the simpleIconsName value exists in the Simple Icons collection. You can use the search feature on the website to get the correct names of the projects you’re adding.

Running the seeder app

Create a file named seed.js:

touch seed.js

This is the code that will run to populate the Repo collection:

const { client, query } = require("./graphql/db-connection");
const q = query;
const simpleIcons = require("simple-icons");
const reposData = require("./data.json");

const repos = reposData.map((r) => {
  const simpleIconsData = simpleIcons.get(r.simpleIconsName);
  r.svgLogo = simpleIconsData.svg;
  r.colorHex = simpleIconsData.hex;
  delete r.simpleIconsName;
  return r;
});

client
  .query(
    q.Map(
      repos,
      q.Lambda(
        "repo",
        q.Create(q.Collection("Repo"), {
          data: q.Var("repo"),
        })
      )
    )
  )
  .then(console.log("Repos seeded successfully to FaunaDB"))
  .catch((err) => console.log("Failed to seed repos to FaunaDB", err));

Let’s review what we did:

Import functions client and query from ./graphql/db-connection
Import simple-icons package
Import list of repos from ./data.json
Go through each repo, get the SVG logo and the hex color code from simple-icons and add the properties accordingly
Delete property simpleIconsName from the repo, since we don’t want to write it to the database
Use the driver to map over the array of repos and create a new document for each one, in the Repo collection

Notice that query operates as a transaction, which means that if an error occurs, none of the repos will be written in the database.

If everything goes as expected, we print a success message.

We’re now ready to add documents to the Repo collection:

node seed.js

Navigate to “Collections” from the sidebar menu, and confirm that the data was written successfully:

Nuxt Repo Catalogue

Now, let’s change gears and look at this tutorial’s core app.

To get started quickly, we’ll initialize the project using Nuxt’s scaffolding tool:

npx create-nuxt-app repo-catalogue

Go through the guide and select the following options:

axios and dotenv in the Nuxt.js modules step
Bulma in the UI framework step, to style our app

Once the tool finishes creating our Nuxt app, install also the other required dependencies:

faunadb: JavaScript driver for FaunaDB
slugify: we’ll use this package to generate slugs from repo names

npm install faunadb slugify

Fauna key

The same way we did for the fauna-seeder app, let’s create a new Fauna key - this time with “Server” Role:

Edit the .env file and paste the key you’ve just generated.

FAUNA_SERVER_KEY=

In the top of nuxt.config.js require and configure dotenv:

require("dotenv").config();

Routes

The Repo Catalogue website will respond in two types of routes:

one home page, where all repos are listed
several repo detail pages, one for each repo in the catalogue

The /pages folder will look like this in Nuxt:

├── index.vue
├── repos
│   └── _slug.vue

Since we want to pre-render the site’s pages, we need to tell Nuxt which routes to generate.

The routes for the individual repo pages have to be generated dynamically.

In Nuxt, we do this by setting the generate.routes property to an array of dynamic routes.

When running nuxt generate, Nuxt.js will use the configuration defined in the generate property, to pre-render the site.

We’ll write a function routes that reads the repo data from the database and returns the array of routes to be generated.

Let’s add the generate property in nuxt.config.js:

generate: {
  async routes() {
    const faunadb = require('faunadb')
    const query = faunadb.query
    const slugify = require('slugify')
    const q = query
    if (!process.env.FAUNA_SERVER_KEY) {
      throw new Error('FAUNA_SERVER_KEY not found.')
    }
    const client = new faunadb.Client({
      secret: process.env.FAUNA_SERVER_KEY
    })
    const result = await client.query(
      q.Map(
        q.Paginate(q.Match(q.Index('allRepos'))),
        q.Lambda('X', q.Get(q.Var('X')))
      )
    )
    const repos = result.data.map((repo) => repo.data)
    const routes = repos.map((repo) => {
      const repoUrlParts = repo.repoUrl.split('/')
      const repoOwner = repoUrlParts[repoUrlParts.length - 2]
      const repoName = repoUrlParts[repoUrlParts.length - 1]
      const slug = slugify(repoName, {
        remove: /[*+~.()'"!:@]/g
      })
      repo.slug = slug
      repo.owner = repoOwner
      repo.name = repoName
      return {
        route: '/repos/' + slug,
        payload: repo
      }
    })
    routes.push({
      route: '/',
      payload: repos
    })
    return routes
  }
}

It’s quite some code. So, let’s review the different steps of the snippet:

Import the faunadb driver from node_modules
Import the slugify package from node_modules
Load the Fauna secret key from .env
Instantiate a Fauna client using the secret key
Fetch the entire repo collection using the allRepos Index
Go through each repo, generate a slug and return an object with the route path and the repo data as payload, that will be passed to the page
Add the route for the home page, passing the repo collection as payload
Return the array of routes that should be generated

Creating the pages

Let’s being with the homepage /pages/index.vue. This is the page that lists the repo collection.

Delete the default CSS inside <style> so we can start with a blank slate.

Replace the content of <script> with:

<script>
export default {
  asyncData({ payload }) {
    return { repos: payload };
  },
};
</script>

We’ve used Nuxt’s asyncData to instantiate the variable repos with the payload from the generate configuration.

Now that have access to the data, replace the existing <template> with:

<template>
  <section class="section">
    <div class="container">
      <h1
        :style="{ marginBottom: '5rem' }"
        class="title has-text-centered is-size-1"
      >
        Repo Catalogue
      </h1>
      <div class="columns is-multiline">
        <div
          v-for="repo in repos"
          :key="repo.projectName"
          class="card column is-3"
        >
          <div
            :style="{ backgroundColor: '#' + repo.colorHex }"
            class="card-image"
          >
            <a :href="`/repos/${repo.slug}`">
              <figure
                :style="{ maxWidth: '20%', margin: '0 auto', padding: '2em 0' }"
                v-html="repo.svgLogo"
              ></figure>
            </a>
          </div>
          <div class="card-content">
            <div class="media">
              <div class="media-content">
                <h3 class="title">{{ repo.projectName }}</h3>
                <a class="subtitle" :href="repo.repoUrl">GitHub</a>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </section>
</template>

In the template above, we’ve gone through each repo and displayed it as a Bulma Card.

Let’s move on to the individual repo detail page. Create a new file /pages/repos/_slug.vue and replace the existing <script> with:

<script>
export default {
  asyncData({ payload }) {
    if (payload) return { repo: payload };
  },
};
</script>

Now that have access to the data, replace the existing <template> with:

<template>
  <div>
    <section
      :style="{ backgroundColor: '#' + repo.colorHex }"
      class="hero has-text-centered"
    >
      <div class="hero-body">
        <div class="container">
          <figure
            :style="{ maxWidth: '10%', margin: '0 auto' }"
            v-html="repo.svgLogo"
          ></figure>
          <h1 class="title has-text-light is-size-1">
            {{ repo.projectName }}
          </h1>
        </div>
      </div>
    </section>
  </div>
</template>

In the template above, we’ve created a Bulma Hero to display the repo data.

Running Nuxt generate

Now that we’ve created the page templates, we have everything we need to build our website, with dynamically generated routes, using Fauna data.

Build your Nuxt.js Repo Catalogue:

npm run generate

And that’s it! 👏 You have now a working static site in the dist folder, that can be served directly from a CDN.

To test it locally run:

npx serve dist

Adding dynamic content to our Repo Catalogue

Perhaps the main objection to static sites is “I don’t want to have to rebuild the entire site every time something changes in the database”.

It’s a totally valid argument - a nuanced one nonetheless. For example, a Netlify hosted website won’t have any downtime, while the build/deploy of a new version takes place.

So what is the real downside? Maybe the time it takes to rebuild a website with large amounts of content. And even in that domain, we’re starting to see amazing progress being made, e.g. Gatsby’s recently announcing incremental builds.

But still, there are certainly some scenarios where constantly rebuilding the site is not viable.

Going back to our Repo Catalogue, suppose we want to add some dynamic data to the detail pages, such as description, number of stars, and number of forks.

Clearly, it’s not practical to rebuild an entire website whenever any of this data changes.

In this section, we’ll be adding some dynamic data to the Repo detail page. We’ll be adding an asynchronous JavaScript API call to the GitHub API to get the repo’s information.

The request for this data will be made client-side and we’ll rely on Vue’s reactivity to display it.

In /pages/repos/_slug.js, declare a repoData object to hold the response data:

data() {
  return { repoData: {} }
},

The GitHub API provides an endpoint GET /repos/:owner/:repo that returns a repo’s info. Use Vue’s mounted hook to call the GitHub API from the client, with axios:

mounted() {
  this.$nextTick(async () => {
    const repoOwner = this.repo.owner
    const repoName = this.repo.name
    const result = await this.$axios.$get(
      `https://api.github.com/repos/${repoOwner}/${repoName}`
    )
    this.repoData = result
  })
}

Under the Hero <section>, create a container to display the dynamic data:

<div class="container" :style="{ paddingTop: '2rem' }">
  <p><span class="is-size-5">Description:</span> {{ repoData.description }}</p>
  <p><span class="is-size-5">Stars:</span> {{ repoData.stargazers_count }}</p>
  <p><span class="is-size-5">Forks:</span> {{ repoData.forks_count }}</p>
</div>

Now, tell Nuxt to generate the site again, so that the GitHub API call is included in the app’s bundle:

npm run generate

And we’re done! 🎉

A dynamic website that loads data in the frontend as the user visits the repo detail page.

Conclusion

In this article, we’ve built a Repo Catalogue static website that you can now deploy on a host of your choice.

The intent was to point out that it doesn’t always have to be a matter of A/B decision. We can aim for a “hybrid” solution whenever possible, where we pre-render the most we can, and asynchronously fetch just the data we need.

We began by writing a GraphQL schema to model our repo data. Then, we used FaunaDB to create a cloud database and, by simply importing the schema, we instantly got a full-featured data backend.

Just like that! No need to deal with any server/database hosting and configurations, we were able to quickly start building our Repo Catalogue.

Another cool benefit we get with a database like Fauna, is that it allows us to have a unique source of truth to represent both the data model and the API that interacts with it.

Then, we used Nuxt to implement the app’s pages and configured it to fetch the repo data from the database, using it to build a pre-rendered app.

Finally, we added dynamic data from the GitHub API to our static pages.

The code for this tutorial can be found in the following GitHub repos:

What to do next

Here are a couple of ideas to further explore:

Hosting the Repo Catalogue on Netlify and configuring it to trigger a new repo-catalogue build/deploy every time there’s a push to master
Finding a way to trigger a new repo-catalogue build/deploy whenever content changes in Fauna’s database
Adding a loader in the repo detail page, while the GitHub API is being requested
Implementing error handling for database and API requests

How to dynamically change the order of HTML elements

Fri, 08 May 2020 00:00:00 GMT

Let’s say you’re working on a page that has two main components - Element A and Element B.

Suppose you had to implement a responsive layout with the following requirements:

Desktop: Element A should be positioned on top of Element B
Mobile: Element B should be positioned on top of Element A

In this tutorial, we’ll look at two different approaches to solve these requirements.

Here’s what we’ll be setting to achieve:

Before we begin

It’s important to clarify some pre-conditions and set the right expectations as to what the end result will exactly be.

We assume that both elements are siblings in the DOM - i.e., both are direct descendants of the same parent element:

<section class="parent">
  <div id="element-a" class="element">
    <h2>HTML Element A</h2>
  </div>
  <div id="element-b" class="element">
    <h2>HTML Element B</h2>
  </div>
</section>

We’ll look at two different solutions. Both accomplish the requirements visually. However, there are some nuances that can make you decide for one or the other.

Here are some quick remarks for each solution, so you can jump right away to the one that better fits your use case.

Solution 1:

The parent element has to be a flex container
Achieved using CSS
Does not actually change the DOM order of the elements
Less implementation steps
Breaks keyboard navigation

Solution 2:

Achieved using JavaScript
Changes the DOM order of the elements
More implementation steps
Does not break keyboard navigation

Solution 1: flex-direction

As you may have guessed from the title, we’ll be using flexbox. The parent element has to be a flex container. This is how we make it one:

.parent {
  display: flex;
  flex-direction: column;
}

We’ve also used flex-direction to set the main axis and define how child elements are placed inside the parent container.

By default, flex items are displayed in the same order as they appear in the document.

Now, for the mobile layout we want to reverse the order in which the elements are displayed. The value column-reverse does precisely this. Let’s go ahead and add a media query to reverse the flex-direction whenever the display area has a maximum width of 767 pixels:

@media (max-width: 767px) {
  .parent {
    flex-direction: column-reverse;
  }
}

And we’re done, that’s all we need!

It is important to bear in mind that this solution creates a disconnect between the visual presentation and the DOM order.

“This will adversely affect users experiencing low vision navigating with the aid of assistive technology such as a screen reader. If the visual (CSS) order is important, then screen reader users will not have access to the correct reading order.” - MDN web docs

If you have more than two child elements and would like to have more control over their individual display order, checkout the order property.

Solution 2: DOM manipulation

We’ll be using JavaScript - via HTML DOM API - to access the document and its elements.

The strategy is to select the element that should be on top - based on the maximum width of the display area, and insert it as the first child of the parent element.

First, let’s create a variable to represent our media query:

const mobile = "(max-width: 767px)";

The Window interface provides the method matchMedia() - which returns a media query list, matching a specified media query string.

We can then check whether our variable mobile matches with the current state of the document.

So let’s define a function that conditionally sets Element A or Element B as first child of the parent element:

function setFirstChild() {
  const matched = window.matchMedia(mobile).matches;

  const topElement = matched
    ? document.getElementById("element-b")
    : document.getElementById("element-a");

  const parent = topElement.parentNode;
  parent.insertBefore(topElement, parent.firstChild);
}

Notice that there was no need to explicitly remove it from the DOM, store it in a temporary variable, and append it again.

Since it already exists in the document, insertBefore() moves it from its current position to the new position.

Now, we attach the function we’ve just created to the load event, so it runs when the document is loaded:

window.onload = setFirstChild;

Finally, we need to watch for media query changes, so that if the user resizes the browser the order updates accordingly:

window.matchMedia(mobile).addEventListener("change", setFirstChild);

You can now test that everything is working as expected by reloading and resizing the browser.

Wrapping up

We’ve seen two ways to dynamically change the order of HTML elements based on the display width. Neither is necessarily better.

Solution 1 is arguably more practical. However, it breaks keyboard navigation.

Solution 2 manipulates the DOM, which is operationally more intensive than just using media queries.

You can reference the code I used to create this tutorial, which includes examples for both solutions.

Acknowledgements

Thanks to Hemlock for mentioning a way to move a DOM element without having to remove and append it again to the DOM.

Three months of Nuxt.js in Production - A Retrospective

Sat, 18 Apr 2020 00:00:00 GMT

In this article, I want to reflect and share my experience working with Nuxt.js, over the past three months, pretty much on a daily basis, in a continuous delivery production setting.

Now that the project is approaching the finish line, it’s time to pause and review its centerpiece tool and how it contributed to its successful completion.

This won’t be a Nuxt.js technical tutorial. There are lot of excellent resources around. I’m not going to examine it in depths, I just want to focus on my journey as a developer, experimenting with the framework for the first time and using it right away in a real-world project.

Hopefully, I’ll also be able to reignite my writing habit and get back on track, as I haven’t had much opportunity to do so lately.

What led me to Nuxt.js

Three months ago, I began working with a new client, where I was asked to choose the frontend stack for a project that was about to begin.

My client’s end-client is a media platform, and the goal was to revamp their website, giving it a more modern/responsive look and feel. The project had two top-level requirements. One, was to allow them to showcase their huge media catalogue. The other, was to feature a new area, something very similar to a classical TV guide, scheduling the airing of their programmes.

At the time, I had been reading and learning about the concept of JAMstack. I had built a couple of personal projects - such as this website, just to test the waters. Maybe this could be the opportunity to apply it professionally for the first time.

The media catalogue seemed an appropriate candidate to be statically built. The content would probably not change that much over time. Could we pass on the heavy lifting to the build process and serve a blazing fast static site from a CDN?

What about the TV guide feature? We’d certainly have to call some API for that. But what if the data changes too often? We wouldn’t want to keep re-building the website all the time. This was the exploration phase, and besides top-level requirements, almost everything else was unclear. There were a lot of questions and not so many answers. I knew we should obviously decouple frontend and backend, but not much more than that.

Although the end-client did not mention it initially, I was already starting to anticipate that web analytics and SEO (Search Engine Optimization) would be very important, so at that point I was already leaning towards a static or SSR approach.

By happy chance, in the meanwhile, I also started to participate in a project alongside the amazing freecodecamp Lisbon community, where I was introduced to Nuxt.js. It couldn’t have come at a better time!

I started to learn more about Nuxt, going through some tutorials, and asking for help and tips. I was from the get-go very impressed with how fast I was prototyping and building.

I have to admit I was a bit apprehensive to see how it would handle the complexities of a real project. I didn’t have the time to fully explore it, and I had to make a decision. I also didn’t have all the answers I needed to fully commit to a static solution.

Well, Nuxt could do that and could also do the safer SSR approach. And so, Nuxt it was.

What is Nuxt.js? Quick Overview

Nuxt.js is an MIT-licensed, open-source web application framework built on top of Vue.js.

Vue.js is a JavaScript library for building web interfaces. Even though Vue’s main tagline is “The Progressive JavaScript Framework”, its official website also describes it as “An incrementally adoptable ecosystem that scales between a library and a full-featured framework”.

Without getting further into the discussion of whether Vue’s correct categorization should be library or framework, for the remainder of this article I’ll be referring to it as in its core library facet.

Frontend JavaScript libraries are supercool! They brought SPAs (Single Page Applications), and with them a whole new level of dynamism and user interactivity to the web.

In order to stay lightweight and performant, libraries need to make firm decisions in terms of their core functionality. They also need to be flexible and not enforce too much conventions, that would make them unusable or not easily integrated into existing projects. This is why the core Vue library does not include routing or global state management. To handle those, you’ll have to install and configure other Vue libraries.

Nuxt, contrarily, is a framework. In this regard, it can more freely abstract, manage and provide tools for common everyday tasks and configurations associated with web development - thus, allowing developers to focus on the logic of the app they’re building.

“There’s always this routine when starting a new Vue project that Nuxt helps alleviate while also applying some tried-and-true best practices to your project free of charge.” - Patrick Hanford

Client-side security and unfitness for SEO are perhaps two of the most common criticisms of SPAs.

Although there are some strategies to mitigate security concerns and make SPAs more SEO-friendly, their intrinsic nature wouldn’t make them the most immediate choice for such requirements. For such requirements, developers will generally lean more to a server-side rendering approach.

Nuxt comes to fill in this gap, powering our Vue.js apps with server-side capabilities. It’s important to note however, that SSR is not the only difference between Nuxt and Vue CLI. Nonetheless, this difference may typically be the main decision factor when choosing between one and the other.

Understanding Server-Side Rendering

Contrary to more modern SPA solutions, where JavaScript is responsible for generating HTML on the client’s browser, SSR (Server-side Rendering) is the more traditional method of rendering a web page. When the client requests a page, the origin server is responsible for executing the code (possibly fetching data from a database or API, in between), running the retrieved data against a template and returning the resulting HTML to the client.

One of the most argued disadvantages of SPAs is their inadequacy for efficient SEO. Search engines need to fetch the content of a page in order to index and rank it. Since SPAs fetch their data asynchronously, after page load, search engines have more trouble crawling the content, and thus end up not favouring SPA websites as much.

Generally speaking, server-side rendered websites are SEO-friendly by default. When the page is delivered to the client (be it a browser or a search engine crawler), all the content is already there.

In terms of performance, under similar conditions, a SSR website will typically initially be perceived as faster. Once the HTML is delivered to the client, the user will already start to see, get familiarized and interact with the DOM, even before the download of JavaScript and other assets is completed.

Of course, all this is very subjective and dependent on the specificities of each project. For example, if there’s data to be retrieved, a SSR website will only deliver the page after fetching it asynchronously. So, if the database takes long to respond, that will also have impact. (This is not to say that a SPA will not be affected by such latency, but at least we can distract the user with a colorful/spinning loader, while the request takes place.)

A SPA website, on the other hand, may have a slower first-initial load, as the whole JavaScript bundle has to be downloaded and the page rendered before the user can interact with it. However, from there on, navigating between routes is typically noticeably faster, offering a more fluid experience to the user.

In terms of memory management, normally with a SSR website you won’t have to worry as much as with a SPA. A SSR website has the advantage of each route access translating to a new server request. This allows the browser to free memory and start again from the beginning.

If not taken care of, a SPA can easily experience performance degradation, especially after a lot of navigation and user interaction within the same session.

“Part of the bargain we struck when we switched from building server-rendered websites to client-rendered SPAs is that we suddenly had to take a lot more care with the resources on the user’s device.” - Nolan Lawson

One last point about performance. SPAs will usually ship the bundle for the entire site at once - big bundle issue™, which can be noticeable specially in mobile devices.

Web development frameworks - such as Nuxt - are able to implement mechanisms of automatic code splitting, where each route gets just the code it requires, keeping the size of JavaScript more controlled.

Vue CLI vs. Nuxt.js

In the early stages of my Nuxt journey, I would ask myself whether Nuxt was simply a SSR version of Vue CLI. Well, now I know the answer is a nuanced no.

For starters, yes, Vue CLI apps are intrinsically SPAs. However, you can also build SPAs with Nuxt. Additionally, with Nuxt, you can also pre-render your pages before they get to the client’s browser, whether that’s achieved on the server (SSR) or during the build process, by generating a static site. Whichever strategy is used, when the page is delivered to the client, your site can still benefit from the interactive nature of Vue, since it “hydrates” the static markup, once it is loaded.

So, is rendering mode the only difference between the two?

No. Nuxt.js is a more opinionated, higher abstraction level framework. Indeed, anything you can build with Vue CLI can be built with Nuxt, plus you also get some extra features added on top.

With Nuxt, you don’t need to think about how to structure your code, everything has its own place already pre-established. Also, no need to install and configure Vue routing. Just place your files in the pages folder and Nuxt will automatically generate the routes according to the folder structure.

Vuex state management also comes installed by default. Add your modules under store and you’re good to go. Finally, HTML metadata management is also available, with vue-meta operating under the hood.

With these extra features in mind, even if you don’t need a SSR website, these are still benefits of using Nuxt. I’d probably almost always go with Nuxt, unless it was a really small-sized SPA (couple of routes only) with no SEO requirements.

Another scenario where you’d not want use Nuxt - which does not apply to a Nuxt statically generated site - would be if you didn’t want to deal with infrastructure and the potential costs of running a a Node.js server. Vue CLI apps can be considered easier to deploy, since they typically compile down to static assets, and thus be served from any common HTTP server or CDN.

This being said, both have their own set of more appropriate use cases, so it’s not so much as Vue CLI vs. Nuxt, but more about choosing which will best suit your requirements. If you need faster initial rendering on first-load or SEO, then Nuxt is for you. If you don’t need to worry about SEO and your app is light, then Vue CLI will work perfectly.

Developer Experience

Nuxt has an official scaffolding tool, create-nuxt-app, that guides you through some options and setups a new project, so you can quickly start developing.

This is when the app’s mode (SSR or SPA) is specified. There are also other options available, where you can choose to integrate other frameworks (server-side/UI/ testing). Linting and code formatting are also other features the tool can add to your project.

Being able to start a project without having to deal with the typical setup and configuration is great!

Out-of-the-box asset bundling - through Webpack - and code transpiling - through Babel - worked flawlessly, and we didn’t need to extend the default build configuration, nor did we run into any browser compatibility issue during the whole project!

nuxt.config.js is the central point of a Nuxt app. It lives at the project root and allows you to customize a set of features that Nuxt provides.

Having a standard, predefined folder structure, increases the team’s productivity. Everything has its place, no need tinkering about where to place files. By being layout-based, Nuxt also helps avoiding code repetition.

In dev mode, hot-reloading allows you to instantly view the results of source code changes reflected on the browser.

Asynchronously fetching data is highly facilitated through the combination of axios and the asyncData method.

Finally, building the app for production is as straightforward as npm run build followed by npm run start.

Our project runs on v2.10.2, which proved to be reliable and stable. Current version, at the time of this writing, is v2.12.2. I found Nuxt to be a robust, developer-friendly environment to work in.

Technical struggles 😰

The fact that I had to make an effort to remember any major issues faced, already speaks for itself in terms of my positive experience using Nuxt.

The only obstacles I can recall - mainly related to my incompetence with Nuxt at the time - were a few tricky DOM-related errors, such as The client-side rendered virtual DOM tree is not matching server-rendered content. and Mismatching childNodes vs. VNodes. I came to learn that these errors mostly manifest when trying to use Vue.js libraries that don’t support SSR, and therefore should only be instantiated client-side.

In the end, I was able to fix all these errors and warnings with lengthy debug sessions, by essentially trying to isolate the faulty components and applying some combination of <client-only> in the templates, and ssr: false in the plugin instantiation in nuxt.config.js. Note to self: be more watchful of the console, specially when adding a new library, that way you can detect if something is wrong as soon as you introduce it.

I also came to realize the importance of understanding the separate stages of client/server execution and how Nuxt and Vue hooks and lifecycle relate to each other.

If you’re new to Nuxt, take some time to study its core concepts, as it can save you a lot of headaches, for example when trying to figure out why you’re getting undefined when accessing the window object or why you can only query and manipulate the DOM in certain hooks.

This schema from the official docs is an essential resource to learn the sequence of steps that take place after the server receives a request:

Something I came to discover, while trying to fix the previously mentioned errors, was that we were writing some invalid HTML in our code, such as <p> elements inside of <button> elements. Although in the end it proved to be unrelated, some of the errors mentioned invalid HTML as a possible cause.

Later, with the help of a validator, we were able to identify and fix almost all the invalid HTML. I wonder if this is a feature that would make sense to have in dev mode. Maybe integrating with an already existing plugin or tool? Who knows, if this could be my first contribution to Nuxt 😃.

Community and Plugin Ecosystem

Nuxt is backed up by a strong active community. Its modular architecture is ideal for the emergence of extensions that add on to the framework’s core functionality. Plus, the entire Vue plugin ecosystem is close at hand - just make sure it supports SSR, if that’s your app’s mode.

These are some modules and plugins that made our life so much easier, helping us deliver faster and better:

@nuxtjs/auth - Authentication and Authorization
@nuxtjs/axios - Axios integration
@nuxtjs/dotenv - Loading .env vars
@nuxtjs/google-analytics - Google Analytics
@nuxtjs/gtm - Google Tag Manager
@nuxtjs/toast - Cool little toasts
nuxt-lazy-load - Effortless lazy-loading
@aceforth/nuxt-optimized-images - Image size optimization during build
vue-awesome-swiper - Swiper component
vue-slider-component - Slider component
vue-youtube - Youtube wrapper
vue-loading-overlay - Full-screen loading indicator
vue-js-modal - Handy modal

Also, don’t miss out on this curated list of awesome things related to Nuxt.js.

Was it worth it? Verdict

Yes, absolutely!

Just recently got the news from the marketing team, and last month we doubled the number of users in comparison to the previous month, with a forecast of reaching a total of 100k 🚀 users by the end of this month 🎉.

I think Nuxt.js is an amazing, production-ready framework for modern web development. If your website requires SSR, I definitely suggest you give it a try.

From the way it simplifies the setup of a project, to the solid build process, the opinionated defaults and best practices, the built-in mechanisms for asynchronously fetching data, and last but not the least, the ecosystem of available plugins and the active community - all reasons that make me really happy to have made the decision to go with Nuxt.

On a more personal note, I learned a lot during the course of this project. It was a period of massive evolution, where I had to do things I’d never done before.

There are of course, some things I would have done differently, if I was starting the project again, knowing what I know today, but they are more related to CSS and Vue, and not so much to Nuxt specifically.

That’s it, hopefully I was able to give a comprehensible rundown of my first steps getting to know and working with Nuxt 💚.

Finding the array element that appears once

Sun, 24 Nov 2019 00:00:00 GMT

A few days ago, during a job interview, I was asked to live code three exercises in JavaScript:

Palindrome check
Find the element that appears once
Fizz Buzz

Exercises 1 and 3 went pretty well. I was able to implement them correctly, even though, for Exercise 1, my initial answer didn’t cover all the edge cases (forgot about space characters and upper/lower case).

Exercise 2 was a bit trickier for me.

Given an array of integers, all the elements appear twice, except one element that appears only once. Write an algorithm to find that element.

The most obvious, brute force solution, consists of two nested loops, where each element in the array is compared with all the other elements, in order to find which element is not repeated. Time complexity of this solution is O(n^2).

I wanted to avoid an answer with such time complexity - also didn’t want to write two nested for loops. So, my first instinct was to look for a higher order function, such as, Array.prototype.find() or Array.prototype.filter(), to which I could pass a function that counted the number of occurrences of an element in the array.

Since I was allowed to check the web for syntax and built-in methods, I started searching for such a method.

I realized there’s no built-in method that does this in JavaScript and wasn’t finding a simple and elegant solution.

As I decided to implement a working solution, and worry about optimization later, the interviewer rightfully commented about the time complexity of the algorithm I was writing.

In fact, this approach also has time complexity O(n^2).

The interviewer proceeded to suggest creating an object and using the array elements as its properties, to which the corresponding values would keep a counter on the number of occurrences.

I immediately remembered doing something similar before, so I knew Array.prototype.reduce() was the way to go.

As I started to implement, I took a bit too much time to figure up the function I needed to pass to reduce() and I didn’t get the chance to finish.

So, here I am to complete this challenge and improve my understanding on how reduce() operates 😉.

This solution has time complexity O(n) and consists of using a hash map to store the count of each element. Then, it iterates through the keys and returns the key which has count 1.

function findElementOnce(arr) {
  let hash = arr.reduce((acc, value) => {
    acc.hasOwnProperty(value) ? acc[value]++ : acc[value] = 1;
    return acc;
  }, {});

  for (const key in hash) {
    if (hash[key] === 1) {
      return key;
    }
  }
}

Important notes about this solution, which became now, clearer to me:

the use of method Object.prototype.hasOwnProperty() to check whether the object already has the specified element as property.
the function that’s passed to reduce() has to return the accumulator.
the second parameter of reduce(), an empty object {}, as the initial value that is assigned to the accumulator.

During my research for this article, I’ve discovered that this challenge can also be solved efficiently, with time complexity O(n), using the operator XOR.

In fact, it can even be considered more efficient, since in terms of space complexity it has O(1), whilst the hashing solution has O(n).

function findElementOnce(arr) {
  if(arr.length == 0) return;
  let xor = arr[0];
  for (let i = 1; i < arr.length ; i++) {
    xor ^= arr[i];
  }
  return xor;
}

We know that A XOR A = 0. If we XOR all the elements in the array, the elements which are repeated twice will become 0, while the element which is appearing only once will remain.

There’s also a more complex version of this problem, where every element appears three times instead of twice, but I’ll leave it for you to dive deeper 🌊.

Creating a Pull Request on GitHub

Fri, 01 Nov 2019 00:00:00 GMT

Pull requests allow you to let others know about features and fixes that you’d like to add to a GitHub project repository.

Once you open a pull request, you’ll be able to discuss and review your proposed changes with other collaborators, adding more commits if necessary, before your changes are merged into the base branch.

With a pull request, your changes are proposed in a new branch, which ensures that the master branch only contains finished and approved work.

In this short guide, I’ll describe the basic process of submitting a pull request on GitHub.

Prerequisites

Basic knowledge of git via command line
GitHub account
A project you’d like to contribute to

Fork the repository

Sign-in to your GitHub account and fork the repository of the project you’d like to contribute to:

This creates a new repository copy, separate from the original codebase, owned by you. Modify it as you please, it will not interfere with the original project.

Clone the repository

Download a local project codebase, by cloning the repository you’ve forked:

git clone https://github.com/ramigs/JavaScript30-1.git

You can get the URL from here:

Navigate to the project folder:

cd JavaScript30-1/

Create a new branch

A git branch is simply a divergent line of development, a pointer to a different version of the codebase.

Create a new branch where you´ll make your changes. Give it a suggestive name, related to what the pull request intends to fix:

git checkout -b fix-challenge-12-cornify-https

Add your changes

Go ahead and implement your fix or new feature locally.

Confirm build, tests and docs

Make sure the changes you’ve made, still keep the build process running correctly. Run tests, if there are any, and update/regenerate the documentation, if necessary.

Most importantly, follow the contributing guidelines of the project.

Confirm updated files

Check which files have local changes pending:

git status

Validate the exact lines that were changed in each file:

git diff

Commit the changes locally

Commit the changes to your local repository:

git add .

git commit -m "Replacing http by https in cornify.js import, to avoid insecure mixed content issues in some hosting providers"

Push your branch to GitHub

git push origin fix-challenge-12-cornify-https

When the push executes, browse to your forked repo on GitHub, where GitHub will recognize the branch you’ve just pulled.

Go ahead and click Compare & Pull Request:

Open pull request

One last confirmation to the changes you’re adding, to the subject and body of your message, and you’re ready to open your pull request:

Congratulations 🎉! You’ve just submitted your pull request.

A notification was sent to the owner of the repository, with a request to merge the changes.

Now, the owner of the repository will review your changes, and if everything goes well, merge them with the main branch of the project.

How the JAMstack inspired me to start blogging

Wed, 21 Aug 2019 00:00:00 GMT

This is the story about how discovering and exploring the JAMstack has inspired me to finally kick off my blogging ventures.

I’ll also be giving an overview of what the JAMstack is - main concepts, benefits of such architectures, and how they can foster the use of modern development workflows.

This article does not intend to convey that the JAMstack is the be all end all solution for every software architecture use case out there. It does not mean to express that we should immediately be ditching all our legacy projects, replacing them with JAMStack applications.

As in most questions regarding software architecture (and life for that matter), depends usually is the better answer. Each case should be evaluated according to its specific requirements. Here, I’ll be referring to my blogging use case.

Many times throughout my developer path I’ve fiddled with the idea of starting a tech-related blog. The motivation mostly derived from the frustration caused by not having a systematic approach that allowed me to save useful commands, configurations, or certain aha moments about a language/tool I’d be learning or using at the time. I’d end up just saving stuff in a bunch of random text files that would eventually get lost.

I realized that over the years, I’ve been doing and learning so many things. All the projects I’ve worked on, the knowledge I’ve exchanged with the teams I was part of; but no reference or online trace of it, besides a couple of bullet points on my LinkedIn profile. Besides, it’s high time I start giving back in return to the tech community, which has given me so much.

That’s why I decided to start this blog, as a way to somehow condense, materialize, and share my discoveries.

Also, as far as I know, there’s no better way of solidifying knowledge about a topic than to present and explain it to others. It kind of forces us to find out exactly what we know and establish clear mental models about it.

“When you face problems that you’ve solved in the past, you don’t always remember exactly what the solution was. When you are blogging frequently, you can always search through your blog and find the answer.” - Paweł Dąbrowski

In this post, I’ll explain how opting for a JAMstack approach to build and deploy my website (and blog) frees me up, and allows me to focus on what’s really important, which is creating content to the best of my abilities.

Looking back for insight

Reflecting upon my avoidance to start a blog, I’ve recently came to terms with the reasons.

“For the longest time, I wanted to know how to make my OWN blog - not rely on Blogger, or WordPress(.com) hosting, but something I hosted myself with my own design - not someone elses theme. But how? I didn’t know how and it was immensely frustrating.” - Tania Rascia

The era of monolithic CMSs

There is this saying we’ve all seen somewhere about how Wordpress powers 30 percent of the web. Is it true? Is it false? Who knows. Though one thing is for sure: CMSs (Content management systems) deserve recognition for making content publishing much more accessible to non-technical authors.

Around 2008 or 2009, I remember trying to set up a blog. I wanted to learn how to host it myself. I had this noisy old computer in my room, running Ubuntu, where I started to do some experiments with Joomla.

Let me pause for a moment and try to recall the steps I had to take:

SSH installation - so I could login and update the site from anywhere
LAMP installation
Apache configuration
MySQL configuration
Joomla installation
Dynamic IP to static hostname configuration

After all the pieces were finally connected, I went on a theme-browsing spree. Nothing seemed to fit with what I was looking for. When I tried to change or customize something, somehow I always ended with a broken site.

Mind you, I have to admit I was very inexperienced as a developer at the time. Nevertheless, it didn’t feel as if setting up a blog should be that difficult.

Throughout my professional journey I’ve encountered numerous Wordpress sites. I’ve seen and been involved in projects where it was being used for diverse use cases. In many, it seemed like Wordpress was being selected without much consideration - besides market popularity - in terms of what the project actually needed.

“Regardless of how much experience you have, while designing a system, your priority should be meeting all the requirements with the least complexity.” - Zlatin Stanimirovv

For some of the projects, which simply served as brochure sites, Wordpress’s complexity and extended functionality was a clear overkill.

Drawbacks of having content stored in a database

Within the context of a CMS, content can take form in many different ways: posts, comments, users, roles, permissions, settings, and version control - if there’s any. Typically, with traditional monolithic CMSs, content is stored in a database. The database introduces an additional layer of complexity.

For each and every request a client makes to the CMS, content has to be retrieved from the database. Then, through the template engine, it’s rendered into HTML. Finally, the response is sent across the network to the browser that requested it.

To lighten the overhead, many web architectures end up resorting to caching mechanisms, so that the load on the database can be reduced. Well implemented caching schemes require complex setups. Improvement in performance comes at the cost of added complexity to the development process. Also, if for whatever reason you decide to migrate to a new CMS, you’d have to take into account the technical cost of exporting, transforming and importing the data to the new CMS.

With this type of architectures, web/application servers repeatedly need to consult the database and build the page for each request. But, what if the content didn’t even change? Should we really be taking all these steps to produce the resulting HTML every time? In a CMS, for example, posts are not expected to change that much. Is there any way to improve performance, by avoiding the repetition of these steps when it’s not required?

Dealing with infrastructure

I’ve mentioned how deciding to go the self-hosting route forces us to deal with the associated required setup and infrastructure.

All of those things take away a lot of time that should be put into crafting and delivering great websites and applications, not on server setup and administration.

Unless we find ways to delegate/outsource such tasks and stand on the shoulders of giants, automating and streamlining our development workflows for better productivity will be much more complicated.

Fortunately, JAMstack architectures integrate wonderfully with the rising PaaS (Platform as a Service) and IaaS (Infrastructure as a Service) ecosystems.

Towards the JAMstack

JAMstack is a modern web development architecture that delivers better performance, higher security, and lower cost of scaling.

It’s not defined by specific technologies or standards - although it encourages us to leverage the progressing capabilities of client-side JavaScript.

The JAMstack is more like a movement towards an architectural pattern, a set of best practices and development workflows that combine well together and improve the experience for both users and developers.

JAMstack stands for:

JavaScript as runtime
Reusable HTTP APIs
Prebuilt Markup

This site falls under the JAMstack umbrella. Let’s take a look at the basic steps of a typical JAMstack workflow:

The source is hosted in a repository that stores content and code together as editable text files.
Whenever a change is pushed to the repository, a build process is triggered, the site is pre-rendered, and the final HTML is created from layouts and content.
The pre-built site and prepared assets are published globally on a CDN (Content Delivery Network), putting them as close to end users as physically possible.

Content Delivery Network

A CDN consists of a series of servers distributed all around the globe, linked together. In order to improve response speed - reducing latency - a CDN distributes website assets (HTML, JavaScript, CSS, and media) so that they are reasonably physically near - to every user that might want to access the website.

Static Site Generators

Typically, the build process of a JAMstack website will be executed by a SSG (Static Site Generator).

A SSG retrieves both (1) frontend code (CSS/JavaScript assets) and (2) content from regular text files (in some structured format, such as Nunjucks or Markdown), and builds a static site.

It’s important to not misunderstand the meaning of static in this context. It should not be interpreted as in static vs dynamic user interfaces, but more as in straight HTML/CSS/JavaScript, that doesn’t need any application server or database, in order to run properly. A simple web server is enough.

With the disassembling of monolithic architectures and the separation of build, deploy, and runtime - SSGs started to gain prominence, mainly through Jekyll, Hugo, 11ty, Gatsby, and others.

Additional functionality through microservices

Even though JAMstack architectures promote the use of client browsers as runtime, there are certain tasks and logic we’d prefer to run server-side.

Advanced search, payments, and authentication are examples of such services. Also, security-wise, API keys should not be shipped with the JavaScript we deliver to the client.

One solution is to proxy these requests through microservices. Microservice architectures allow developers to build applications out of modular, smaller components and integrate with third-party services.

Frontend JavaScript acts as the glue, orchestrating microservices together, and giving us the ability to enrich our applications with additional functionality, that was generally provided through plugin ecosystems, inside monolithic CMSs.

By separating different services into smaller microservices, with well-defined purposes, we can better comprehend the system globally, instead of having to understand the inner complexities of each individual service.

Need image processing added to your workflow? Search functionality? E-commerce? The pervasiveness of service APIs allows us to outsource and delegate these responsibilities to expert service providers, instead of having to write our own implementations.

Headless CMSs as editor-friendly UIs

While it’s easy to picture developers editing text files locally and pushing them to GitHub through the command-line, what about content editors who aren’t developers and might not be familiar with Git and Markdown? For non-technical users, such workflows may not be the best solution at all.

The JAMstack has fathered a new generation of content editing tools with intuitive interfaces, that look and function like traditional CMSs, but actually push changes into version control repositories.

In this way, everyone can participate in the same workflow, enjoying the benefits of modern version control software — even if unaware about what’s happening behind the scenes.

Benefits of using a JAMstack architecture

Let’s examine some of the advantages of the JAMstack.

Less infrastructure costs

Discussing project costs is certainly very subjective, as each one has to be analyzed according to its specificities. Nonetheless, hosting infrastructure is definitely a major aspect to consider.

A JAMstack site can be served from a CDN - with all the mentioned benefits this brings - while a traditional monolithic site needs some server that builds the page every time it’s requested.

By pre-rendering a website at build time, the infrastructure costs are significantly diminished. The runtime technology cost simply becomes the cost of serving static HTML/CSS/JavaScript files.

This surely doesn’t mean that applications and services are now suddenly running on the ether, and not on physical servers. You’re probably familiar with the running joke about how the cloud is just “someone else’s computer”.

“Now we have an architectural pattern that utilizes a compute model that abstracts away infrastructure management, allowing developers to focus primarily on business logic by (at most) writing code that consumes other services.” - Jeremy Daly

The important aspect, in my opinion, is that we can now delegate infrastructure management as on-demand services (network, operating systems, storage, security, and scaling). This way, we are able to focus only on solving the business requirements of our projects, and significantly improve effort allocation of dev teams.

Performance

Performance is very important. The widespread of mobile has made us more impatient and eager for immediacy. We expect sites to load very fast, and quickly dismiss slow pages.

We also know that, for at least the last ten years, search engines have been incorporating site speed factors in their ranking algorithms.

With monolithic architectures and server-side rendering, all layers of the stack are involved - every time the user makes a request to a site or application.

So, instead of having each HTTP request build the entire page on the fly, we can instead deliver it directly to the client. This is a great way to minimize our time to first byte.

Through the asynchronous capabilities of JavaScript, we can start to think in a more modular way, having greater control over the data flow of our applications.

Security

Securing a traditional monolithic CMS involves continuous monitoring and effort. The server/infrastructure needs to be managed and kept up-to-date. Security patches need to be applied to Wordpress sites, each time a new security issue is announced.

JAMstack applications benefit from a smaller and simpler stack, when compared to traditional architectures - with their various servers and databases. By minimizing the number of layers, we also narrow down the attack surface area. If there is no backend, there is much less that can go wrong.

Workflow flexibility

Monolithic applications can undermine our ability to integrate with third-party technology, and impede changes that could benefit our development workflows.

“Monolithic applications, by definition, are a single unit. This means that deploying a monolith to production is an all or nothing proposition.” - Jeremy Daly

A poor development experience can be devastating for a project. It can impede progress and bring uncertainty. Undesired side-effects and maintenance implications.

Every developer will inevitably run into a legacy project or some old codebase, where everything just resembles a castle of cards, in danger of collapsing at any moment. No one wants to take take risks and try to innovate in such projects.

How does it feel when you jump on a project and it’s really easy to get everything running seamlessly on your machine? Pretty amazing, right?

Decoupling frontend from server functionality allows for better productivity, as different teams can focus on different parts of the project.

Decoupling build, deploy, and runtime offers a clear separation between the workflow processes - making it much easier to develop and maintain.

What I like the most about these type of workflows:

Easy local dev environment. Simply consists of cloning the repository, installing the dependencies, and running a local web server.
Integration with continuous deployment tools, HTTPS and domain configuration, all in the same workflow.
Working with text files, which allows full control over content.
Atomic deploys. The new version only goes live when everything is ready and all the assets can be served. No more error-prone FTP uploads. Trivial to roll back to any state, at any time. Complex staging environments are no longer needed, as previewing and testing changes can be done through Git’s branching system and Netlify’s workflow.

Netlify and workflow automation

Netlify is an awesome CD/CI platform I’ve been exploring lately. It lets me automate the entire workflow for my frontend web projects.

In a nutshell, a Netlify site is connected to a Git repository. Every time a change is pushed, a build tool (such as npm or gulp) is triggered. A new version of the website is generated, and Netlify automatically deploys and publishes it through a CDN.

Add Netlify to your workflow and no more wrestling with hosting, deploy rollbacks, securing, and scaling. A simple push to Git and it just takes care of itself. Really cool!

Wrapping up

The JAMstack contributes to a better developer experience, which leads to higher productivity, happier teams, and a more stable ground for innovation at all dimensions of a project.

As a developer, I chose to go with the JAMstack approach, which gives me total workflow flexibility and ownership over my content.

At the end of the day, striving for better content creation is easier when we have full control. The JAMstack makes this possible - and as a bonus, it also contributes to a faster, more stable and secure web experience for both users and developers.

If you’re interested to learn more about the JAMstack, I recommend a great book called Modern Web Development on the JAMstack, by Mathias Biilmann & Phil Hawksworth. It provides real world use cases of the JAMstack.

Acknowledgements

Before ending my official first blog post ever 🚀, I want to give a shout-out 📣 to:

Tania Rascia, for the inspiration in terms of writing and presentation style.
Webstoemp, for the amazing Gulp pipeline, which I’m using as a boilerplate for building this site.