/reticle/blog PhD researcher and engineer writing about autonomous systems, web technologies, and software design. Zola en Tue, 28 Jul 2026 00:00:00 +0000 Tue, 28 Jul 2026 00:00:00 +0000 Unknown /reticle/blog/blog/customizing-reticle-colors/ /reticle/blog/blog/customizing-reticle-colors/ <p>Reticle uses an <strong>instrument-reading color system</strong>: blueprint-paper ground (<code>--paper</code>), petrol ink (<code>--ink</code>), and three semantic accents that carry meaning rather than decoration.</p> <h2 id="the-semantic-accents">The Semantic Accents</h2> <p>Reticle's color system revolves around three core state accents:</p> <table><thead><tr><th>Token</th><th>Hue</th><th>Meaning</th></tr></thead><tbody> <tr><td><code>--proved</code></td><td>Teal (<code>#0e6b5e</code> / <code>#5fc9b6</code>)</td><td>Proved, confirmed, cleared, done</td></tr> <tr><td><code>--obligation</code></td><td>Violet (<code>#5340bb</code> / <code>#a99bf5</code>)</td><td>Owed, awaiting judgement, in progress (also the primary UI accent)</td></tr> <tr><td><code>--blocking</code></td><td>Red (<code>#a01c12</code> / <code>#ef8377</code>)</td><td>Blocking, error, destructive action</td></tr> </tbody></table> <h2 id="core-color-tokens">Core Color Tokens</h2> <h3 id="ground-inks">Ground &amp; Inks</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">:</span><span style="color: #94E2D5;">root</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --paper</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>0c151a</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* Deep blueprint dark canvas */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --paper-2</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>111d24</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* Sidebar and panel background */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --card</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>14222a</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* Lifted surface background */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --ink</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>e6eef1</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* Primary text */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --ink-2</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>9fb2bb</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* Secondary text */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --ink-3</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>708590</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* Muted labels &amp; dates */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --rule</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>2a3d47</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* Primary borders */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --rule-soft</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>1e2e37</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* Soft dividers */</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="signature-element-margin-tape">Signature Element: Margin Tape</h3> <p>Reticle includes a <strong>margin tape</strong> component (<code>.tape</code>) — a 3px left border whose color indicates the state of the content beside it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="html"><span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">div</span><span style="color: #F9E2AF;"> class</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;tape&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &lt;</span><span style="color: #89B4FA;">div</span><span style="color: #F9E2AF;"> class</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;tape__rail tape__rail--obligation&quot;</span><span style="color: #94E2D5;">&gt;&lt;/</span><span style="color: #89B4FA;">div</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &lt;</span><span style="color: #89B4FA;">div</span><span style="color: #F9E2AF;"> class</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;tape__body&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &lt;</span><span style="color: #89B4FA;">p</span><span style="color: #94E2D5;">&gt;</span><span>This item requires your review.</span><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">p</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &lt;/</span><span style="color: #89B4FA;">div</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">div</span><span style="color: #94E2D5;">&gt;</span></span></code></pre><h2 id="overriding-tokens-in-extra-css">Overriding Tokens in Extra CSS</h2> <p>You can override any token in your site's custom CSS file:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">:</span><span style="color: #94E2D5;">root</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> /* Customize the primary UI accent */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --obligation</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>6366f1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --obligation-bg</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>1e1b4b</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Enjoy customizing your Reticle site!</p> Fri, 27 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/welcome-to-reticle/ /reticle/blog/blog/welcome-to-reticle/ <h1 id="welcome-to-reticle">Welcome to Reticle</h1> <p>We're excited to introduce Reticle, a new Zola theme that brings joy and whimsy to your documentation, books, and blogs.</p> <h2 id="why-reticle">Why Reticle?</h2> <p>The reticle (Japanese raccoon dog) is a beloved creature in Japanese folklore, known for being playful, mischievous, and a little magical. We chose this name because our theme embodies those same qualities—it's fun to use, delightful to look at, and just a bit magical in how it transforms your content.</p> <h2 id="three-modes-one-theme">Three Modes, One Theme</h2> <p>Reticle supports three distinct modes:</p> <ol> <li><strong>Documentation Mode</strong> - Perfect for API docs and technical references</li> <li><strong>E-Book Mode</strong> - Ideal for tutorials, courses, and long-form content</li> <li><strong>Blog Mode</strong> - Great for personal sites, portfolios, and announcements</li> </ol> <p>Each mode is optimized for its purpose while maintaining a consistent, cohesive design language.</p> <h2 id="features-you-ll-love">Features You'll Love</h2> <h3 id="catppuccin-colors">Catppuccin Colors</h3> <p>We use the beautiful <a rel="external" href="https://github.com/catppuccin/catppuccin">Catppuccin</a> color palette, with Mocha for dark mode and Latte for light mode. The colors are warm, inviting, and easy on the eyes during long reading sessions.</p> <h3 id="nintendo-inspired-ux">Nintendo-Inspired UX</h3> <p>Inspired by games like Animal Crossing and Super Mario Odyssey, we've added subtle animations and interactions that make using the theme feel delightful. Watch the theme toggle sparkle when you click it!</p> <h3 id="full-text-search">Full-Text Search</h3> <p>Press <code>/</code> anywhere to search your entire site instantly. Powered by Elasticlunr, it's fast and works offline.</p> <h2 id="getting-started">Getting Started</h2> <p>Adding Reticle to your project is simple:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">git</span><span style="color: #A6E3A1;"> submodule add https://github.com/lokeshmohanty/reticle themes/reticle</span></span></code></pre> <p>Then add to your <code>config.toml</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span>theme</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;reticle&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>extra</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>mode</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;site&quot;</span><span style="color: #9399B2;font-style: italic;"> # or &quot;docs&quot; or &quot;book&quot;</span></span></code></pre><h2 id="what-s-next">What's Next?</h2> <p>We're just getting started! Upcoming features include:</p> <ul> <li>More theme color options</li> <li>Additional page templates</li> <li>Enhanced print stylesheets</li> <li>Improved accessibility features</li> </ul> <p>Stay tuned for more updates, and happy building!</p> Thu, 26 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/getting-started-with-zola/ /reticle/blog/blog/getting-started-with-zola/ <h1 id="getting-started-with-zola">Getting Started with Zola</h1> <p>Zola is a fast static site generator written in Rust. It's what powers the Reticle theme, and it's a joy to work with.</p> <h2 id="why-zola">Why Zola?</h2> <p>There are many static site generators out there—Jekyll, Hugo, Eleventy, Next.js—so why choose Zola?</p> <h3 id="speed">Speed</h3> <p>Zola is incredibly fast. A typical site builds in milliseconds, not seconds. This makes development pleasant and deployments quick.</p> <h3 id="single-binary">Single Binary</h3> <p>Unlike Jekyll (Ruby) or Eleventy (Node.js), Zola is a single binary with no dependencies. Download it, run it, done.</p> <h3 id="built-in-features">Built-in Features</h3> <p>Zola includes everything you need out of the box:</p> <ul> <li>Sass compilation</li> <li>Syntax highlighting</li> <li>Search index generation</li> <li>Image processing</li> <li>Shortcodes</li> <li>Taxonomies (tags, categories)</li> <li>Multilingual support</li> </ul> <p>No plugins to install, no configuration rabbit holes.</p> <h2 id="installation">Installation</h2> <h3 id="macos-homebrew">macOS (Homebrew)</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">brew</span><span style="color: #A6E3A1;"> install zola</span></span></code></pre><h3 id="linux">Linux</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Snap</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">snap</span><span style="color: #A6E3A1;"> install zola --edge</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Or download from GitHub releases</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">wget</span><span style="color: #A6E3A1;"> https://github.com/getzola/zola/releases/download/v0.19.2/zola-v0.19.2-x86_64-unknown-linux-gnu.tar.gz</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">tar</span><span style="color: #A6E3A1;"> xzf zola-</span><span>*</span><span style="color: #A6E3A1;">.tar.gz</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">sudo</span><span style="color: #A6E3A1;"> mv zola /usr/local/bin/</span></span></code></pre><h3 id="windows">Windows</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="powershell"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Scoop</span></span> <span class="giallo-l"><span>scoop install zola</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Or Chocolatey</span></span> <span class="giallo-l"><span>choco install zola</span></span></code></pre><h2 id="creating-a-new-site">Creating a New Site</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">zola</span><span style="color: #A6E3A1;"> init my-site</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> my-site</span></span></code></pre> <p>Zola will ask a few questions about your site configuration. Answer them, and you'll have a basic structure:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>my-site/</span></span> <span class="giallo-l"><span>├── config.toml</span></span> <span class="giallo-l"><span>├── content/</span></span> <span class="giallo-l"><span>├── sass/</span></span> <span class="giallo-l"><span>├── static/</span></span> <span class="giallo-l"><span>├── templates/</span></span> <span class="giallo-l"><span>└── themes/</span></span></code></pre><h2 id="adding-content">Adding Content</h2> <p>Content goes in the <code>content/</code> directory as Markdown files:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="markdown"><span class="giallo-l"><span>+++</span></span> <span class="giallo-l"><span>title = &quot;My First Post&quot;</span></span> <span class="giallo-l"><span>date = 2024-12-27</span></span> <span class="giallo-l"><span>+++</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F38BA8;"># Hello, World!</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>This is my first post using Zola.</span></span></code></pre> <p>The <code>+++</code> section is called front matter—it's TOML by default and contains metadata about your page.</p> <h2 id="development-server">Development Server</h2> <p>Run the development server:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">zola</span><span style="color: #A6E3A1;"> serve</span></span></code></pre> <p>Open http://127.0.0.1:1111 and you'll see your site. Changes trigger automatic rebuilds and browser refresh.</p> <h2 id="building-for-production">Building for Production</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">zola</span><span style="color: #A6E3A1;"> build</span></span></code></pre> <p>Your complete site will be in the <code>public/</code> directory, ready to deploy anywhere.</p> <h2 id="next-steps">Next Steps</h2> <ul> <li>Read the <a rel="external" href="https://www.getzola.org/documentation/">Zola documentation</a></li> <li>Explore the <a href="/docs/">Reticle theme documentation</a></li> <li>Join the <a rel="external" href="https://discord.gg/WN8n6xqp">Zola Discord</a></li> </ul> <p>Happy building!</p> Thu, 26 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/testing-strategies/ /reticle/blog/blog/testing-strategies/ <h1 id="testing-strategies-that-actually-work">Testing Strategies That Actually Work</h1> <p>The goal of testing isn't 100% coverage. It's confidence to ship.</p> <h2 id="the-testing-trophy">The Testing Trophy</h2> <p>Forget the pyramid. Think trophy:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span> ╱╲</span></span> <span class="giallo-l"><span> ╱ ╲ E2E (few)</span></span> <span class="giallo-l"><span> ╱────╲</span></span> <span class="giallo-l"><span> ╱ ╲ Integration (most)</span></span> <span class="giallo-l"><span> ╱────────╲</span></span> <span class="giallo-l"><span> ╱ ╲ Unit (some)</span></span> <span class="giallo-l"><span> ╱────────────╲</span></span> <span class="giallo-l"><span> │ Static Types │</span></span> <span class="giallo-l"><span> └──────────────┘</span></span></code></pre> <p><strong>Static analysis</strong> catches the most bugs with the least effort.</p> <h2 id="unit-tests">Unit Tests</h2> <p>Test pure functions and isolated logic:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// utils.test.js</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">import</span><span style="color: #9399B2;"> {</span><span> formatCurrency</span><span style="color: #9399B2;">,</span><span> calculateDiscount</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;./utils&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">describe</span><span>(</span><span style="color: #A6E3A1;">&#39;formatCurrency&#39;</span><span style="color: #9399B2;">, ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> it</span><span>(</span><span style="color: #A6E3A1;">&#39;formats positive amounts&#39;</span><span style="color: #9399B2;">, ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(</span><span style="color: #89B4FA;font-style: italic;">formatCurrency</span><span>(</span><span style="color: #FAB387;">1234.5</span><span>))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toBe</span><span>(</span><span style="color: #A6E3A1;">&#39;$1,234.50&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> it</span><span>(</span><span style="color: #A6E3A1;">&#39;handles zero&#39;</span><span style="color: #9399B2;">, ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(</span><span style="color: #89B4FA;font-style: italic;">formatCurrency</span><span>(</span><span style="color: #FAB387;">0</span><span>))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toBe</span><span>(</span><span style="color: #A6E3A1;">&#39;$0.00&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> it</span><span>(</span><span style="color: #A6E3A1;">&#39;formats negative amounts&#39;</span><span style="color: #9399B2;">, ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(</span><span style="color: #89B4FA;font-style: italic;">formatCurrency</span><span>(</span><span style="color: #94E2D5;">-</span><span style="color: #FAB387;">50</span><span>))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toBe</span><span>(</span><span style="color: #A6E3A1;">&#39;-$50.00&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">describe</span><span>(</span><span style="color: #A6E3A1;">&#39;calculateDiscount&#39;</span><span style="color: #9399B2;">, ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> it</span><span>(</span><span style="color: #A6E3A1;">&#39;applies percentage discount&#39;</span><span style="color: #9399B2;">, ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(</span><span style="color: #89B4FA;font-style: italic;">calculateDiscount</span><span>(</span><span style="color: #FAB387;">100</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0.2</span><span>))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toBe</span><span>(</span><span style="color: #FAB387;">80</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> it</span><span>(</span><span style="color: #A6E3A1;">&#39;never goes below zero&#39;</span><span style="color: #9399B2;">, ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(</span><span style="color: #89B4FA;font-style: italic;">calculateDiscount</span><span>(</span><span style="color: #FAB387;">10</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span>))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toBe</span><span>(</span><span style="color: #FAB387;">0</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span>)</span><span style="color: #9399B2;">;</span></span></code></pre><h3 id="when-to-unit-test">When to Unit Test</h3> <ul> <li>Pure functions</li> <li>Complex business logic</li> <li>Utility functions</li> <li>State reducers</li> <li>Data transformations</li> </ul> <h3 id="when-not-to-unit-test">When NOT to Unit Test</h3> <ul> <li>Simple getters/setters</li> <li>Framework code</li> <li>Implementation details</li> <li>One-liner functions</li> </ul> <h2 id="integration-tests">Integration Tests</h2> <p>Test how pieces work together:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// api.test.js</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">import</span><span style="color: #9399B2;"> {</span><span> createServer</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;../server&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">import</span><span style="color: #9399B2;"> {</span><span> db</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;../database&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">describe</span><span>(</span><span style="color: #A6E3A1;">&#39;POST /users&#39;</span><span style="color: #9399B2;">, ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> server</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> beforeAll</span><span>(</span><span style="color: #CBA6F7;">async</span><span style="color: #9399B2;"> ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> server</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> await</span><span style="color: #89B4FA;font-style: italic;"> createServer</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> db</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">migrate</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> afterAll</span><span>(</span><span style="color: #CBA6F7;">async</span><span style="color: #9399B2;"> ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> db</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">close</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> server</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">close</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> beforeEach</span><span>(</span><span style="color: #CBA6F7;">async</span><span style="color: #9399B2;"> ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> db</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">truncate</span><span>(</span><span style="color: #A6E3A1;">&#39;users&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> it</span><span>(</span><span style="color: #A6E3A1;">&#39;creates a user and returns 201&#39;</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> async</span><span style="color: #9399B2;"> ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> const</span><span> response</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> await</span><span> server</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">inject</span><span>(</span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span> method</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;POST&#39;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;/users&#39;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> payload</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> email</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;test@example.com&#39;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;Test User&#39;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(response</span><span style="color: #94E2D5;">.</span><span>statusCode)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toBe</span><span>(</span><span style="color: #FAB387;">201</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(response</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">json</span><span>())</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toMatchObject</span><span>(</span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span> email</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;test@example.com&#39;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;Test User&#39;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Verify database</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> const</span><span> user</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> await</span><span> db</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">query</span><span>(</span><span style="color: #A6E3A1;">&#39;SELECT * FROM users WHERE email = $1&#39;</span><span style="color: #9399B2;">,</span><span> [</span><span style="color: #A6E3A1;">&#39;test@example.com&#39;</span><span>])</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(user)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toBeDefined</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> it</span><span>(</span><span style="color: #A6E3A1;">&#39;returns 400 for invalid email&#39;</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> async</span><span style="color: #9399B2;"> ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> const</span><span> response</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> await</span><span> server</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">inject</span><span>(</span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span> method</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;POST&#39;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;/users&#39;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> payload</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> email</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;not-an-email&#39;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;Test&#39;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(response</span><span style="color: #94E2D5;">.</span><span>statusCode)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toBe</span><span>(</span><span style="color: #FAB387;">400</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(response</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">json</span><span>()</span><span style="color: #94E2D5;">.</span><span>error</span><span style="color: #94E2D5;">.</span><span>code)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toBe</span><span>(</span><span style="color: #A6E3A1;">&#39;VALIDATION_ERROR&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span>)</span><span style="color: #9399B2;">;</span></span></code></pre><h2 id="component-tests-frontend">Component Tests (Frontend)</h2> <p>Test components with realistic interactions:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// UserProfile.test.jsx</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">import</span><span style="color: #9399B2;"> {</span><span> render</span><span style="color: #9399B2;">,</span><span> screen</span><span style="color: #9399B2;">,</span><span> waitFor</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;@testing-library/react&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">import</span><span> userEvent</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;@testing-library/user-event&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">import</span><span style="color: #9399B2;"> {</span><span> UserProfile</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;./UserProfile&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">import</span><span style="color: #9399B2;"> {</span><span> server</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;../mocks/server&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">import</span><span style="color: #9399B2;"> {</span><span> rest</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;msw&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">describe</span><span>(</span><span style="color: #A6E3A1;">&#39;UserProfile&#39;</span><span style="color: #9399B2;">, ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> it</span><span>(</span><span style="color: #A6E3A1;">&#39;displays user information&#39;</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> async</span><span style="color: #9399B2;"> ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> render</span><span>(</span><span style="color: #94E2D5;">&lt;</span><span style="color: #F5C2E7;">UserProfile</span><span style="color: #F9E2AF;"> userId</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;123&quot;</span><span style="color: #94E2D5;"> /&gt;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span style="color: #89B4FA;font-style: italic;"> waitFor</span><span>(</span><span style="color: #9399B2;">()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(screen</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">getByRole</span><span>(</span><span style="color: #A6E3A1;">&#39;heading&#39;</span><span>))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toHaveTextContent</span><span>(</span><span style="color: #A6E3A1;">&#39;Jane Doe&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(screen</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">getByText</span><span>(</span><span style="color: #A6E3A1;">&#39;jane@example.com&#39;</span><span>))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toBeInTheDocument</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> it</span><span>(</span><span style="color: #A6E3A1;">&#39;handles edit mode&#39;</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> async</span><span style="color: #9399B2;"> ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> const</span><span> user</span><span style="color: #94E2D5;"> =</span><span> userEvent</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">setup</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> render</span><span>(</span><span style="color: #94E2D5;">&lt;</span><span style="color: #F5C2E7;">UserProfile</span><span style="color: #F9E2AF;"> userId</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;123&quot;</span><span style="color: #94E2D5;"> /&gt;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> user</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">click</span><span>(screen</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">getByRole</span><span>(</span><span style="color: #A6E3A1;">&#39;button&#39;</span><span style="color: #9399B2;">, {</span><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F5C2E7;"> /</span><span style="color: #A6E3A1;">edit</span><span style="color: #F5C2E7;">/</span><span style="color: #CBA6F7;">i</span><span style="color: #9399B2;"> }</span><span>))</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> const</span><span> input</span><span style="color: #94E2D5;"> =</span><span> screen</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">getByLabelText</span><span>(</span><span style="color: #F5C2E7;">/</span><span style="color: #A6E3A1;">name</span><span style="color: #F5C2E7;">/</span><span style="color: #CBA6F7;">i</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> user</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clear</span><span>(input)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> user</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">type</span><span>(input</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &#39;Jane Smith&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> user</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">click</span><span>(screen</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">getByRole</span><span>(</span><span style="color: #A6E3A1;">&#39;button&#39;</span><span style="color: #9399B2;">, {</span><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F5C2E7;"> /</span><span style="color: #A6E3A1;">save</span><span style="color: #F5C2E7;">/</span><span style="color: #CBA6F7;">i</span><span style="color: #9399B2;"> }</span><span>))</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span style="color: #89B4FA;font-style: italic;"> waitFor</span><span>(</span><span style="color: #9399B2;">()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(screen</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">getByRole</span><span>(</span><span style="color: #A6E3A1;">&#39;heading&#39;</span><span>))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toHaveTextContent</span><span>(</span><span style="color: #A6E3A1;">&#39;Jane Smith&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> it</span><span>(</span><span style="color: #A6E3A1;">&#39;shows error state&#39;</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> async</span><span style="color: #9399B2;"> ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> server</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">use</span><span>(</span></span> <span class="giallo-l"><span> rest</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span>(</span><span style="color: #A6E3A1;">&#39;/api/users/:id&#39;</span><span style="color: #9399B2;">, (</span><span style="color: #EBA0AC;font-style: italic;">req</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;font-style: italic;"> res</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;font-style: italic;"> ctx</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #89B4FA;font-style: italic;"> res</span><span>(ctx</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">status</span><span>(</span><span style="color: #FAB387;">500</span><span>))</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span></span> <span class="giallo-l"><span> )</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> render</span><span>(</span><span style="color: #94E2D5;">&lt;</span><span style="color: #F5C2E7;">UserProfile</span><span style="color: #F9E2AF;"> userId</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;123&quot;</span><span style="color: #94E2D5;"> /&gt;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span style="color: #89B4FA;font-style: italic;"> waitFor</span><span>(</span><span style="color: #9399B2;">()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(screen</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">getByRole</span><span>(</span><span style="color: #A6E3A1;">&#39;alert&#39;</span><span>))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toHaveTextContent</span><span>(</span><span style="color: #F5C2E7;">/</span><span style="color: #A6E3A1;">failed to load</span><span style="color: #F5C2E7;">/</span><span style="color: #CBA6F7;">i</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span>)</span><span style="color: #9399B2;">;</span></span></code></pre><h2 id="e2e-tests">E2E Tests</h2> <p>Test critical user journeys:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// checkout.spec.js (Playwright)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">import</span><span style="color: #9399B2;"> {</span><span> test</span><span style="color: #9399B2;">,</span><span> expect</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;@playwright/test&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>test</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">describe</span><span>(</span><span style="color: #A6E3A1;">&#39;Checkout Flow&#39;</span><span style="color: #9399B2;">, ()</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> test</span><span>(</span><span style="color: #A6E3A1;">&#39;completes purchase successfully&#39;</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> async</span><span style="color: #9399B2;"> ({</span><span style="color: #EBA0AC;font-style: italic;"> page</span><span style="color: #9399B2;"> })</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Add item to cart</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">goto</span><span>(</span><span style="color: #A6E3A1;">&#39;/products/widget&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">click</span><span>(</span><span style="color: #A6E3A1;">&#39;button:has-text(&quot;Add to Cart&quot;)&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Go to checkout</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">click</span><span>(</span><span style="color: #A6E3A1;">&#39;a:has-text(&quot;Checkout&quot;)&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Fill shipping</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">fill</span><span>(</span><span style="color: #A6E3A1;">&#39;[name=&quot;email&quot;]&#39;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &#39;test@example.com&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">fill</span><span>(</span><span style="color: #A6E3A1;">&#39;[name=&quot;address&quot;]&#39;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &#39;123 Main St&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">fill</span><span>(</span><span style="color: #A6E3A1;">&#39;[name=&quot;city&quot;]&#39;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &#39;Portland&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">selectOption</span><span>(</span><span style="color: #A6E3A1;">&#39;[name=&quot;state&quot;]&#39;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &#39;OR&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">fill</span><span>(</span><span style="color: #A6E3A1;">&#39;[name=&quot;zip&quot;]&#39;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &#39;97201&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Fill payment (test card)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">fill</span><span>(</span><span style="color: #A6E3A1;">&#39;[name=&quot;cardNumber&quot;]&#39;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &#39;4242424242424242&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">fill</span><span>(</span><span style="color: #A6E3A1;">&#39;[name=&quot;expiry&quot;]&#39;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &#39;12/25&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">fill</span><span>(</span><span style="color: #A6E3A1;">&#39;[name=&quot;cvc&quot;]&#39;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &#39;123&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Submit</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">click</span><span>(</span><span style="color: #A6E3A1;">&#39;button:has-text(&quot;Place Order&quot;)&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Verify success</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">locator</span><span>(</span><span style="color: #A6E3A1;">&#39;h1&#39;</span><span>))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toHaveText</span><span>(</span><span style="color: #A6E3A1;">&#39;Order Confirmed&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span style="color: #89B4FA;font-style: italic;"> expect</span><span>(page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">locator</span><span>(</span><span style="color: #A6E3A1;">&#39;.order-number&#39;</span><span>))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toBeVisible</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span>)</span><span style="color: #9399B2;">;</span></span></code></pre><h3 id="e2e-best-practices">E2E Best Practices</h3> <ul> <li>Test happy paths thoroughly</li> <li>Use realistic test data</li> <li>Run in CI on every PR</li> <li>Keep tests independent</li> <li>Use test IDs for stability</li> </ul> <h2 id="what-not-to-test">What NOT to Test</h2> <ul> <li>Third-party libraries</li> <li>Framework internals</li> <li>Private implementation details</li> <li>Simple pass-through code</li> <li>Autogenerated code</li> </ul> <h2 id="test-data-strategies">Test Data Strategies</h2> <h3 id="factories">Factories</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// factories/user.js</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">import</span><span style="color: #9399B2;"> {</span><span> faker</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;@faker-js/faker&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">export function</span><span style="color: #89B4FA;font-style: italic;"> createUser</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;font-style: italic;">overrides</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {}) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> faker</span><span style="color: #94E2D5;">.</span><span>string</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">uuid</span><span>()</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> email</span><span style="color: #94E2D5;">:</span><span> faker</span><span style="color: #94E2D5;">.</span><span>internet</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">email</span><span>()</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span> faker</span><span style="color: #94E2D5;">.</span><span>person</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">fullName</span><span>()</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> createdAt</span><span style="color: #94E2D5;">:</span><span> faker</span><span style="color: #94E2D5;">.</span><span>date</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">past</span><span>()</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ...</span><span>overrides</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// In tests</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> user</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> createUser</span><span>(</span><span style="color: #9399B2;">{</span><span> email</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;specific@test.com&#39;</span><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span></code></pre><h3 id="fixtures">Fixtures</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// fixtures/users.json</span></span> <span class="giallo-l"><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;admin&quot;</span><span>:</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;id&quot;</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;admin-001&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;email&quot;</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;admin@example.com&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;role&quot;</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;admin&quot;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;regular&quot;</span><span>:</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;id&quot;</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;user-001&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;email&quot;</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;user@example.com&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;role&quot;</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;user&quot;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="measuring-test-quality">Measuring Test Quality</h2> <p>Coverage is a <strong>floor</strong>, not a <strong>ceiling</strong>.</p> <p>Better metrics:</p> <ul> <li><strong>Mutation score</strong>: Do tests catch bugs?</li> <li><strong>Flakiness rate</strong>: Are tests reliable?</li> <li><strong>Time to run</strong>: Are tests fast enough?</li> <li><strong>Maintenance cost</strong>: Are tests easy to update?</li> </ul> <h2 id="quick-guidelines">Quick Guidelines</h2> <table><thead><tr><th>Test Type</th><th>Speed</th><th>Confidence</th><th>Quantity</th></tr></thead><tbody> <tr><td>Static</td><td>Instant</td><td>Medium</td><td>All code</td></tr> <tr><td>Unit</td><td>Fast</td><td>Low-Medium</td><td>Some</td></tr> <tr><td>Integration</td><td>Medium</td><td>High</td><td>Most</td></tr> <tr><td>E2E</td><td>Slow</td><td>Highest</td><td>Few</td></tr> </tbody></table> <p>Write tests that give you confidence to ship, not tests that give you coverage badges.</p> Wed, 25 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/docker-essentials/ /reticle/blog/blog/docker-essentials/ <h1 id="docker-essentials-for-developers">Docker Essentials for Developers</h1> <p>"Works on my machine" used to be a punchline. Docker makes it a guarantee.</p> <h2 id="core-concepts">Core Concepts</h2> <p><strong>Image</strong>: A read-only template with your application and dependencies.</p> <p><strong>Container</strong>: A running instance of an image.</p> <p><strong>Dockerfile</strong>: Instructions to build an image.</p> <p><strong>Registry</strong>: Storage for images (Docker Hub, GitHub Container Registry).</p> <h2 id="your-first-dockerfile">Your First Dockerfile</h2> <p>For a Node.js application:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="docker"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Start from a base image</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">FROM</span><span> node:20-alpine</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Set working directory</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">WORKDIR</span><span> /app</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Copy package files first (for caching)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">COPY</span><span> package*.json ./</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Install dependencies</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">RUN</span><span> npm ci --only=production</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Copy application code</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">COPY</span><span> . .</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Expose the port</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">EXPOSE</span><span> 3000</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Run the application</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">CMD</span><span> [</span><span style="color: #A6E3A1;">&quot;node&quot;</span><span>, </span><span style="color: #A6E3A1;">&quot;server.js&quot;</span><span>]</span></span></code></pre> <p>Build and run:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> build -t myapp .</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> run -p 3000:3000 myapp</span></span></code></pre><h2 id="layer-caching">Layer Caching</h2> <p>Docker caches layers. Order matters:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="docker"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Bad: reinstalls deps on any code change</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">COPY</span><span> . .</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">RUN</span><span> npm install</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Good: deps only reinstall when package.json changes</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">COPY</span><span> package*.json ./</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">RUN</span><span> npm install</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">COPY</span><span> . .</span></span></code></pre><h2 id="multi-stage-builds">Multi-Stage Builds</h2> <p>Keep production images small:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="docker"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Build stage</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">FROM</span><span> node:20 </span><span style="color: #CBA6F7;">AS</span><span> builder</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">WORKDIR</span><span> /app</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">COPY</span><span> package*.json ./</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">RUN</span><span> npm ci</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">COPY</span><span> . .</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">RUN</span><span> npm run build</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Production stage</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">FROM</span><span> node:20-alpine</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">WORKDIR</span><span> /app</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">COPY</span><span> --from=builder /app/dist ./dist</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">COPY</span><span> --from=builder /app/node_modules ./node_modules</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">EXPOSE</span><span> 3000</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">CMD</span><span> [</span><span style="color: #A6E3A1;">&quot;node&quot;</span><span>, </span><span style="color: #A6E3A1;">&quot;dist/server.js&quot;</span><span>]</span></span></code></pre> <p>Result: A fraction of the size.</p> <h2 id="docker-compose">Docker Compose</h2> <p>Define multi-container applications:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># docker-compose.yml</span></span> <span class="giallo-l"><span style="color: #89B4FA;">services</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> web</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> build</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> .</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> ports</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> &quot;3000:3000&quot;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> environment</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> DATABASE_URL=postgres://db:5432/myapp</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> depends_on</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> db</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;"> db</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> image</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> postgres:16-alpine</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> environment</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> POSTGRES_DB=myapp</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> POSTGRES_PASSWORD=secret</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> volumes</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> postgres_data:/var/lib/postgresql/data</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;">volumes</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> postgres_data</span><span style="color: #94E2D5;">:</span></span></code></pre> <p>Run everything:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> compose up -d</span></span></code></pre><h2 id="essential-commands">Essential Commands</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Images</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> build -t name:tag .</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> images</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> rmi image_name</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Containers</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> run -d -p 8080:80 nginx</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> ps</span><span style="color: #9399B2;font-style: italic;"> # Running containers</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> ps -a</span><span style="color: #9399B2;font-style: italic;"> # All containers</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> stop container_id</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> rm container_id</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Logs and debugging</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> logs container_id</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> logs -f container_id</span><span style="color: #9399B2;font-style: italic;"> # Follow logs</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> exec -it container_id sh</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Cleanup</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> system prune</span><span style="color: #9399B2;font-style: italic;"> # Remove unused data</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> system prune -a</span><span style="color: #9399B2;font-style: italic;"> # Remove everything unused</span></span></code></pre><h2 id="volumes-persistent-data">Volumes: Persistent Data</h2> <p>Data inside containers is ephemeral. Use volumes:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Named volume</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> run -v mydata:/app/data myapp</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Bind mount (development)</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> run -v</span><span style="color: #9399B2;"> $(</span><span style="color: #F38BA8;font-style: italic;">pwd</span><span style="color: #9399B2;">)</span><span style="color: #A6E3A1;">:/app myapp</span></span></code></pre> <p>In Compose:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #89B4FA;">services</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> app</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> volumes</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> ./src:/app/src</span><span style="color: #9399B2;font-style: italic;"> # Bind mount for hot reload</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> node_modules:/app/node_modules</span><span style="color: #9399B2;font-style: italic;"> # Named volume</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;">volumes</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> node_modules</span><span style="color: #94E2D5;">:</span></span></code></pre><h2 id="environment-variables">Environment Variables</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="docker"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Default value in Dockerfile</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">ENV</span><span> NODE_ENV=production</span></span></code></pre> <p>Override at runtime:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> run -e NODE_ENV=development myapp</span></span></code></pre> <p>Or use <code>.env</code> files with Compose:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #89B4FA;">services</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> app</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> env_file</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> .env</span></span></code></pre><h2 id="health-checks">Health Checks</h2> <p>Let Docker know if your app is healthy:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="docker"><span class="giallo-l"><span style="color: #CBA6F7;">HEALTHCHECK</span><span> --interval=30s --timeout=3s --start-period=5s \</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> CMD</span><span> curl -f http://localhost:3000/health || exit 1</span></span></code></pre><h2 id="security-best-practices">Security Best Practices</h2> <h3 id="don-t-run-as-root">Don't run as root</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="docker"><span class="giallo-l"><span style="color: #CBA6F7;">RUN</span><span> addgroup -S appgroup &amp;&amp; adduser -S appuser -G appgroup</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">USER</span><span> appuser</span></span></code></pre><h3 id="use-specific-image-tags">Use specific image tags</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="docker"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Bad: unpredictable</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">FROM</span><span> node:latest</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Good: reproducible</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">FROM</span><span> node:20.10-alpine3.18</span></span></code></pre><h3 id="don-t-store-secrets-in-images">Don't store secrets in images</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Bad</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">ENV</span><span style="color: #A6E3A1;"> API_KEY=secret123</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Good: pass at runtime</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> run -e API_KEY=</span><span>$API_KEY</span><span style="color: #A6E3A1;"> myapp</span></span></code></pre><h2 id="dockerignore">.dockerignore</h2> <p>Keep images lean:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>node_modules</span></span> <span class="giallo-l"><span>.git</span></span> <span class="giallo-l"><span>.env</span></span> <span class="giallo-l"><span>*.md</span></span> <span class="giallo-l"><span>Dockerfile</span></span> <span class="giallo-l"><span>docker-compose.yml</span></span> <span class="giallo-l"><span>.dockerignore</span></span> <span class="giallo-l"><span>coverage</span></span> <span class="giallo-l"><span>.nyc_output</span></span></code></pre><h2 id="development-workflow">Development Workflow</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># docker-compose.dev.yml</span></span> <span class="giallo-l"><span style="color: #89B4FA;">services</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> app</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> build</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> context</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> .</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> dockerfile</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> Dockerfile.dev</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> volumes</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> .:/app</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> /app/node_modules</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> environment</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> NODE_ENV=development</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> command</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> npm run dev</span></span></code></pre><pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> compose -f docker-compose.dev.yml up</span></span></code></pre><h2 id="debugging-containers">Debugging Containers</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Shell into running container</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> exec -it container_id sh</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Inspect container details</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> inspect container_id</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># View resource usage</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">docker</span><span style="color: #A6E3A1;"> stats</span></span></code></pre><h2 id="quick-reference">Quick Reference</h2> <table><thead><tr><th>Task</th><th>Command</th></tr></thead><tbody> <tr><td>Build image</td><td><code>docker build -t name .</code></td></tr> <tr><td>Run container</td><td><code>docker run -d -p 8080:80 name</code></td></tr> <tr><td>View logs</td><td><code>docker logs -f container</code></td></tr> <tr><td>Shell access</td><td><code>docker exec -it container sh</code></td></tr> <tr><td>Stop all</td><td><code>docker stop $(docker ps -q)</code></td></tr> <tr><td>Clean up</td><td><code>docker system prune -a</code></td></tr> </tbody></table> <p>Docker transforms "it works on my machine" into "it works everywhere."</p> Sun, 22 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/api-design-best-practices/ /reticle/blog/blog/api-design-best-practices/ <h1 id="rest-api-design-best-practices">REST API Design Best Practices</h1> <p>Your API is a contract. Make it one developers actually want to sign.</p> <h2 id="use-nouns-not-verbs">Use Nouns, Not Verbs</h2> <p>The HTTP method is the verb. The URL is the noun.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span># Bad</span></span> <span class="giallo-l"><span>GET /getUsers</span></span> <span class="giallo-l"><span>POST /createUser</span></span> <span class="giallo-l"><span>DELETE /deleteUser/123</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Good</span></span> <span class="giallo-l"><span>GET /users</span></span> <span class="giallo-l"><span>POST /users</span></span> <span class="giallo-l"><span>DELETE /users/123</span></span></code></pre><h2 id="use-plural-resource-names">Use Plural Resource Names</h2> <p>Consistency matters more than grammar debates:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>GET /users # List users</span></span> <span class="giallo-l"><span>GET /users/123 # Get one user</span></span> <span class="giallo-l"><span>POST /users # Create user</span></span> <span class="giallo-l"><span>PUT /users/123 # Update user</span></span> <span class="giallo-l"><span>DELETE /users/123 # Delete user</span></span></code></pre><h2 id="nest-related-resources">Nest Related Resources</h2> <p>Show relationships through URL structure:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>GET /users/123/posts # Posts by user 123</span></span> <span class="giallo-l"><span>GET /posts/456/comments # Comments on post 456</span></span></code></pre> <p>But don't nest too deeply:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span># Too deep</span></span> <span class="giallo-l"><span>GET /users/123/posts/456/comments/789/likes</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Better: use query params or separate endpoint</span></span> <span class="giallo-l"><span>GET /likes?comment=789</span></span></code></pre><h2 id="http-status-codes">HTTP Status Codes</h2> <p>Use them correctly:</p> <table><thead><tr><th>Code</th><th>Meaning</th><th>When to Use</th></tr></thead><tbody> <tr><td>200</td><td>OK</td><td>Successful GET, PUT, PATCH</td></tr> <tr><td>201</td><td>Created</td><td>Successful POST</td></tr> <tr><td>204</td><td>No Content</td><td>Successful DELETE</td></tr> <tr><td>400</td><td>Bad Request</td><td>Invalid syntax, validation errors</td></tr> <tr><td>401</td><td>Unauthorized</td><td>Missing/invalid authentication</td></tr> <tr><td>403</td><td>Forbidden</td><td>Authenticated but not allowed</td></tr> <tr><td>404</td><td>Not Found</td><td>Resource doesn't exist</td></tr> <tr><td>409</td><td>Conflict</td><td>Duplicate resource, version conflict</td></tr> <tr><td>422</td><td>Unprocessable</td><td>Valid syntax but semantic errors</td></tr> <tr><td>429</td><td>Too Many Requests</td><td>Rate limit exceeded</td></tr> <tr><td>500</td><td>Server Error</td><td>Something broke</td></tr> </tbody></table> <h2 id="consistent-error-format">Consistent Error Format</h2> <p>Always return errors in the same shape:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="json"><span class="giallo-l"><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">error</span><span style="color: #9399B2;">&quot;: {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">code</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;VALIDATION_ERROR&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">message</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;Invalid input data&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">details</span><span style="color: #9399B2;">&quot;: [</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">field</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;email&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">message</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;Must be a valid email address&quot;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">field</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;age&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">message</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;Must be at least 18&quot;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ]</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="pagination">Pagination</h2> <p>For any list endpoint, support pagination:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>GET /posts?page=2&amp;limit=20</span></span></code></pre> <p>Return pagination metadata:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="json"><span class="giallo-l"><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">data</span><span style="color: #9399B2;">&quot;: [</span><span>...</span><span style="color: #9399B2;">],</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">pagination</span><span style="color: #9399B2;">&quot;: {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">page</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">limit</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> 20</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">total</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> 156</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">pages</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> 8</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Or use cursor-based pagination for large datasets:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>GET /posts?cursor=eyJpZCI6MTAwfQ&amp;limit=20</span></span></code></pre><h2 id="filtering-and-sorting">Filtering and Sorting</h2> <p>Use query parameters:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>GET /posts?status=published&amp;author=123</span></span> <span class="giallo-l"><span>GET /posts?sort=-created_at,title</span></span> <span class="giallo-l"><span>GET /posts?created_after=2024-01-01</span></span></code></pre> <p>The <code>-</code> prefix indicates descending order.</p> <h2 id="partial-responses">Partial Responses</h2> <p>Let clients request only what they need:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>GET /users/123?fields=id,name,email</span></span></code></pre> <p>Response:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="json"><span class="giallo-l"><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> 123</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">name</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;Jane Doe&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">email</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;jane@example.com&quot;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="versioning">Versioning</h2> <p>Version your API from day one:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span># URL path (most common)</span></span> <span class="giallo-l"><span>GET /v1/users</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Header</span></span> <span class="giallo-l"><span>GET /users</span></span> <span class="giallo-l"><span>Accept: application/vnd.api+json;version=1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Query param (least preferred)</span></span> <span class="giallo-l"><span>GET /users?version=1</span></span></code></pre><h2 id="rate-limiting-headers">Rate Limiting Headers</h2> <p>Tell clients their limits:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>X-RateLimit-Limit: 1000</span></span> <span class="giallo-l"><span>X-RateLimit-Remaining: 999</span></span> <span class="giallo-l"><span>X-RateLimit-Reset: 1640995200</span></span></code></pre><h2 id="hateoas-hypermedia">HATEOAS (Hypermedia)</h2> <p>Include links for discoverability:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="json"><span class="giallo-l"><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> 123</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;API Design&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">links</span><span style="color: #9399B2;">&quot;: {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">self</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;/posts/123&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">author</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;/users/456&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">comments</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;/posts/123/comments&quot;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="idempotency">Idempotency</h2> <p>Make operations safe to retry:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span># Idempotent (safe to retry)</span></span> <span class="giallo-l"><span>GET /users/123</span></span> <span class="giallo-l"><span>PUT /users/123 # Full replacement</span></span> <span class="giallo-l"><span>DELETE /users/123</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Not idempotent</span></span> <span class="giallo-l"><span>POST /users # Creates new each time</span></span></code></pre> <p>For non-idempotent operations, accept an idempotency key:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>POST /payments</span></span> <span class="giallo-l"><span>Idempotency-Key: abc123</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Retrying with same key returns cached response</span></span></code></pre><h2 id="documentation">Documentation</h2> <p>Good APIs have good docs:</p> <ul> <li><strong>OpenAPI/Swagger</strong>: Machine-readable spec</li> <li><strong>Examples</strong>: Show request/response pairs</li> <li><strong>Authentication</strong>: Clear setup instructions</li> <li><strong>Errors</strong>: Document all error codes</li> <li><strong>Changelog</strong>: Track breaking changes</li> </ul> <h2 id="quick-checklist">Quick Checklist</h2> <ul> <li><input disabled="" type="checkbox"/> Consistent naming conventions</li> <li><input disabled="" type="checkbox"/> Proper HTTP status codes</li> <li><input disabled="" type="checkbox"/> Structured error responses</li> <li><input disabled="" type="checkbox"/> Pagination for lists</li> <li><input disabled="" type="checkbox"/> Rate limiting</li> <li><input disabled="" type="checkbox"/> API versioning</li> <li><input disabled="" type="checkbox"/> Authentication documented</li> <li><input disabled="" type="checkbox"/> OpenAPI specification</li> </ul> <p>Good API design is invisible—developers just get things working without friction.</p> Fri, 20 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/dark-mode-best-practices/ /reticle/blog/blog/dark-mode-best-practices/ <h1 id="dark-mode-best-practices-for-web-development">Dark Mode Best Practices for Web Development</h1> <p>Dark mode has become an essential feature for modern websites. Here's how to implement it properly.</p> <h2 id="respect-system-preferences">Respect System Preferences</h2> <p>The first rule of dark mode is to respect what the user has already chosen at the OS level:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #CBA6F7;">@media</span><span style="color: #9399B2;"> (</span><span>prefers-color-scheme</span><span style="color: #94E2D5;">:</span><span> dark</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> :</span><span style="color: #94E2D5;">root</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --bg</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>1e1e2e</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --text</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>cdd6f4</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="use-css-custom-properties">Use CSS Custom Properties</h2> <p>CSS custom properties make theme switching trivial:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">:</span><span style="color: #94E2D5;">root</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --bg</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>eff1f5</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --text</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>4c4f69</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;">data-theme</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;dark&quot;</span><span style="color: #9399B2;">] {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --bg</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>1e1e2e</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --text</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> #</span><span>cdd6f4</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;">body</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> background</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> var</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;">--bg</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> color</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> var</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;">--text</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="avoid-pure-black">Avoid Pure Black</h2> <p>Pure black (<code>#000000</code>) on screens can cause eye strain. Use a softer dark color like Catppuccin Mocha's base (<code>#1e1e2e</code>) instead.</p> <h2 id="consider-contrast-ratios">Consider Contrast Ratios</h2> <p>WCAG guidelines recommend:</p> <ul> <li><strong>4.5:1</strong> for normal text</li> <li><strong>3:1</strong> for large text and UI components</li> </ul> <p>Tools like the <a rel="external" href="https://webaim.org/resources/contrastchecker/">WebAIM Contrast Checker</a> can help verify your choices.</p> <h2 id="persist-user-choice">Persist User Choice</h2> <p>Store the user's preference so it persists across sessions:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> theme</span><span style="color: #94E2D5;"> =</span><span> localStorage</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">getItem</span><span>(</span><span style="color: #A6E3A1;">&#39;theme&#39;</span><span>)</span><span style="color: #94E2D5;"> ||</span><span style="color: #A6E3A1;"> &#39;auto&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span>document</span><span style="color: #94E2D5;">.</span><span>documentElement</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">setAttribute</span><span>(</span><span style="color: #A6E3A1;">&#39;data-theme&#39;</span><span style="color: #9399B2;">,</span><span> theme)</span><span style="color: #9399B2;">;</span></span></code></pre><h2 id="smooth-transitions">Smooth Transitions</h2> <p>Add a subtle transition to prevent jarring switches:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #89B4FA;">body</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> transition</span><span style="color: #94E2D5;">:</span><span> background-color </span><span style="color: #FAB387;">0.2</span><span style="color: #CBA6F7;">s</span><span> ease</span><span style="color: #9399B2;">,</span><span> color</span><span style="color: #FAB387;"> 0.2</span><span style="color: #CBA6F7;">s</span><span> ease</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="test-both-modes">Test Both Modes</h2> <p>Always test your site in both light and dark modes. Images, syntax highlighting, and embedded content can look different—or broken—in each mode.</p> <p>Dark mode done right improves accessibility, reduces eye strain, and gives users control over their experience.</p> Fri, 20 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/modern-javascript-features/ /reticle/blog/blog/modern-javascript-features/ <h1 id="modern-javascript-features-you-should-be-using">Modern JavaScript Features You Should Be Using</h1> <p>JavaScript evolves yearly. Here are features from recent versions that genuinely improve code quality.</p> <h2 id="optional-chaining">Optional Chaining (?.)</h2> <p>Stop writing defensive chains:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Before</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> city</span><span style="color: #94E2D5;"> =</span><span> user</span><span style="color: #94E2D5;"> &amp;&amp;</span><span> user</span><span style="color: #94E2D5;">.</span><span>address</span><span style="color: #94E2D5;"> &amp;&amp;</span><span> user</span><span style="color: #94E2D5;">.</span><span>address</span><span style="color: #94E2D5;">.</span><span>city</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// After</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> city</span><span style="color: #94E2D5;"> =</span><span> user</span><span style="color: #94E2D5;">?.</span><span>address</span><span style="color: #94E2D5;">?.</span><span>city</span><span style="color: #9399B2;">;</span></span></code></pre> <p>Works with methods and arrays too:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> result</span><span style="color: #94E2D5;"> =</span><span> obj</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">method</span><span style="color: #94E2D5;">?.</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> first</span><span style="color: #94E2D5;"> =</span><span> arr</span><span style="color: #94E2D5;">?.</span><span>[</span><span style="color: #FAB387;">0</span><span>]</span><span style="color: #9399B2;">;</span></span></code></pre><h2 id="nullish-coalescing">Nullish Coalescing (??)</h2> <p>Default values that respect <code>0</code> and <code>''</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Problem with ||</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> count</span><span style="color: #94E2D5;"> =</span><span> response</span><span style="color: #94E2D5;">.</span><span>count</span><span style="color: #94E2D5;"> ||</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // 0 becomes 10!</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Solution with ??</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> count</span><span style="color: #94E2D5;"> =</span><span> response</span><span style="color: #94E2D5;">.</span><span>count</span><span style="color: #94E2D5;"> ??</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // 0 stays 0</span></span></code></pre><h2 id="logical-assignment-operators">Logical Assignment Operators</h2> <p>Combine logical operators with assignment:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// ||= assigns if falsy</span></span> <span class="giallo-l"><span>options</span><span style="color: #94E2D5;">.</span><span>timeout</span><span style="color: #94E2D5;"> ||=</span><span style="color: #FAB387;"> 3000</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// ??= assigns if nullish</span></span> <span class="giallo-l"><span>user</span><span style="color: #94E2D5;">.</span><span>name</span><span style="color: #94E2D5;"> ??=</span><span style="color: #A6E3A1;"> &#39;Anonymous&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// &amp;&amp;= assigns if truthy</span></span> <span class="giallo-l"><span>config</span><span style="color: #94E2D5;">.</span><span>debug</span><span style="color: #94E2D5;"> &amp;&amp;=</span><span style="color: #89B4FA;font-style: italic;"> validateDebugMode</span><span>()</span><span style="color: #9399B2;">;</span></span></code></pre><h2 id="array-methods">Array Methods</h2> <h3 id="at-negative-indexing">at() - Negative Indexing</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> arr</span><span style="color: #94E2D5;"> =</span><span> [</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 5</span><span>]</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Before</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> last</span><span style="color: #94E2D5;"> =</span><span> arr[arr</span><span style="color: #94E2D5;">.</span><span>length</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 1</span><span>]</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// After</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> last</span><span style="color: #94E2D5;"> =</span><span> arr</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">at</span><span>(</span><span style="color: #94E2D5;">-</span><span style="color: #FAB387;">1</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> secondLast</span><span style="color: #94E2D5;"> =</span><span> arr</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">at</span><span>(</span><span style="color: #94E2D5;">-</span><span style="color: #FAB387;">2</span><span>)</span><span style="color: #9399B2;">;</span></span></code></pre><h3 id="findlast-and-findlastindex">findLast() and findLastIndex()</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> transactions</span><span style="color: #94E2D5;"> =</span><span> [</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span><span> type</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;credit&#39;</span><span style="color: #9399B2;">,</span><span> amount</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 100</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span><span> type</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;debit&#39;</span><span style="color: #9399B2;">,</span><span> amount</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 50</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span><span> type</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;credit&#39;</span><span style="color: #9399B2;">,</span><span> amount</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 200</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span>]</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> lastCredit</span><span style="color: #94E2D5;"> =</span><span> transactions</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">findLast</span><span>(</span><span style="color: #EBA0AC;font-style: italic;">t</span><span style="color: #CBA6F7;"> =&gt;</span><span> t</span><span style="color: #94E2D5;">.</span><span>type</span><span style="color: #94E2D5;"> ===</span><span style="color: #A6E3A1;"> &#39;credit&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// { type: &#39;credit&#39;, amount: 200 }</span></span></code></pre><h3 id="tosorted-toreversed-tospliced">toSorted(), toReversed(), toSpliced()</h3> <p>Non-mutating array operations:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> original</span><span style="color: #94E2D5;"> =</span><span> [</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span>]</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> sorted</span><span style="color: #94E2D5;"> =</span><span> original</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toSorted</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// sorted: [1, 2, 3]</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// original: [3, 1, 2] - unchanged!</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> reversed</span><span style="color: #94E2D5;"> =</span><span> original</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toReversed</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> removed</span><span style="color: #94E2D5;"> =</span><span> original</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">toSpliced</span><span>(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 1</span><span>)</span><span style="color: #9399B2;">;</span></span></code></pre><h2 id="object-groupby">Object.groupBy()</h2> <p>Native grouping without lodash:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> inventory</span><span style="color: #94E2D5;"> =</span><span> [</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;apples&#39;</span><span style="color: #9399B2;">,</span><span> type</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;fruit&#39;</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;bananas&#39;</span><span style="color: #9399B2;">,</span><span> type</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;fruit&#39;</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;carrots&#39;</span><span style="color: #9399B2;">,</span><span> type</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;vegetable&#39;</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span>]</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> grouped</span><span style="color: #94E2D5;"> =</span><span> Object</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">groupBy</span><span>(inventory</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;font-style: italic;"> item</span><span style="color: #CBA6F7;"> =&gt;</span><span> item</span><span style="color: #94E2D5;">.</span><span>type)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// fruit: [{ name: &#39;apples&#39;, ... }, { name: &#39;bananas&#39;, ... }],</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// vegetable: [{ name: &#39;carrots&#39;, ... }]</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// }</span></span></code></pre><h2 id="promise-allsettled">Promise.allSettled()</h2> <p>Wait for all promises regardless of rejection:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> results</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> await</span><span style="color: #F9E2AF;font-style: italic;"> Promise</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">allSettled</span><span>([</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> fetch</span><span>(</span><span style="color: #A6E3A1;">&#39;/api/users&#39;</span><span>)</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> fetch</span><span>(</span><span style="color: #A6E3A1;">&#39;/api/posts&#39;</span><span>)</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> fetch</span><span>(</span><span style="color: #A6E3A1;">&#39;/api/comments&#39;</span><span>)</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span>])</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>results</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">forEach</span><span>(</span><span style="color: #EBA0AC;font-style: italic;">result</span><span style="color: #CBA6F7;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> (result</span><span style="color: #94E2D5;">.</span><span>status</span><span style="color: #94E2D5;"> ===</span><span style="color: #A6E3A1;"> &#39;fulfilled&#39;</span><span>)</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> console</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">log</span><span>(result</span><span style="color: #94E2D5;">.</span><span>value)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> console</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">error</span><span>(result</span><span style="color: #94E2D5;">.</span><span>reason)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span>)</span><span style="color: #9399B2;">;</span></span></code></pre><h2 id="private-class-fields">Private Class Fields</h2> <p>True privacy with <code>#</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #CBA6F7;">class</span><span style="color: #F9E2AF;font-style: italic;"> Counter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> #count</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> increment</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> this</span><span style="color: #94E2D5;">.</span><span>#count</span><span style="color: #94E2D5;">++</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> get</span><span style="color: #89B4FA;font-style: italic;"> value</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F38BA8;"> this</span><span style="color: #94E2D5;">.</span><span>#count</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> counter</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;font-weight: bold;"> new</span><span style="color: #89B4FA;font-style: italic;"> Counter</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span>counter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">increment</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span>console</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">log</span><span>(counter</span><span style="color: #94E2D5;">.</span><span>value)</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // 1</span></span> <span class="giallo-l"><span>console</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">log</span><span>(counter</span><span style="color: #94E2D5;">.</span><span>#count)</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // SyntaxError!</span></span></code></pre><h2 id="static-blocks">Static Blocks</h2> <p>Complex static initialization:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #CBA6F7;">class</span><span style="color: #F9E2AF;font-style: italic;"> Config</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> static</span><span> values</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> static</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> try</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> this</span><span style="color: #94E2D5;">.</span><span>values</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> JSON</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse</span><span>(localStorage</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">getItem</span><span>(</span><span style="color: #A6E3A1;">&#39;config&#39;</span><span>))</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> catch</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> this</span><span style="color: #94E2D5;">.</span><span>values</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> theme</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;dark&#39;</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="top-level-await">Top-Level Await</h2> <p>Use <code>await</code> outside async functions in modules:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// config.js</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> response</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> await</span><span style="color: #89B4FA;font-style: italic;"> fetch</span><span>(</span><span style="color: #A6E3A1;">&#39;/api/config&#39;</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">export const</span><span> config</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> await</span><span> response</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">json</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// main.js</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">import</span><span style="color: #9399B2;"> {</span><span> config</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;./config.js&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// config is already resolved</span></span></code></pre><h2 id="temporal-api-coming-soon">Temporal API (Coming Soon)</h2> <p>Finally, a sane date/time API:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Current (painful)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> date</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;font-weight: bold;"> new</span><span style="color: #89B4FA;font-style: italic;"> Date</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span>date</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">setDate</span><span>(date</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">getDate</span><span>()</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 7</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Temporal (clear)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> date</span><span style="color: #94E2D5;"> =</span><span> Temporal</span><span style="color: #94E2D5;">.</span><span>Now</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">plainDateISO</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span> nextWeek</span><span style="color: #94E2D5;"> =</span><span> date</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add</span><span>(</span><span style="color: #9399B2;">{</span><span> days</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 7</span><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span></code></pre><h2 id="error-cause">Error Cause</h2> <p>Chain errors with context:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="javascript"><span class="giallo-l"><span style="color: #CBA6F7;">try</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span style="color: #89B4FA;font-style: italic;"> fetchUserData</span><span>(userId)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span style="color: #CBA6F7;"> catch</span><span> (error)</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> throw</span><span style="color: #CBA6F7;font-weight: bold;"> new</span><span style="color: #89B4FA;font-style: italic;"> Error</span><span>(</span><span style="color: #A6E3A1;">&#39;Failed to load user profile&#39;</span><span style="color: #9399B2;">, {</span></span> <span class="giallo-l"><span> cause</span><span style="color: #94E2D5;">:</span><span> error</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span>)</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="quick-adoption-guide">Quick Adoption Guide</h2> <table><thead><tr><th>Feature</th><th>Use When</th></tr></thead><tbody> <tr><td><code>?.</code></td><td>Accessing nested properties</td></tr> <tr><td><code>??</code></td><td>Providing defaults (especially for 0/'')</td></tr> <tr><td><code>at(-1)</code></td><td>Accessing from array end</td></tr> <tr><td><code>toSorted()</code></td><td>Sorting without mutation</td></tr> <tr><td><code>Object.groupBy()</code></td><td>Categorizing arrays</td></tr> <tr><td><code>#private</code></td><td>Encapsulating class data</td></tr> </tbody></table> <p>Check <a rel="external" href="https://caniuse.com">caniuse.com</a> for browser support before using in production.</p> Wed, 18 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/introduction-to-webassembly/ /reticle/blog/blog/introduction-to-webassembly/ <h1 id="introduction-to-webassembly">Introduction to WebAssembly</h1> <p>WebAssembly (Wasm) is a binary instruction format that runs in browsers at near-native speed. It's not here to replace JavaScript—it's here to complement it.</p> <h2 id="why-webassembly">Why WebAssembly?</h2> <p>JavaScript is incredibly versatile, but some tasks need more performance:</p> <ul> <li><strong>Image/video processing</strong></li> <li><strong>Games and 3D graphics</strong></li> <li><strong>Compression/encryption</strong></li> <li><strong>Scientific computing</strong></li> <li><strong>CAD applications</strong></li> </ul> <p>WebAssembly handles these without plugins or browser extensions.</p> <h2 id="how-it-works">How It Works</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Source Code → Compiler → .wasm binary → Browser Runtime</span></span> <span class="giallo-l"><span>(Rust, C++) (portable) (sandboxed)</span></span></code></pre> <p>The browser downloads the <code>.wasm</code> file and executes it in a secure sandbox alongside JavaScript.</p> <h2 id="your-first-webassembly-with-rust">Your First WebAssembly (with Rust)</h2> <h3 id="1-set-up">1. Set Up</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Install the Wasm target</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">rustup</span><span style="color: #A6E3A1;"> target add wasm32-unknown-unknown</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Install wasm-pack</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> install wasm-pack</span></span></code></pre><h3 id="2-create-a-project">2. Create a Project</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new --lib hello-wasm</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> hello-wasm</span></span></code></pre><h3 id="3-configure-cargo-toml">3. Configure Cargo.toml</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>package</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>name</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;hello-wasm&quot;</span></span> <span class="giallo-l"><span>version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.1.0&quot;</span></span> <span class="giallo-l"><span>edition</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2021&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>lib</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>crate-type</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> [</span><span style="color: #A6E3A1;">&quot;cdylib&quot;</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>dependencies</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>wasm-bindgen</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.2&quot;</span></span></code></pre><h3 id="4-write-rust-code">4. Write Rust Code</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> wasm_bindgen</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">prelude</span><span style="color: #94E2D5;">::*</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">wasm_bindgen</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">pub fn</span><span style="color: #89B4FA;font-style: italic;"> greet</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">name</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Hello, </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">!&quot;</span><span style="color: #9399B2;">,</span><span> name</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">wasm_bindgen</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">pub fn</span><span style="color: #89B4FA;font-style: italic;"> fibonacci</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">n</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> n</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> fibonacci</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> +</span><span style="color: #89B4FA;font-style: italic;"> fibonacci</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="5-build">5. Build</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">wasm-pack</span><span style="color: #A6E3A1;"> build --target web</span></span></code></pre><h3 id="6-use-in-javascript">6. Use in JavaScript</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="html"><span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">script</span><span style="color: #F9E2AF;"> type</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;module&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> import</span><span> init</span><span style="color: #9399B2;">, {</span><span> greet</span><span style="color: #9399B2;">,</span><span> fibonacci</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &#39;./pkg/hello_wasm.js&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> async function</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> await</span><span style="color: #89B4FA;font-style: italic;"> init</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> console</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">log</span><span>(</span><span style="color: #89B4FA;font-style: italic;">greet</span><span>(</span><span style="color: #A6E3A1;">&quot;World&quot;</span><span>))</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> console</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">log</span><span>(</span><span style="color: #89B4FA;font-style: italic;">fibonacci</span><span>(</span><span style="color: #FAB387;">40</span><span>))</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // Much faster than JS</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> main</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span>&lt;</span><span style="color: #94E2D5;">/</span><span style="color: #89B4FA;">script</span><span style="color: #94E2D5;">&gt;</span></span></code></pre><h2 id="performance-comparison">Performance Comparison</h2> <p>Computing Fibonacci(45):</p> <table><thead><tr><th>Language</th><th>Time</th></tr></thead><tbody> <tr><td>JavaScript</td><td>~8 seconds</td></tr> <tr><td>WebAssembly (Rust)</td><td>~4 seconds</td></tr> <tr><td>Native Rust</td><td>~3 seconds</td></tr> </tbody></table> <p>For compute-heavy tasks, Wasm can be 2-10x faster than JavaScript.</p> <h2 id="real-world-use-cases">Real-World Use Cases</h2> <h3 id="figma">Figma</h3> <p>The design tool uses WebAssembly for its rendering engine, enabling smooth performance with complex designs.</p> <h3 id="photoshop-web">Photoshop Web</h3> <p>Adobe ported significant portions of Photoshop to Wasm for the web version.</p> <h3 id="google-earth">Google Earth</h3> <p>Complex 3D rendering runs smoothly thanks to WebAssembly.</p> <h3 id="sqlite-in-the-browser">SQLite in the Browser</h3> <p>The entire SQLite database engine compiled to Wasm.</p> <h2 id="interacting-with-the-dom">Interacting with the DOM</h2> <p>WebAssembly can't directly access the DOM—it must go through JavaScript:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> wasm_bindgen</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">prelude</span><span style="color: #94E2D5;">::*</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> web_sys</span><span style="color: #94E2D5;">::</span><span>console</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">wasm_bindgen</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">start</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">pub fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> console</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">log_1</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #A6E3A1;">&quot;Hello from Wasm!&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Add to Cargo.toml</span></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>dependencies.web-sys</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.3&quot;</span></span> <span class="giallo-l"><span>features</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> [</span><span style="color: #A6E3A1;">&quot;console&quot;</span><span style="color: #9399B2;">]</span></span></code></pre><h2 id="memory-management">Memory Management</h2> <p>Wasm has its own linear memory that JavaScript can read:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">wasm_bindgen</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">pub fn</span><span style="color: #89B4FA;font-style: italic;"> process_image</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">data</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">[</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">])</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u8</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Process and return new data</span></span> <span class="giallo-l"><span> data</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|&amp;</span><span>x</span><span style="color: #94E2D5;">|</span><span style="color: #FAB387;"> 255</span><span style="color: #94E2D5;"> -</span><span> x</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="when-not-to-use-webassembly">When NOT to Use WebAssembly</h2> <ul> <li><strong>Simple DOM manipulation</strong>: JavaScript is faster to develop</li> <li><strong>Small utilities</strong>: The Wasm overhead isn't worth it</li> <li><strong>I/O-bound tasks</strong>: Network/file operations are limited by the browser</li> <li><strong>When bundle size matters</strong>: Wasm adds payload</li> </ul> <h2 id="the-future">The Future</h2> <ul> <li><strong>WASI</strong>: WebAssembly System Interface for running outside browsers</li> <li><strong>Component Model</strong>: Better interoperability between Wasm modules</li> <li><strong>Garbage Collection</strong>: Native GC support coming soon</li> <li><strong>Threads</strong>: Shared memory and threading support</li> </ul> <p>WebAssembly isn't just for browsers anymore—it's becoming a universal runtime.</p> Wed, 18 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/why-static-sites/ /reticle/blog/blog/why-static-sites/ <h1 id="why-static-sites-are-making-a-comeback">Why Static Sites Are Making a Comeback</h1> <p>In an era of complex web applications, static sites are experiencing a renaissance. Here's why.</p> <h2 id="performance">Performance</h2> <p>Static sites are <em>fast</em>. There's no database to query, no server-side rendering to wait for. Your HTML, CSS, and JavaScript are served directly from a CDN, often in under 100ms.</p> <p>Compare this to a typical WordPress site that might take 2-3 seconds to generate a page.</p> <h2 id="security">Security</h2> <p>With no database and no server-side code, the attack surface shrinks dramatically:</p> <ul> <li>No SQL injection</li> <li>No server-side vulnerabilities</li> <li>No CMS to keep patched</li> </ul> <p>Your site is essentially a folder of files. There's nothing to hack.</p> <h2 id="cost">Cost</h2> <p>Static hosting is cheap—often free:</p> <ul> <li><strong>GitHub Pages</strong>: Free</li> <li><strong>Cloudflare Pages</strong>: Free</li> <li><strong>Netlify</strong>: Free tier available</li> <li><strong>Vercel</strong>: Free tier available</li> </ul> <p>No server to maintain. No database to pay for. No DevOps headaches.</p> <h2 id="developer-experience">Developer Experience</h2> <p>Modern static site generators like Zola, Hugo, and Eleventy offer:</p> <ul> <li><strong>Hot reload</strong> during development</li> <li><strong>Markdown</strong> for content</li> <li><strong>Git-based workflows</strong> for versioning</li> <li><strong>Build previews</strong> for pull requests</li> </ul> <h2 id="when-static-doesn-t-work">When Static Doesn't Work</h2> <p>Static sites aren't for everything. You'll still need a server for:</p> <ul> <li>User authentication</li> <li>Real-time features</li> <li>Dynamic content that changes per-user</li> </ul> <p>But for blogs, documentation, marketing sites, and portfolios? Static is hard to beat.</p> <h2 id="the-jamstack-approach">The JAMstack Approach</h2> <p>The JAMstack (JavaScript, APIs, Markup) architecture extends static sites with:</p> <ul> <li>Client-side JavaScript for interactivity</li> <li>Third-party APIs for dynamic features</li> <li>Pre-rendered markup for speed</li> </ul> <p>This gives you the best of both worlds: static performance with dynamic capabilities.</p> <h2 id="getting-started">Getting Started</h2> <p>Ready to try static? Zola is a great starting point:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Install Zola</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">brew</span><span style="color: #A6E3A1;"> install zola</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Create a new site</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">zola</span><span style="color: #A6E3A1;"> init my-site</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> my-site</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Start the dev server</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">zola</span><span style="color: #A6E3A1;"> serve</span></span></code></pre> <p>The future is static—and it's faster than ever.</p> Sun, 15 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/css-grid-vs-flexbox/ /reticle/blog/blog/css-grid-vs-flexbox/ <h1 id="css-grid-vs-flexbox-when-to-use-each">CSS Grid vs Flexbox: When to Use Each</h1> <p>The age-old question: Grid or Flexbox? The answer is usually "both"—but knowing when to reach for each makes all the difference.</p> <h2 id="the-mental-model">The Mental Model</h2> <p><strong>Flexbox</strong> is one-dimensional. It handles either a row <em>or</em> a column.</p> <p><strong>Grid</strong> is two-dimensional. It handles rows <em>and</em> columns simultaneously.</p> <h2 id="use-flexbox-when">Use Flexbox When...</h2> <h3 id="aligning-items-in-a-single-direction">Aligning Items in a Single Direction</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">navbar</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> flex</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> justify-content</span><span style="color: #94E2D5;">:</span><span> space-between</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> align-items</span><span style="color: #94E2D5;">:</span><span> center</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="content-size-should-determine-layout">Content Size Should Determine Layout</h3> <p>Flexbox lets items grow and shrink based on their content:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">tags</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> flex</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> flex-wrap</span><span style="color: #94E2D5;">:</span><span> wrap</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> gap</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0.5</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">tag</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> /* Each tag sizes to its content */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> padding</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0.25</span><span style="color: #CBA6F7;">rem</span><span style="color: #FAB387;"> 0.5</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="centering-things">Centering Things</h3> <p>The classic centering trick:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">centered</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> flex</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> justify-content</span><span style="color: #94E2D5;">:</span><span> center</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> align-items</span><span style="color: #94E2D5;">:</span><span> center</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="use-grid-when">Use Grid When...</h2> <h3 id="creating-page-layouts">Creating Page Layouts</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">page</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> grid</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> grid-template-columns</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 250</span><span style="color: #CBA6F7;">px</span><span style="color: #FAB387;"> 1</span><span style="color: #CBA6F7;">fr</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> grid-template-rows</span><span style="color: #94E2D5;">:</span><span> auto</span><span style="color: #FAB387;"> 1</span><span style="color: #CBA6F7;">fr</span><span> auto</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> grid-template-areas</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;sidebar header&quot;</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;sidebar main&quot;</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;sidebar footer&quot;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="equal-width-columns">Equal-Width Columns</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">card-grid</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> grid</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> grid-template-columns</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> repeat</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 1</span><span style="color: #CBA6F7;">fr</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> gap</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1.5</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="overlapping-elements">Overlapping Elements</h3> <p>Grid allows items to occupy the same cells:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">hero</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> grid</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">hero</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #89B4FA;"> *</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> grid-area</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1</span><span> / </span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">hero-image</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> z-index</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">hero-text</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> z-index</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="use-both-together">Use Both Together</h2> <p>The real power comes from combining them:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">/* Grid for the overall layout */</span></span> <span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">dashboard</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> grid</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> grid-template-columns</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> repeat</span><span style="color: #9399B2;">(</span><span>auto-fit</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> minmax</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">300</span><span style="color: #CBA6F7;">px</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 1</span><span style="color: #CBA6F7;">fr</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> gap</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">/* Flexbox for card internals */</span></span> <span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">card</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> flex</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> flex-direction</span><span style="color: #94E2D5;">:</span><span> column</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">card-footer</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> margin-top</span><span style="color: #94E2D5;">:</span><span> auto</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* Push to bottom */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> flex</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> justify-content</span><span style="color: #94E2D5;">:</span><span> space-between</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="quick-reference">Quick Reference</h2> <table><thead><tr><th>Scenario</th><th>Use</th></tr></thead><tbody> <tr><td>Navigation bars</td><td>Flexbox</td></tr> <tr><td>Page layout</td><td>Grid</td></tr> <tr><td>Card grids</td><td>Grid</td></tr> <tr><td>Card contents</td><td>Flexbox</td></tr> <tr><td>Centering</td><td>Either</td></tr> <tr><td>Form layouts</td><td>Grid</td></tr> <tr><td>Button groups</td><td>Flexbox</td></tr> <tr><td>Image galleries</td><td>Grid</td></tr> </tbody></table> <h2 id="the-subgrid-game-changer">The Subgrid Game-Changer</h2> <p>CSS Subgrid (now widely supported) lets nested grids align with their parent:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">card-grid</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> grid</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> grid-template-columns</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> repeat</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 1</span><span style="color: #CBA6F7;">fr</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">card</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> grid</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> grid-template-rows</span><span style="color: #94E2D5;">:</span><span> subgrid</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> grid-row</span><span style="color: #94E2D5;">:</span><span> span </span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This ensures all card headers, bodies, and footers align across the row.</p> <p>Stop asking "Grid or Flexbox?" Start asking "What problem am I solving?"</p> Sun, 15 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/typography-for-developers/ /reticle/blog/blog/typography-for-developers/ <h1 id="typography-fundamentals-for-developers">Typography Fundamentals for Developers</h1> <p>You don't need to be a designer to get typography right. These fundamentals will take you far.</p> <h2 id="choose-readable-fonts">Choose Readable Fonts</h2> <p>For body text, prioritize readability:</p> <ul> <li><strong>Sans-serif</strong> for screens: Geist, Inter, system-ui</li> <li><strong>Serif</strong> for long-form: Georgia, Charter, Literata</li> <li><strong>Monospace</strong> for code: Geist Mono, JetBrains Mono, Fira Code</li> </ul> <p>Avoid decorative fonts for body text. Save them for headlines.</p> <h2 id="set-a-comfortable-line-length">Set a Comfortable Line Length</h2> <p>Lines that are too long or too short hurt readability. Aim for <strong>45-75 characters</strong> per line:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">prose</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> max-width</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 65</span><span style="color: #CBA6F7;">ch</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>ch</code> unit is based on the width of the "0" character, making it perfect for this.</p> <h2 id="use-a-type-scale">Use a Type Scale</h2> <p>Don't pick font sizes randomly. Use a scale:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">:</span><span style="color: #94E2D5;">root</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --text-xs</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0.75</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* 12px */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --text-sm</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0.875</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* 14px */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --text-base</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* 16px */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --text-lg</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1.125</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* 18px */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --text-xl</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1.25</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* 20px */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --text-2xl</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1.5</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* 24px */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --text-3xl</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1.875</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* 30px */</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> --text-4xl</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 2.25</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> /* 36px */</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="line-height-matters">Line Height Matters</h2> <p>Tighter line height for headlines, looser for body text:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #89B4FA;">h1</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;"> h2</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;"> h3</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> line-height</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1.2</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;">p</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> line-height</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1.6</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="vertical-rhythm">Vertical Rhythm</h2> <p>Consistent spacing creates visual harmony:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">prose</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #89B4FA;"> *</span><span style="color: #94E2D5;"> +</span><span style="color: #89B4FA;"> *</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> margin-top</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1.5</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">prose</span><span style="color: #89B4FA;"> h2</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> margin-top</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 3</span><span style="color: #CBA6F7;">rem</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="font-loading">Font Loading</h2> <p>Use <code>font-display: swap</code> to prevent invisible text:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #CBA6F7;">@font-face</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> font-family</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &#39;Geist&#39;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> src</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> url</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&#39;/fonts/Geist-Variable.woff2&#39;</span><span style="color: #9399B2;">)</span><span style="color: #89B4FA;font-style: italic;"> format</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&#39;woff2&#39;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> font-display</span><span style="color: #94E2D5;">:</span><span> swap</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="responsive-typography">Responsive Typography</h2> <p>Scale fonts based on viewport:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #89B4FA;">html</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> font-size</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> clamp</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">16</span><span style="color: #CBA6F7;">px</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 1</span><span style="color: #CBA6F7;">vw</span><span style="color: #EBA0AC;font-style: italic;"> +</span><span style="color: #FAB387;"> 14</span><span style="color: #CBA6F7;">px</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 20</span><span style="color: #CBA6F7;">px</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This creates fluid typography that adapts to screen size.</p> <p>Good typography is invisible—readers don't notice it, they just enjoy the content.</p> Thu, 12 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/building-accessible-websites/ /reticle/blog/blog/building-accessible-websites/ <h1 id="building-accessible-websites-a-practical-guide">Building Accessible Websites: A Practical Guide</h1> <p>Web accessibility ensures your site works for everyone, including people with disabilities. Here's how to do it right.</p> <h2 id="semantic-html">Semantic HTML</h2> <p>Use the right elements for the job:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="html"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">&lt;!-- Bad --&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">div</span><span style="color: #F9E2AF;"> class</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;button&quot;</span><span style="color: #F9E2AF;"> onclick</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #89B4FA;font-style: italic;">submit</span><span>()&quot;</span><span style="color: #94E2D5;">&gt;</span><span>Submit</span><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">div</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">&lt;!-- Good --&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">button</span><span style="color: #F9E2AF;"> type</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;submit&quot;</span><span style="color: #94E2D5;">&gt;</span><span>Submit</span><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">button</span><span style="color: #94E2D5;">&gt;</span></span></code></pre> <p>Semantic elements provide built-in accessibility features that <code>div</code>s don't have.</p> <h2 id="keyboard-navigation">Keyboard Navigation</h2> <p>Everything clickable should be keyboard accessible:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">/* Make focus visible */</span></span> <span class="giallo-l"><span style="color: #9399B2;">:</span><span style="color: #94E2D5;">focus</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> outline</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 2</span><span style="color: #CBA6F7;">px</span><span> solid</span><span style="color: #89B4FA;font-style: italic;"> var</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;">--accent</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> outline-offset</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 2</span><span style="color: #CBA6F7;">px</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">/* Don&#39;t hide focus outlines */</span></span> <span class="giallo-l"><span style="color: #9399B2;">:</span><span style="color: #94E2D5;">focus</span><span style="color: #9399B2;">:</span><span style="color: #94E2D5;">not</span><span style="color: #9399B2;">(:</span><span style="color: #94E2D5;">focus-visible</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> outline</span><span style="color: #94E2D5;">:</span><span> none</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #9399B2;">:</span><span style="color: #94E2D5;">focus-visible</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> outline</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 2</span><span style="color: #CBA6F7;">px</span><span> solid</span><span style="color: #89B4FA;font-style: italic;"> var</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;">--accent</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Test your site using only the keyboard: Tab, Shift+Tab, Enter, and Escape should work everywhere.</p> <h2 id="alt-text-for-images">Alt Text for Images</h2> <p>Every image needs alt text:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="html"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">&lt;!-- Informative image --&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">img</span><span style="color: #F9E2AF;"> src</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;chart.png&quot;</span><span style="color: #F9E2AF;"> alt</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;Sales increased 50% in Q4 2024&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">&lt;!-- Decorative image --&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">img</span><span style="color: #F9E2AF;"> src</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;divider.png&quot;</span><span style="color: #F9E2AF;"> alt</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;&quot;</span><span style="color: #F9E2AF;"> role</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;presentation&quot;</span><span style="color: #94E2D5;">&gt;</span></span></code></pre> <p>If an image is decorative, use an empty alt attribute.</p> <h2 id="color-contrast">Color Contrast</h2> <p>Ensure sufficient contrast between text and background:</p> <ul> <li><strong>4.5:1</strong> minimum for normal text</li> <li><strong>3:1</strong> minimum for large text (18px+ or 14px+ bold)</li> </ul> <p>Don't rely on color alone to convey information:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="html"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">&lt;!-- Bad: color only --&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">span</span><span style="color: #F9E2AF;"> class</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;error&quot;</span><span style="color: #94E2D5;">&gt;</span><span>Invalid email</span><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">span</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">&lt;!-- Good: color + icon + text --&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">span</span><span style="color: #F9E2AF;"> class</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;error&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &lt;</span><span style="color: #89B4FA;">svg</span><span style="color: #F9E2AF;"> aria-hidden</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;true&quot;</span><span style="color: #94E2D5;">&gt;</span><span style="color: #9399B2;font-style: italic;">&lt;!-- error icon --&gt;</span><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">svg</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span> Invalid email address</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">span</span><span style="color: #94E2D5;">&gt;</span></span></code></pre><h2 id="aria-labels">ARIA Labels</h2> <p>Use ARIA when HTML semantics aren't enough:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="html"><span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">button</span><span style="color: #F9E2AF;"> aria-label</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;Close dialog&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &lt;</span><span style="color: #89B4FA;">svg</span><span style="color: #94E2D5;">&gt;</span><span style="color: #9399B2;font-style: italic;">&lt;!-- X icon --&gt;</span><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">svg</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">button</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">nav</span><span style="color: #F9E2AF;"> aria-label</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;Main navigation&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> &lt;!-- links --&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">nav</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">div</span><span style="color: #F9E2AF;"> role</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;alert&quot;</span><span style="color: #F9E2AF;"> aria-live</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;polite&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span> Your changes have been saved.</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">div</span><span style="color: #94E2D5;">&gt;</span></span></code></pre> <p>But remember: <strong>no ARIA is better than bad ARIA</strong>.</p> <h2 id="skip-links">Skip Links</h2> <p>Let keyboard users skip repetitive navigation:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="html"><span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">a</span><span style="color: #F9E2AF;"> href</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;#main-content&quot;</span><span style="color: #F9E2AF;"> class</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;skip-link&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span> Skip to main content</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">a</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">&lt;!-- ... navigation ... --&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">main</span><span style="color: #F9E2AF;"> id</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;main-content&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> &lt;!-- content --&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">main</span><span style="color: #94E2D5;">&gt;</span></span></code></pre><pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="css"><span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">skip-link</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> position</span><span style="color: #94E2D5;">:</span><span> absolute</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> top</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> -100%</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #9399B2;">.</span><span style="color: #F9E2AF;">skip-link</span><span style="color: #9399B2;">:</span><span style="color: #94E2D5;">focus</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> top</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="testing-accessibility">Testing Accessibility</h2> <p>Use these tools:</p> <ul> <li><strong>axe DevTools</strong>: Browser extension for automated testing</li> <li><strong>WAVE</strong>: Web accessibility evaluation tool</li> <li><strong>Screen readers</strong>: VoiceOver (Mac), NVDA (Windows)</li> </ul> <p>Run <code>lighthouse</code> in Chrome DevTools for an accessibility audit.</p> <h2 id="quick-wins">Quick Wins</h2> <ol> <li>Add <code>lang</code> attribute to <code>&lt;html&gt;</code></li> <li>Use descriptive link text (not "click here")</li> <li>Ensure form inputs have labels</li> <li>Add captions to videos</li> <li>Test at 200% zoom</li> </ol> <p>Accessibility benefits everyone—not just users with disabilities.</p> Sun, 08 Dec 2024 00:00:00 +0000 Unknown /reticle/blog/blog/git-workflow-for-content/ /reticle/blog/blog/git-workflow-for-content/ <h1 id="git-workflow-for-content-teams">Git Workflow for Content Teams</h1> <p>Static sites store content as files in a Git repository. This unlocks powerful workflows for content teams.</p> <h2 id="why-git-for-content">Why Git for Content?</h2> <p>Traditional CMS platforms have their own versioning, but Git offers:</p> <ul> <li><strong>Complete history</strong>: Every change is tracked forever</li> <li><strong>Branching</strong>: Work on drafts without affecting the live site</li> <li><strong>Review process</strong>: Pull requests for editorial review</li> <li><strong>Rollback</strong>: Instantly revert any change</li> <li><strong>Collaboration</strong>: Multiple people can work simultaneously</li> </ul> <h2 id="the-basic-workflow">The Basic Workflow</h2> <h3 id="1-create-a-branch">1. Create a Branch</h3> <p>Never work directly on <code>main</code>. Create a branch for your changes:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">git</span><span style="color: #A6E3A1;"> checkout -b post/new-article-title</span></span></code></pre><h3 id="2-make-your-changes">2. Make Your Changes</h3> <p>Edit or create Markdown files in the <code>content/</code> directory:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="markdown"><span class="giallo-l"><span>+++</span></span> <span class="giallo-l"><span>title = &quot;My New Article&quot;</span></span> <span class="giallo-l"><span>date = 2024-12-08</span></span> <span class="giallo-l"><span>+++</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Article content goes here...</span></span></code></pre><h3 id="3-commit-your-work">3. Commit Your Work</h3> <p>Save your changes with a descriptive message:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">git</span><span style="color: #A6E3A1;"> add content/my-new-article.md</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">git</span><span style="color: #A6E3A1;"> commit -m &quot;Add article about Git workflows&quot;</span></span></code></pre><h3 id="4-push-and-create-a-pull-request">4. Push and Create a Pull Request</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">git</span><span style="color: #A6E3A1;"> push origin post/new-article-title</span></span></code></pre> <p>Then create a pull request on GitHub for review.</p> <h3 id="5-review-and-merge">5. Review and Merge</h3> <p>Team members can:</p> <ul> <li>Comment on specific lines</li> <li>Suggest edits</li> <li>Preview the changes (with deploy previews)</li> <li>Approve and merge</li> </ul> <h2 id="deploy-previews">Deploy Previews</h2> <p>Services like Netlify and Vercel create preview URLs for every pull request. This lets editors see exactly how their changes will look before merging.</p> <h2 id="branch-naming-conventions">Branch Naming Conventions</h2> <p>Use consistent prefixes:</p> <ul> <li><code>post/</code> - New blog posts</li> <li><code>docs/</code> - Documentation updates</li> <li><code>fix/</code> - Corrections and typos</li> <li><code>feature/</code> - New site features</li> </ul> <h2 id="handling-conflicts">Handling Conflicts</h2> <p>If two people edit the same file:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">git</span><span style="color: #A6E3A1;"> pull origin main</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Resolve conflicts in your editor</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">git</span><span style="color: #A6E3A1;"> add .</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">git</span><span style="color: #A6E3A1;"> commit -m &quot;Resolve merge conflict&quot;</span></span></code></pre><h2 id="tips-for-non-developers">Tips for Non-Developers</h2> <ol> <li><strong>Use GitHub's web editor</strong> for simple changes</li> <li><strong>Use a desktop app</strong> like GitHub Desktop or VS Code</li> <li><strong>Write good commit messages</strong> describing what and why</li> <li><strong>Don't fear branches</strong> - they're cheap and easy to delete</li> <li><strong>Ask for help</strong> - Git has a learning curve</li> </ol> <h2 id="automating-quality-checks">Automating Quality Checks</h2> <p>Add CI checks to catch issues before merge:</p> <ul> <li>Spell checking</li> <li>Link validation</li> <li>Build verification</li> <li>Image optimization</li> </ul> <p>Git transforms content management from a black box into a transparent, collaborative process.</p>