/tanuki/blog Software developer writing about web technologies, design, and the craft of building things. Zola en Fri, 27 Dec 2024 00:00:00 +0000 Fri, 27 Dec 2024 00:00:00 +0000 Unknown /tanuki/blog/blog/welcome-to-tanuki/ /tanuki/blog/blog/welcome-to-tanuki/ <h1 id="welcome-to-tanuki">Welcome to Tanuki</h1> <p>We're excited to introduce Tanuki, a new Zola theme that brings joy and whimsy to your documentation, books, and blogs.</p> <h2 id="why-tanuki">Why Tanuki?</h2> <p>The tanuki (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>Tanuki 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 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 Tanuki to your project is simple:</p> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">git</span><span> submodule add https://github.com/raskell-io/tanuki themes/tanuki </span></code></pre> <p>Then add to your <code>config.toml</code>:</p> <pre data-lang="toml" style="background-color:#2b303b;color:#c0c5ce;" class="language-toml "><code class="language-toml" data-lang="toml"><span style="color:#bf616a;">theme </span><span>= &quot;</span><span style="color:#a3be8c;">tanuki</span><span>&quot; </span><span> </span><span>[extra] </span><span style="color:#bf616a;">mode </span><span>= &quot;</span><span style="color:#a3be8c;">site</span><span>&quot; </span><span style="color:#65737e;"># or &quot;docs&quot; or &quot;book&quot; </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 /tanuki/blog/blog/getting-started-with-zola/ /tanuki/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 Tanuki 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 data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">brew</span><span> install zola </span></code></pre> <h3 id="linux">Linux</h3> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#65737e;"># Snap </span><span style="color:#bf616a;">snap</span><span> install zola</span><span style="color:#bf616a;"> --edge </span><span> </span><span style="color:#65737e;"># Or download from GitHub releases </span><span style="color:#bf616a;">wget</span><span> https://github.com/getzola/zola/releases/download/v0.19.2/zola-v0.19.2-x86_64-unknown-linux-gnu.tar.gz </span><span style="color:#bf616a;">tar</span><span> xzf zola-*.tar.gz </span><span style="color:#bf616a;">sudo</span><span> mv zola /usr/local/bin/ </span></code></pre> <h3 id="windows">Windows</h3> <pre data-lang="powershell" style="background-color:#2b303b;color:#c0c5ce;" class="language-powershell "><code class="language-powershell" data-lang="powershell"><span style="color:#65737e;"># Scoop </span><span>scoop install zola </span><span> </span><span style="color:#65737e;"># Or Chocolatey </span><span>choco install zola </span></code></pre> <h2 id="creating-a-new-site">Creating a New Site</h2> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">zola</span><span> init my-site </span><span style="color:#96b5b4;">cd</span><span> my-site </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 style="background-color:#2b303b;color:#c0c5ce;"><code><span>my-site/ </span><span>├── config.toml </span><span>├── content/ </span><span>├── sass/ </span><span>├── static/ </span><span>├── templates/ </span><span>└── themes/ </span></code></pre> <h2 id="adding-content">Adding Content</h2> <p>Content goes in the <code>content/</code> directory as Markdown files:</p> <pre data-lang="markdown" style="background-color:#2b303b;color:#c0c5ce;" class="language-markdown "><code class="language-markdown" data-lang="markdown"><span>+++ </span><span>title = &quot;My First Post&quot; </span><span>date = 2024-12-27 </span><span>+++ </span><span> </span><span style="color:#8fa1b3;"># Hello, World! </span><span> </span><span>This is my first post using Zola. </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 data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">zola</span><span> serve </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 data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">zola</span><span> build </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 href="https://www.getzola.org/documentation/">Zola documentation</a></li> <li>Explore the <a href="/docs/">Tanuki theme documentation</a></li> <li>Join the <a href="https://discord.gg/WN8n6xqp">Zola Discord</a></li> </ul> <p>Happy building!</p> Thu, 26 Dec 2024 00:00:00 +0000 Unknown /tanuki/blog/blog/testing-strategies/ /tanuki/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 style="background-color:#2b303b;color:#c0c5ce;"><code><span> ╱╲ </span><span> ╱ ╲ E2E (few) </span><span> ╱────╲ </span><span> ╱ ╲ Integration (most) </span><span> ╱────────╲ </span><span> ╱ ╲ Unit (some) </span><span> ╱────────────╲ </span><span> │ Static Types │ </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 data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#65737e;">// utils.test.js </span><span style="color:#b48ead;">import </span><span>{ </span><span style="color:#bf616a;">formatCurrency</span><span>, </span><span style="color:#bf616a;">calculateDiscount </span><span>} </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">./utils</span><span>&#39;; </span><span> </span><span style="color:#8fa1b3;">describe</span><span>(&#39;</span><span style="color:#a3be8c;">formatCurrency</span><span>&#39;, () </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">it</span><span>(&#39;</span><span style="color:#a3be8c;">formats positive amounts</span><span>&#39;, () </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#8fa1b3;">formatCurrency</span><span>(</span><span style="color:#d08770;">1234.5</span><span>)).</span><span style="color:#8fa1b3;">toBe</span><span>(&#39;</span><span style="color:#a3be8c;">$1,234.50</span><span>&#39;); </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">it</span><span>(&#39;</span><span style="color:#a3be8c;">handles zero</span><span>&#39;, () </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#8fa1b3;">formatCurrency</span><span>(</span><span style="color:#d08770;">0</span><span>)).</span><span style="color:#8fa1b3;">toBe</span><span>(&#39;</span><span style="color:#a3be8c;">$0.00</span><span>&#39;); </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">it</span><span>(&#39;</span><span style="color:#a3be8c;">formats negative amounts</span><span>&#39;, () </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#8fa1b3;">formatCurrency</span><span>(-</span><span style="color:#d08770;">50</span><span>)).</span><span style="color:#8fa1b3;">toBe</span><span>(&#39;</span><span style="color:#a3be8c;">-$50.00</span><span>&#39;); </span><span> }); </span><span>}); </span><span> </span><span style="color:#8fa1b3;">describe</span><span>(&#39;</span><span style="color:#a3be8c;">calculateDiscount</span><span>&#39;, () </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">it</span><span>(&#39;</span><span style="color:#a3be8c;">applies percentage discount</span><span>&#39;, () </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#8fa1b3;">calculateDiscount</span><span>(</span><span style="color:#d08770;">100</span><span>, </span><span style="color:#d08770;">0.2</span><span>)).</span><span style="color:#8fa1b3;">toBe</span><span>(</span><span style="color:#d08770;">80</span><span>); </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">it</span><span>(&#39;</span><span style="color:#a3be8c;">never goes below zero</span><span>&#39;, () </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#8fa1b3;">calculateDiscount</span><span>(</span><span style="color:#d08770;">10</span><span>, </span><span style="color:#d08770;">2</span><span>)).</span><span style="color:#8fa1b3;">toBe</span><span>(</span><span style="color:#d08770;">0</span><span>); </span><span> }); </span><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 data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#65737e;">// api.test.js </span><span style="color:#b48ead;">import </span><span>{ </span><span style="color:#bf616a;">createServer </span><span>} </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">../server</span><span>&#39;; </span><span style="color:#b48ead;">import </span><span>{ </span><span style="color:#bf616a;">db </span><span>} </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">../database</span><span>&#39;; </span><span> </span><span style="color:#8fa1b3;">describe</span><span>(&#39;</span><span style="color:#a3be8c;">POST /users</span><span>&#39;, () </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#b48ead;">let </span><span style="color:#bf616a;">server</span><span>; </span><span> </span><span> </span><span style="color:#8fa1b3;">beforeAll</span><span>(</span><span style="color:#b48ead;">async </span><span>() </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#bf616a;">server </span><span>= </span><span style="color:#b48ead;">await </span><span style="color:#8fa1b3;">createServer</span><span>(); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">db</span><span>.</span><span style="color:#8fa1b3;">migrate</span><span>(); </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">afterAll</span><span>(</span><span style="color:#b48ead;">async </span><span>() </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">db</span><span>.</span><span style="color:#96b5b4;">close</span><span>(); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">server</span><span>.</span><span style="color:#96b5b4;">close</span><span>(); </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">beforeEach</span><span>(</span><span style="color:#b48ead;">async </span><span>() </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">db</span><span>.</span><span style="color:#8fa1b3;">truncate</span><span>(&#39;</span><span style="color:#a3be8c;">users</span><span>&#39;); </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">it</span><span>(&#39;</span><span style="color:#a3be8c;">creates a user and returns 201</span><span>&#39;, </span><span style="color:#b48ead;">async </span><span>() </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">response </span><span>= </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">server</span><span>.</span><span style="color:#8fa1b3;">inject</span><span>({ </span><span> method: &#39;</span><span style="color:#a3be8c;">POST</span><span>&#39;, </span><span> url: &#39;</span><span style="color:#a3be8c;">/users</span><span>&#39;, </span><span> payload: { </span><span> email: &#39;</span><span style="color:#a3be8c;">test@example.com</span><span>&#39;, </span><span> name: &#39;</span><span style="color:#a3be8c;">Test User</span><span>&#39;, </span><span> }, </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#bf616a;">response</span><span>.</span><span style="color:#bf616a;">statusCode</span><span>).</span><span style="color:#8fa1b3;">toBe</span><span>(</span><span style="color:#d08770;">201</span><span>); </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#bf616a;">response</span><span>.</span><span style="color:#8fa1b3;">json</span><span>()).</span><span style="color:#8fa1b3;">toMatchObject</span><span>({ </span><span> email: &#39;</span><span style="color:#a3be8c;">test@example.com</span><span>&#39;, </span><span> name: &#39;</span><span style="color:#a3be8c;">Test User</span><span>&#39;, </span><span> }); </span><span> </span><span> </span><span style="color:#65737e;">// Verify database </span><span> </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">user </span><span>= </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">db</span><span>.</span><span style="color:#8fa1b3;">query</span><span>(&#39;</span><span style="color:#a3be8c;">SELECT * FROM users WHERE email = $1</span><span>&#39;, [&#39;</span><span style="color:#a3be8c;">test@example.com</span><span>&#39;]); </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#bf616a;">user</span><span>).</span><span style="color:#8fa1b3;">toBeDefined</span><span>(); </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">it</span><span>(&#39;</span><span style="color:#a3be8c;">returns 400 for invalid email</span><span>&#39;, </span><span style="color:#b48ead;">async </span><span>() </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">response </span><span>= </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">server</span><span>.</span><span style="color:#8fa1b3;">inject</span><span>({ </span><span> method: &#39;</span><span style="color:#a3be8c;">POST</span><span>&#39;, </span><span> url: &#39;</span><span style="color:#a3be8c;">/users</span><span>&#39;, </span><span> payload: { </span><span> email: &#39;</span><span style="color:#a3be8c;">not-an-email</span><span>&#39;, </span><span> name: &#39;</span><span style="color:#a3be8c;">Test</span><span>&#39;, </span><span> }, </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#bf616a;">response</span><span>.</span><span style="color:#bf616a;">statusCode</span><span>).</span><span style="color:#8fa1b3;">toBe</span><span>(</span><span style="color:#d08770;">400</span><span>); </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#bf616a;">response</span><span>.</span><span style="color:#8fa1b3;">json</span><span>().</span><span style="color:#bf616a;">error</span><span>.code).</span><span style="color:#8fa1b3;">toBe</span><span>(&#39;</span><span style="color:#a3be8c;">VALIDATION_ERROR</span><span>&#39;); </span><span> }); </span><span>}); </span></code></pre> <h2 id="component-tests-frontend">Component Tests (Frontend)</h2> <p>Test components with realistic interactions:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#65737e;">// UserProfile.test.jsx </span><span style="color:#b48ead;">import </span><span>{ </span><span style="color:#bf616a;">render</span><span>, </span><span style="color:#bf616a;">screen</span><span>, </span><span style="color:#bf616a;">waitFor </span><span>} </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">@testing-library/react</span><span>&#39;; </span><span style="color:#b48ead;">import </span><span style="color:#bf616a;">userEvent </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">@testing-library/user-event</span><span>&#39;; </span><span style="color:#b48ead;">import </span><span>{ </span><span style="color:#bf616a;">UserProfile </span><span>} </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">./UserProfile</span><span>&#39;; </span><span style="color:#b48ead;">import </span><span>{ </span><span style="color:#bf616a;">server </span><span>} </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">../mocks/server</span><span>&#39;; </span><span style="color:#b48ead;">import </span><span>{ </span><span style="color:#bf616a;">rest </span><span>} </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">msw</span><span>&#39;; </span><span> </span><span style="color:#8fa1b3;">describe</span><span>(&#39;</span><span style="color:#a3be8c;">UserProfile</span><span>&#39;, () </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">it</span><span>(&#39;</span><span style="color:#a3be8c;">displays user information</span><span>&#39;, </span><span style="color:#b48ead;">async </span><span>() </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">render</span><span>(&lt;UserProfile userId=&quot;</span><span style="color:#a3be8c;">123</span><span>&quot; /&gt;); </span><span> </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#8fa1b3;">waitFor</span><span>(() </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(screen.</span><span style="color:#8fa1b3;">getByRole</span><span>(&#39;</span><span style="color:#a3be8c;">heading</span><span>&#39;)).</span><span style="color:#8fa1b3;">toHaveTextContent</span><span>(&#39;</span><span style="color:#a3be8c;">Jane Doe</span><span>&#39;); </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(screen.</span><span style="color:#8fa1b3;">getByText</span><span>(&#39;</span><span style="color:#a3be8c;">jane@example.com</span><span>&#39;)).</span><span style="color:#8fa1b3;">toBeInTheDocument</span><span>(); </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">it</span><span>(&#39;</span><span style="color:#a3be8c;">handles edit mode</span><span>&#39;, </span><span style="color:#b48ead;">async </span><span>() </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">user </span><span>= </span><span style="color:#bf616a;">userEvent</span><span>.</span><span style="color:#8fa1b3;">setup</span><span>(); </span><span> </span><span style="color:#8fa1b3;">render</span><span>(&lt;UserProfile userId=&quot;</span><span style="color:#a3be8c;">123</span><span>&quot; /&gt;); </span><span> </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">user</span><span>.</span><span style="color:#96b5b4;">click</span><span>(screen.</span><span style="color:#8fa1b3;">getByRole</span><span>(&#39;</span><span style="color:#a3be8c;">button</span><span>&#39;, { name: /</span><span style="color:#96b5b4;">edit</span><span>/</span><span style="color:#b48ead;">i </span><span>})); </span><span> </span><span> </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">input </span><span>= screen.</span><span style="color:#8fa1b3;">getByLabelText</span><span>(/</span><span style="color:#96b5b4;">name</span><span>/</span><span style="color:#b48ead;">i</span><span>); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">user</span><span>.</span><span style="color:#96b5b4;">clear</span><span>(</span><span style="color:#bf616a;">input</span><span>); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">user</span><span>.</span><span style="color:#8fa1b3;">type</span><span>(</span><span style="color:#bf616a;">input</span><span>, &#39;</span><span style="color:#a3be8c;">Jane Smith</span><span>&#39;); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">user</span><span>.</span><span style="color:#96b5b4;">click</span><span>(screen.</span><span style="color:#8fa1b3;">getByRole</span><span>(&#39;</span><span style="color:#a3be8c;">button</span><span>&#39;, { name: /</span><span style="color:#96b5b4;">save</span><span>/</span><span style="color:#b48ead;">i </span><span>})); </span><span> </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#8fa1b3;">waitFor</span><span>(() </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(screen.</span><span style="color:#8fa1b3;">getByRole</span><span>(&#39;</span><span style="color:#a3be8c;">heading</span><span>&#39;)).</span><span style="color:#8fa1b3;">toHaveTextContent</span><span>(&#39;</span><span style="color:#a3be8c;">Jane Smith</span><span>&#39;); </span><span> }); </span><span> }); </span><span> </span><span> </span><span style="color:#8fa1b3;">it</span><span>(&#39;</span><span style="color:#a3be8c;">shows error state</span><span>&#39;, </span><span style="color:#b48ead;">async </span><span>() </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#bf616a;">server</span><span>.</span><span style="color:#8fa1b3;">use</span><span>( </span><span> </span><span style="color:#bf616a;">rest</span><span>.</span><span style="color:#96b5b4;">get</span><span>(&#39;</span><span style="color:#a3be8c;">/api/users/:id</span><span>&#39;, (</span><span style="color:#bf616a;">req</span><span>, </span><span style="color:#bf616a;">res</span><span>, </span><span style="color:#bf616a;">ctx</span><span>) </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#b48ead;">return </span><span style="color:#8fa1b3;">res</span><span>(</span><span style="color:#bf616a;">ctx</span><span>.</span><span style="color:#8fa1b3;">status</span><span>(</span><span style="color:#d08770;">500</span><span>)); </span><span> }) </span><span> ); </span><span> </span><span> </span><span style="color:#8fa1b3;">render</span><span>(&lt;UserProfile userId=&quot;</span><span style="color:#a3be8c;">123</span><span>&quot; /&gt;); </span><span> </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#8fa1b3;">waitFor</span><span>(() </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">expect</span><span>(screen.</span><span style="color:#8fa1b3;">getByRole</span><span>(&#39;</span><span style="color:#a3be8c;">alert</span><span>&#39;)).</span><span style="color:#8fa1b3;">toHaveTextContent</span><span>(/</span><span style="color:#96b5b4;">failed to load</span><span>/</span><span style="color:#b48ead;">i</span><span>); </span><span> }); </span><span> }); </span><span>}); </span></code></pre> <h2 id="e2e-tests">E2E Tests</h2> <p>Test critical user journeys:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#65737e;">// checkout.spec.js (Playwright) </span><span style="color:#b48ead;">import </span><span>{ </span><span style="color:#bf616a;">test</span><span>, </span><span style="color:#bf616a;">expect </span><span>} </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">@playwright/test</span><span>&#39;; </span><span> </span><span style="color:#bf616a;">test</span><span>.</span><span style="color:#8fa1b3;">describe</span><span>(&#39;</span><span style="color:#a3be8c;">Checkout Flow</span><span>&#39;, () </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#8fa1b3;">test</span><span>(&#39;</span><span style="color:#a3be8c;">completes purchase successfully</span><span>&#39;, </span><span style="color:#b48ead;">async </span><span>({ </span><span style="color:#bf616a;">page </span><span>}) </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#65737e;">// Add item to cart </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#8fa1b3;">goto</span><span>(&#39;</span><span style="color:#a3be8c;">/products/widget</span><span>&#39;); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#96b5b4;">click</span><span>(&#39;</span><span style="color:#a3be8c;">button:has-text(&quot;Add to Cart&quot;)</span><span>&#39;); </span><span> </span><span> </span><span style="color:#65737e;">// Go to checkout </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#96b5b4;">click</span><span>(&#39;</span><span style="color:#a3be8c;">a:has-text(&quot;Checkout&quot;)</span><span>&#39;); </span><span> </span><span> </span><span style="color:#65737e;">// Fill shipping </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#8fa1b3;">fill</span><span>(&#39;</span><span style="color:#a3be8c;">[name=&quot;email&quot;]</span><span>&#39;, &#39;</span><span style="color:#a3be8c;">test@example.com</span><span>&#39;); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#8fa1b3;">fill</span><span>(&#39;</span><span style="color:#a3be8c;">[name=&quot;address&quot;]</span><span>&#39;, &#39;</span><span style="color:#a3be8c;">123 Main St</span><span>&#39;); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#8fa1b3;">fill</span><span>(&#39;</span><span style="color:#a3be8c;">[name=&quot;city&quot;]</span><span>&#39;, &#39;</span><span style="color:#a3be8c;">Portland</span><span>&#39;); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#8fa1b3;">selectOption</span><span>(&#39;</span><span style="color:#a3be8c;">[name=&quot;state&quot;]</span><span>&#39;, &#39;</span><span style="color:#a3be8c;">OR</span><span>&#39;); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#8fa1b3;">fill</span><span>(&#39;</span><span style="color:#a3be8c;">[name=&quot;zip&quot;]</span><span>&#39;, &#39;</span><span style="color:#a3be8c;">97201</span><span>&#39;); </span><span> </span><span> </span><span style="color:#65737e;">// Fill payment (test card) </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#8fa1b3;">fill</span><span>(&#39;</span><span style="color:#a3be8c;">[name=&quot;cardNumber&quot;]</span><span>&#39;, &#39;</span><span style="color:#a3be8c;">4242424242424242</span><span>&#39;); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#8fa1b3;">fill</span><span>(&#39;</span><span style="color:#a3be8c;">[name=&quot;expiry&quot;]</span><span>&#39;, &#39;</span><span style="color:#a3be8c;">12/25</span><span>&#39;); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#8fa1b3;">fill</span><span>(&#39;</span><span style="color:#a3be8c;">[name=&quot;cvc&quot;]</span><span>&#39;, &#39;</span><span style="color:#a3be8c;">123</span><span>&#39;); </span><span> </span><span> </span><span style="color:#65737e;">// Submit </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#96b5b4;">click</span><span>(&#39;</span><span style="color:#a3be8c;">button:has-text(&quot;Place Order&quot;)</span><span>&#39;); </span><span> </span><span> </span><span style="color:#65737e;">// Verify success </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#8fa1b3;">locator</span><span>(&#39;</span><span style="color:#a3be8c;">h1</span><span>&#39;)).</span><span style="color:#8fa1b3;">toHaveText</span><span>(&#39;</span><span style="color:#a3be8c;">Order Confirmed</span><span>&#39;); </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#8fa1b3;">expect</span><span>(</span><span style="color:#bf616a;">page</span><span>.</span><span style="color:#8fa1b3;">locator</span><span>(&#39;</span><span style="color:#a3be8c;">.order-number</span><span>&#39;)).</span><span style="color:#8fa1b3;">toBeVisible</span><span>(); </span><span> }); </span><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 data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#65737e;">// factories/user.js </span><span style="color:#b48ead;">import </span><span>{ </span><span style="color:#bf616a;">faker </span><span>} </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">@faker-js/faker</span><span>&#39;; </span><span> </span><span style="color:#b48ead;">export function </span><span style="color:#8fa1b3;">createUser</span><span>(</span><span style="color:#bf616a;">overrides </span><span>= {}) { </span><span> </span><span style="color:#b48ead;">return </span><span>{ </span><span> id: </span><span style="color:#bf616a;">faker</span><span>.</span><span style="color:#bf616a;">string</span><span>.</span><span style="color:#8fa1b3;">uuid</span><span>(), </span><span> email: </span><span style="color:#bf616a;">faker</span><span>.</span><span style="color:#bf616a;">internet</span><span>.</span><span style="color:#8fa1b3;">email</span><span>(), </span><span> name: </span><span style="color:#bf616a;">faker</span><span>.</span><span style="color:#bf616a;">person</span><span>.</span><span style="color:#8fa1b3;">fullName</span><span>(), </span><span> createdAt: </span><span style="color:#bf616a;">faker</span><span>.</span><span style="color:#bf616a;">date</span><span>.</span><span style="color:#8fa1b3;">past</span><span>(), </span><span> ...</span><span style="color:#bf616a;">overrides</span><span>, </span><span> }; </span><span>} </span><span> </span><span style="color:#65737e;">// In tests </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">user </span><span>= </span><span style="color:#8fa1b3;">createUser</span><span>({ email: &#39;</span><span style="color:#a3be8c;">specific@test.com</span><span>&#39; }); </span></code></pre> <h3 id="fixtures">Fixtures</h3> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#65737e;">// fixtures/users.json </span><span>{ </span><span> &quot;</span><span style="color:#a3be8c;">admin</span><span>&quot;: { </span><span> &quot;</span><span style="color:#a3be8c;">id</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">admin-001</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">email</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">admin@example.com</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">role</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">admin</span><span>&quot; </span><span> }, </span><span> &quot;</span><span style="color:#a3be8c;">regular</span><span>&quot;: { </span><span> &quot;</span><span style="color:#a3be8c;">id</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">user-001</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">email</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">user@example.com</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">role</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">user</span><span>&quot; </span><span> } </span><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 /tanuki/blog/blog/customizing-catppuccin-colors/ /tanuki/blog/blog/customizing-catppuccin-colors/ <h1 id="customizing-catppuccin-colors">Customizing Catppuccin Colors</h1> <p>Tanuki uses the <a href="https://github.com/catppuccin/catppuccin">Catppuccin</a> color palette, a soothing pastel theme that's easy on the eyes. But what if you want to customize it?</p> <h2 id="understanding-the-color-system">Understanding the Color System</h2> <p>Tanuki uses CSS custom properties (variables) for all colors. This makes customization straightforward—just override the variables you want to change.</p> <h3 id="the-base-palette">The Base Palette</h3> <p>Each Catppuccin flavor (Latte for light, Mocha for dark) includes:</p> <table><thead><tr><th>Variable</th><th>Purpose</th></tr></thead><tbody> <tr><td><code>--ctp-base</code></td><td>Main background</td></tr> <tr><td><code>--ctp-mantle</code></td><td>Secondary background</td></tr> <tr><td><code>--ctp-crust</code></td><td>Tertiary background</td></tr> <tr><td><code>--ctp-surface0/1/2</code></td><td>Surface layers</td></tr> <tr><td><code>--ctp-overlay0/1/2</code></td><td>Overlay layers</td></tr> <tr><td><code>--ctp-text</code></td><td>Primary text</td></tr> <tr><td><code>--ctp-subtext0/1</code></td><td>Secondary text</td></tr> </tbody></table> <h3 id="accent-colors">Accent Colors</h3> <p>The fun colors for highlights and accents:</p> <ul> <li><code>--ctp-rosewater</code> - Soft pink</li> <li><code>--ctp-flamingo</code> - Coral</li> <li><code>--ctp-pink</code> - Vibrant pink</li> <li><code>--ctp-mauve</code> - Purple (default accent)</li> <li><code>--ctp-red</code> - Error/danger</li> <li><code>--ctp-maroon</code> - Deep red</li> <li><code>--ctp-peach</code> - Orange</li> <li><code>--ctp-yellow</code> - Warning/highlight</li> <li><code>--ctp-green</code> - Success</li> <li><code>--ctp-teal</code> - Teal</li> <li><code>--ctp-sky</code> - Light blue</li> <li><code>--ctp-sapphire</code> - Blue</li> <li><code>--ctp-blue</code> - Primary blue</li> <li><code>--ctp-lavender</code> - Soft purple</li> </ul> <h2 id="changing-the-accent-color">Changing the Accent Color</h2> <p>The simplest customization is changing the accent color. Create a custom CSS file:</p> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#65737e;">/* static/css/custom.css */ </span><span style="color:#8fa1b3;">:</span><span style="color:#b48ead;">root </span><span>{ </span><span> --color-accent: </span><span style="color:#96b5b4;">var</span><span>(--ctp-pink); </span><span> --color-accent-hover: </span><span style="color:#96b5b4;">var</span><span>(--ctp-pink); </span><span>} </span></code></pre> <p>Then include it in your <code>config.toml</code>:</p> <pre data-lang="toml" style="background-color:#2b303b;color:#c0c5ce;" class="language-toml "><code class="language-toml" data-lang="toml"><span>[extra] </span><span style="color:#bf616a;">stylesheets </span><span>= [&quot;</span><span style="color:#a3be8c;">css/custom.css</span><span>&quot;] </span></code></pre> <h2 id="creating-a-custom-theme">Creating a Custom Theme</h2> <p>Want something more dramatic? Override the entire palette:</p> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#65737e;">/* A &quot;cyberpunk&quot; variant */ </span><span style="color:#8fa1b3;">[</span><span style="color:#d08770;">data-theme</span><span>=&quot;</span><span style="color:#a3be8c;">dark</span><span>&quot;</span><span style="color:#8fa1b3;">] </span><span>{ </span><span> --ctp-base: </span><span style="color:#96b5b4;">#0a0a0f</span><span>; </span><span> --ctp-mantle: </span><span style="color:#96b5b4;">#12121a</span><span>; </span><span> --ctp-crust: </span><span style="color:#96b5b4;">#08080c</span><span>; </span><span> --ctp-text: </span><span style="color:#96b5b4;">#00ff9f</span><span>; </span><span> --ctp-subtext0: </span><span style="color:#96b5b4;">#00cc7f</span><span>; </span><span> --ctp-mauve: </span><span style="color:#96b5b4;">#ff00ff</span><span>; </span><span> --ctp-pink: </span><span style="color:#96b5b4;">#ff1493</span><span>; </span><span>} </span></code></pre> <h2 id="using-other-catppuccin-flavors">Using Other Catppuccin Flavors</h2> <p>Catppuccin has four flavors: Latte, Frappé, Macchiato, and Mocha. Tanuki uses Latte (light) and Mocha (dark) by default, but you can switch to others.</p> <h3 id="using-macchiato-for-dark-mode">Using Macchiato for Dark Mode</h3> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">[</span><span style="color:#d08770;">data-theme</span><span>=&quot;</span><span style="color:#a3be8c;">dark</span><span>&quot;</span><span style="color:#8fa1b3;">] </span><span>{ </span><span> </span><span style="color:#65737e;">/* Macchiato base colors */ </span><span> --ctp-rosewater: </span><span style="color:#96b5b4;">#f4dbd6</span><span>; </span><span> --ctp-flamingo: </span><span style="color:#96b5b4;">#f0c6c6</span><span>; </span><span> --ctp-pink: </span><span style="color:#96b5b4;">#f5bde6</span><span>; </span><span> --ctp-mauve: </span><span style="color:#96b5b4;">#c6a0f6</span><span>; </span><span> --ctp-red: </span><span style="color:#96b5b4;">#ed8796</span><span>; </span><span> --ctp-maroon: </span><span style="color:#96b5b4;">#ee99a0</span><span>; </span><span> --ctp-peach: </span><span style="color:#96b5b4;">#f5a97f</span><span>; </span><span> --ctp-yellow: </span><span style="color:#96b5b4;">#eed49f</span><span>; </span><span> --ctp-green: </span><span style="color:#96b5b4;">#a6da95</span><span>; </span><span> --ctp-teal: </span><span style="color:#96b5b4;">#8bd5ca</span><span>; </span><span> --ctp-sky: </span><span style="color:#96b5b4;">#91d7e3</span><span>; </span><span> --ctp-sapphire: </span><span style="color:#96b5b4;">#7dc4e4</span><span>; </span><span> --ctp-blue: </span><span style="color:#96b5b4;">#8aadf4</span><span>; </span><span> --ctp-lavender: </span><span style="color:#96b5b4;">#b7bdf8</span><span>; </span><span> --ctp-text: </span><span style="color:#96b5b4;">#cad3f5</span><span>; </span><span> --ctp-subtext1: </span><span style="color:#96b5b4;">#b8c0e0</span><span>; </span><span> --ctp-subtext0: </span><span style="color:#96b5b4;">#a5adcb</span><span>; </span><span> --ctp-overlay2: </span><span style="color:#96b5b4;">#939ab7</span><span>; </span><span> --ctp-overlay1: </span><span style="color:#96b5b4;">#8087a2</span><span>; </span><span> --ctp-overlay0: </span><span style="color:#96b5b4;">#6e738d</span><span>; </span><span> --ctp-surface2: </span><span style="color:#96b5b4;">#5b6078</span><span>; </span><span> --ctp-surface1: </span><span style="color:#96b5b4;">#494d64</span><span>; </span><span> --ctp-surface0: </span><span style="color:#96b5b4;">#363a4f</span><span>; </span><span> --ctp-base: </span><span style="color:#96b5b4;">#24273a</span><span>; </span><span> --ctp-mantle: </span><span style="color:#96b5b4;">#1e2030</span><span>; </span><span> --ctp-crust: </span><span style="color:#96b5b4;">#181926</span><span>; </span><span>} </span></code></pre> <h2 id="tips-for-color-customization">Tips for Color Customization</h2> <ol> <li><strong>Maintain contrast</strong> - Ensure text remains readable against backgrounds</li> <li><strong>Test both modes</strong> - Check your changes in both light and dark themes</li> <li><strong>Use the palette</strong> - Stick to Catppuccin colors for a cohesive look</li> <li><strong>Consider accessibility</strong> - WCAG recommends 4.5:1 contrast for normal text</li> </ol> <h2 id="resources">Resources</h2> <ul> <li><a href="https://github.com/catppuccin/catppuccin">Catppuccin GitHub</a></li> <li><a href="https://catppuccin.com/palette">Catppuccin Palette</a></li> <li><a href="https://webaim.org/resources/contrastchecker/">Contrast Checker</a></li> </ul> <p>Happy theming!</p> Wed, 25 Dec 2024 00:00:00 +0000 Unknown /tanuki/blog/blog/docker-essentials/ /tanuki/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 data-lang="dockerfile" style="background-color:#2b303b;color:#c0c5ce;" class="language-dockerfile "><code class="language-dockerfile" data-lang="dockerfile"><span style="color:#65737e;"># Start from a base image </span><span style="color:#b48ead;">FROM</span><span> node:20-alpine </span><span> </span><span style="color:#65737e;"># Set working directory </span><span style="color:#b48ead;">WORKDIR </span><span>/app </span><span> </span><span style="color:#65737e;"># Copy package files first (for caching) </span><span style="color:#b48ead;">COPY</span><span> package*.json ./ </span><span> </span><span style="color:#65737e;"># Install dependencies </span><span style="color:#b48ead;">RUN </span><span>npm ci --only=production </span><span> </span><span style="color:#65737e;"># Copy application code </span><span style="color:#b48ead;">COPY</span><span> . . </span><span> </span><span style="color:#65737e;"># Expose the port </span><span style="color:#b48ead;">EXPOSE </span><span>3000 </span><span> </span><span style="color:#65737e;"># Run the application </span><span>CMD [&quot;</span><span style="color:#a3be8c;">node</span><span>&quot;, &quot;</span><span style="color:#a3be8c;">server.js</span><span>&quot;] </span></code></pre> <p>Build and run:</p> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">docker</span><span> build</span><span style="color:#bf616a;"> -t</span><span> myapp . </span><span style="color:#bf616a;">docker</span><span> run</span><span style="color:#bf616a;"> -p</span><span> 3000:3000 myapp </span></code></pre> <h2 id="layer-caching">Layer Caching</h2> <p>Docker caches layers. Order matters:</p> <pre data-lang="dockerfile" style="background-color:#2b303b;color:#c0c5ce;" class="language-dockerfile "><code class="language-dockerfile" data-lang="dockerfile"><span style="color:#65737e;"># Bad: reinstalls deps on any code change </span><span>COPY . . </span><span>RUN npm install </span><span> </span><span style="color:#65737e;"># Good: deps only reinstall when package.json changes </span><span>COPY package*.json ./ </span><span>RUN npm install </span><span>COPY . . </span></code></pre> <h2 id="multi-stage-builds">Multi-Stage Builds</h2> <p>Keep production images small:</p> <pre data-lang="dockerfile" style="background-color:#2b303b;color:#c0c5ce;" class="language-dockerfile "><code class="language-dockerfile" data-lang="dockerfile"><span style="color:#65737e;"># Build stage </span><span style="color:#b48ead;">FROM</span><span> node:20 </span><span style="color:#b48ead;">AS </span><span style="color:#bf616a;">builder </span><span style="color:#b48ead;">WORKDIR </span><span>/app </span><span style="color:#b48ead;">COPY</span><span> package*.json ./ </span><span style="color:#b48ead;">RUN </span><span>npm ci </span><span style="color:#b48ead;">COPY</span><span> . . </span><span style="color:#b48ead;">RUN </span><span>npm run build </span><span> </span><span style="color:#65737e;"># Production stage </span><span style="color:#b48ead;">FROM</span><span> node:20-alpine </span><span style="color:#b48ead;">WORKDIR </span><span>/app </span><span style="color:#b48ead;">COPY</span><span> --from=</span><span style="color:#bf616a;">builder</span><span> /app/dist ./dist </span><span style="color:#b48ead;">COPY</span><span> --from=</span><span style="color:#bf616a;">builder</span><span> /app/node_modules ./node_modules </span><span style="color:#b48ead;">EXPOSE </span><span>3000 </span><span>CMD [&quot;</span><span style="color:#a3be8c;">node</span><span>&quot;, &quot;</span><span style="color:#a3be8c;">dist/server.js</span><span>&quot;] </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 data-lang="yaml" style="background-color:#2b303b;color:#c0c5ce;" class="language-yaml "><code class="language-yaml" data-lang="yaml"><span style="color:#65737e;"># docker-compose.yml </span><span style="color:#bf616a;">services</span><span>: </span><span> </span><span style="color:#bf616a;">web</span><span>: </span><span> </span><span style="color:#bf616a;">build</span><span>: </span><span style="color:#d08770;">. </span><span> </span><span style="color:#bf616a;">ports</span><span>: </span><span> - &quot;</span><span style="color:#a3be8c;">3000:3000</span><span>&quot; </span><span> </span><span style="color:#bf616a;">environment</span><span>: </span><span> - </span><span style="color:#a3be8c;">DATABASE_URL=postgres://db:5432/myapp </span><span> </span><span style="color:#bf616a;">depends_on</span><span>: </span><span> - </span><span style="color:#a3be8c;">db </span><span> </span><span> </span><span style="color:#bf616a;">db</span><span>: </span><span> </span><span style="color:#bf616a;">image</span><span>: </span><span style="color:#a3be8c;">postgres:16-alpine </span><span> </span><span style="color:#bf616a;">environment</span><span>: </span><span> - </span><span style="color:#a3be8c;">POSTGRES_DB=myapp </span><span> - </span><span style="color:#a3be8c;">POSTGRES_PASSWORD=secret </span><span> </span><span style="color:#bf616a;">volumes</span><span>: </span><span> - </span><span style="color:#a3be8c;">postgres_data:/var/lib/postgresql/data </span><span> </span><span style="color:#bf616a;">volumes</span><span>: </span><span> </span><span style="color:#bf616a;">postgres_data</span><span>: </span></code></pre> <p>Run everything:</p> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">docker</span><span> compose up</span><span style="color:#bf616a;"> -d </span></code></pre> <h2 id="essential-commands">Essential Commands</h2> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#65737e;"># Images </span><span style="color:#bf616a;">docker</span><span> build</span><span style="color:#bf616a;"> -t</span><span> name:tag . </span><span style="color:#bf616a;">docker</span><span> images </span><span style="color:#bf616a;">docker</span><span> rmi image_name </span><span> </span><span style="color:#65737e;"># Containers </span><span style="color:#bf616a;">docker</span><span> run</span><span style="color:#bf616a;"> -d -p</span><span> 8080:80 nginx </span><span style="color:#bf616a;">docker</span><span> ps </span><span style="color:#65737e;"># Running containers </span><span style="color:#bf616a;">docker</span><span> ps</span><span style="color:#bf616a;"> -a </span><span style="color:#65737e;"># All containers </span><span style="color:#bf616a;">docker</span><span> stop container_id </span><span style="color:#bf616a;">docker</span><span> rm container_id </span><span> </span><span style="color:#65737e;"># Logs and debugging </span><span style="color:#bf616a;">docker</span><span> logs container_id </span><span style="color:#bf616a;">docker</span><span> logs</span><span style="color:#bf616a;"> -f</span><span> container_id </span><span style="color:#65737e;"># Follow logs </span><span style="color:#bf616a;">docker</span><span> exec</span><span style="color:#bf616a;"> -it</span><span> container_id sh </span><span> </span><span style="color:#65737e;"># Cleanup </span><span style="color:#bf616a;">docker</span><span> system prune </span><span style="color:#65737e;"># Remove unused data </span><span style="color:#bf616a;">docker</span><span> system prune</span><span style="color:#bf616a;"> -a </span><span style="color:#65737e;"># Remove everything unused </span></code></pre> <h2 id="volumes-persistent-data">Volumes: Persistent Data</h2> <p>Data inside containers is ephemeral. Use volumes:</p> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#65737e;"># Named volume </span><span style="color:#bf616a;">docker</span><span> run</span><span style="color:#bf616a;"> -v</span><span> mydata:/app/data myapp </span><span> </span><span style="color:#65737e;"># Bind mount (development) </span><span style="color:#bf616a;">docker</span><span> run</span><span style="color:#bf616a;"> -v </span><span>$(</span><span style="color:#bf616a;">pwd</span><span>):/app myapp </span></code></pre> <p>In Compose:</p> <pre data-lang="yaml" style="background-color:#2b303b;color:#c0c5ce;" class="language-yaml "><code class="language-yaml" data-lang="yaml"><span style="color:#bf616a;">services</span><span>: </span><span> </span><span style="color:#bf616a;">app</span><span>: </span><span> </span><span style="color:#bf616a;">volumes</span><span>: </span><span> - </span><span style="color:#a3be8c;">./src:/app/src </span><span style="color:#65737e;"># Bind mount for hot reload </span><span> - </span><span style="color:#a3be8c;">node_modules:/app/node_modules </span><span style="color:#65737e;"># Named volume </span><span> </span><span style="color:#bf616a;">volumes</span><span>: </span><span> </span><span style="color:#bf616a;">node_modules</span><span>: </span></code></pre> <h2 id="environment-variables">Environment Variables</h2> <pre data-lang="dockerfile" style="background-color:#2b303b;color:#c0c5ce;" class="language-dockerfile "><code class="language-dockerfile" data-lang="dockerfile"><span style="color:#65737e;"># Default value in Dockerfile </span><span>ENV NODE_ENV=production </span></code></pre> <p>Override at runtime:</p> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">docker</span><span> run</span><span style="color:#bf616a;"> -e</span><span> NODE_ENV=development myapp </span></code></pre> <p>Or use <code>.env</code> files with Compose:</p> <pre data-lang="yaml" style="background-color:#2b303b;color:#c0c5ce;" class="language-yaml "><code class="language-yaml" data-lang="yaml"><span style="color:#bf616a;">services</span><span>: </span><span> </span><span style="color:#bf616a;">app</span><span>: </span><span> </span><span style="color:#bf616a;">env_file</span><span>: </span><span> - </span><span style="color:#a3be8c;">.env </span></code></pre> <h2 id="health-checks">Health Checks</h2> <p>Let Docker know if your app is healthy:</p> <pre data-lang="dockerfile" style="background-color:#2b303b;color:#c0c5ce;" class="language-dockerfile "><code class="language-dockerfile" data-lang="dockerfile"><span>HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \ </span><span> CMD curl -f http://localhost:3000/health || exit 1 </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 data-lang="dockerfile" style="background-color:#2b303b;color:#c0c5ce;" class="language-dockerfile "><code class="language-dockerfile" data-lang="dockerfile"><span>RUN addgroup -S appgroup &amp;&amp; adduser -S appuser -G appgroup </span><span>USER appuser </span></code></pre> <h3 id="use-specific-image-tags">Use specific image tags</h3> <pre data-lang="dockerfile" style="background-color:#2b303b;color:#c0c5ce;" class="language-dockerfile "><code class="language-dockerfile" data-lang="dockerfile"><span style="color:#65737e;"># Bad: unpredictable </span><span style="color:#b48ead;">FROM</span><span> node:latest </span><span> </span><span style="color:#65737e;"># Good: reproducible </span><span style="color:#b48ead;">FROM</span><span> node:20.10-alpine3.18 </span></code></pre> <h3 id="don-t-store-secrets-in-images">Don't store secrets in images</h3> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#65737e;"># Bad </span><span style="color:#bf616a;">ENV</span><span> API_KEY=secret123 </span><span> </span><span style="color:#65737e;"># Good: pass at runtime </span><span style="color:#bf616a;">docker</span><span> run</span><span style="color:#bf616a;"> -e</span><span> API_KEY=$</span><span style="color:#bf616a;">API_KEY</span><span> myapp </span></code></pre> <h2 id="dockerignore">.dockerignore</h2> <p>Keep images lean:</p> <pre style="background-color:#2b303b;color:#c0c5ce;"><code><span>node_modules </span><span>.git </span><span>.env </span><span>*.md </span><span>Dockerfile </span><span>docker-compose.yml </span><span>.dockerignore </span><span>coverage </span><span>.nyc_output </span></code></pre> <h2 id="development-workflow">Development Workflow</h2> <pre data-lang="yaml" style="background-color:#2b303b;color:#c0c5ce;" class="language-yaml "><code class="language-yaml" data-lang="yaml"><span style="color:#65737e;"># docker-compose.dev.yml </span><span style="color:#bf616a;">services</span><span>: </span><span> </span><span style="color:#bf616a;">app</span><span>: </span><span> </span><span style="color:#bf616a;">build</span><span>: </span><span> </span><span style="color:#bf616a;">context</span><span>: </span><span style="color:#d08770;">. </span><span> </span><span style="color:#bf616a;">dockerfile</span><span>: </span><span style="color:#a3be8c;">Dockerfile.dev </span><span> </span><span style="color:#bf616a;">volumes</span><span>: </span><span> - </span><span style="color:#a3be8c;">.:/app </span><span> - </span><span style="color:#a3be8c;">/app/node_modules </span><span> </span><span style="color:#bf616a;">environment</span><span>: </span><span> - </span><span style="color:#a3be8c;">NODE_ENV=development </span><span> </span><span style="color:#bf616a;">command</span><span>: </span><span style="color:#a3be8c;">npm run dev </span></code></pre> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">docker</span><span> compose</span><span style="color:#bf616a;"> -f</span><span> docker-compose.dev.yml up </span></code></pre> <h2 id="debugging-containers">Debugging Containers</h2> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#65737e;"># Shell into running container </span><span style="color:#bf616a;">docker</span><span> exec</span><span style="color:#bf616a;"> -it</span><span> container_id sh </span><span> </span><span style="color:#65737e;"># Inspect container details </span><span style="color:#bf616a;">docker</span><span> inspect container_id </span><span> </span><span style="color:#65737e;"># View resource usage </span><span style="color:#bf616a;">docker</span><span> stats </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 /tanuki/blog/blog/api-design-best-practices/ /tanuki/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 style="background-color:#2b303b;color:#c0c5ce;"><code><span># Bad </span><span>GET /getUsers </span><span>POST /createUser </span><span>DELETE /deleteUser/123 </span><span> </span><span># Good </span><span>GET /users </span><span>POST /users </span><span>DELETE /users/123 </span></code></pre> <h2 id="use-plural-resource-names">Use Plural Resource Names</h2> <p>Consistency matters more than grammar debates:</p> <pre style="background-color:#2b303b;color:#c0c5ce;"><code><span>GET /users # List users </span><span>GET /users/123 # Get one user </span><span>POST /users # Create user </span><span>PUT /users/123 # Update user </span><span>DELETE /users/123 # Delete user </span></code></pre> <h2 id="nest-related-resources">Nest Related Resources</h2> <p>Show relationships through URL structure:</p> <pre style="background-color:#2b303b;color:#c0c5ce;"><code><span>GET /users/123/posts # Posts by user 123 </span><span>GET /posts/456/comments # Comments on post 456 </span></code></pre> <p>But don't nest too deeply:</p> <pre style="background-color:#2b303b;color:#c0c5ce;"><code><span># Too deep </span><span>GET /users/123/posts/456/comments/789/likes </span><span> </span><span># Better: use query params or separate endpoint </span><span>GET /likes?comment=789 </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 data-lang="json" style="background-color:#2b303b;color:#c0c5ce;" class="language-json "><code class="language-json" data-lang="json"><span>{ </span><span> &quot;</span><span style="color:#a3be8c;">error</span><span>&quot;: { </span><span> &quot;</span><span style="color:#a3be8c;">code</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">VALIDATION_ERROR</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">message</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">Invalid input data</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">details</span><span>&quot;: [ </span><span> { </span><span> &quot;</span><span style="color:#a3be8c;">field</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">email</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">message</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">Must be a valid email address</span><span>&quot; </span><span> }, </span><span> { </span><span> &quot;</span><span style="color:#a3be8c;">field</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">age</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">message</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">Must be at least 18</span><span>&quot; </span><span> } </span><span> ] </span><span> } </span><span>} </span></code></pre> <h2 id="pagination">Pagination</h2> <p>For any list endpoint, support pagination:</p> <pre style="background-color:#2b303b;color:#c0c5ce;"><code><span>GET /posts?page=2&amp;limit=20 </span></code></pre> <p>Return pagination metadata:</p> <pre data-lang="json" style="background-color:#2b303b;color:#c0c5ce;" class="language-json "><code class="language-json" data-lang="json"><span>{ </span><span> &quot;</span><span style="color:#a3be8c;">data</span><span>&quot;: [</span><span style="background-color:#bf616a;color:#2b303b;">...</span><span>], </span><span> &quot;</span><span style="color:#a3be8c;">pagination</span><span>&quot;: { </span><span> &quot;</span><span style="color:#a3be8c;">page</span><span>&quot;: </span><span style="color:#d08770;">2</span><span>, </span><span> &quot;</span><span style="color:#a3be8c;">limit</span><span>&quot;: </span><span style="color:#d08770;">20</span><span>, </span><span> &quot;</span><span style="color:#a3be8c;">total</span><span>&quot;: </span><span style="color:#d08770;">156</span><span>, </span><span> &quot;</span><span style="color:#a3be8c;">pages</span><span>&quot;: </span><span style="color:#d08770;">8 </span><span> } </span><span>} </span></code></pre> <p>Or use cursor-based pagination for large datasets:</p> <pre style="background-color:#2b303b;color:#c0c5ce;"><code><span>GET /posts?cursor=eyJpZCI6MTAwfQ&amp;limit=20 </span></code></pre> <h2 id="filtering-and-sorting">Filtering and Sorting</h2> <p>Use query parameters:</p> <pre style="background-color:#2b303b;color:#c0c5ce;"><code><span>GET /posts?status=published&amp;author=123 </span><span>GET /posts?sort=-created_at,title </span><span>GET /posts?created_after=2024-01-01 </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 style="background-color:#2b303b;color:#c0c5ce;"><code><span>GET /users/123?fields=id,name,email </span></code></pre> <p>Response:</p> <pre data-lang="json" style="background-color:#2b303b;color:#c0c5ce;" class="language-json "><code class="language-json" data-lang="json"><span>{ </span><span> &quot;</span><span style="color:#a3be8c;">id</span><span>&quot;: </span><span style="color:#d08770;">123</span><span>, </span><span> &quot;</span><span style="color:#a3be8c;">name</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">Jane Doe</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">email</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">jane@example.com</span><span>&quot; </span><span>} </span></code></pre> <h2 id="versioning">Versioning</h2> <p>Version your API from day one:</p> <pre style="background-color:#2b303b;color:#c0c5ce;"><code><span># URL path (most common) </span><span>GET /v1/users </span><span> </span><span># Header </span><span>GET /users </span><span>Accept: application/vnd.api+json;version=1 </span><span> </span><span># Query param (least preferred) </span><span>GET /users?version=1 </span></code></pre> <h2 id="rate-limiting-headers">Rate Limiting Headers</h2> <p>Tell clients their limits:</p> <pre style="background-color:#2b303b;color:#c0c5ce;"><code><span>X-RateLimit-Limit: 1000 </span><span>X-RateLimit-Remaining: 999 </span><span>X-RateLimit-Reset: 1640995200 </span></code></pre> <h2 id="hateoas-hypermedia">HATEOAS (Hypermedia)</h2> <p>Include links for discoverability:</p> <pre data-lang="json" style="background-color:#2b303b;color:#c0c5ce;" class="language-json "><code class="language-json" data-lang="json"><span>{ </span><span> &quot;</span><span style="color:#a3be8c;">id</span><span>&quot;: </span><span style="color:#d08770;">123</span><span>, </span><span> &quot;</span><span style="color:#a3be8c;">title</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">API Design</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">links</span><span>&quot;: { </span><span> &quot;</span><span style="color:#a3be8c;">self</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">/posts/123</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">author</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">/users/456</span><span>&quot;, </span><span> &quot;</span><span style="color:#a3be8c;">comments</span><span>&quot;: &quot;</span><span style="color:#a3be8c;">/posts/123/comments</span><span>&quot; </span><span> } </span><span>} </span></code></pre> <h2 id="idempotency">Idempotency</h2> <p>Make operations safe to retry:</p> <pre style="background-color:#2b303b;color:#c0c5ce;"><code><span># Idempotent (safe to retry) </span><span>GET /users/123 </span><span>PUT /users/123 # Full replacement </span><span>DELETE /users/123 </span><span> </span><span># Not idempotent </span><span>POST /users # Creates new each time </span></code></pre> <p>For non-idempotent operations, accept an idempotency key:</p> <pre style="background-color:#2b303b;color:#c0c5ce;"><code><span>POST /payments </span><span>Idempotency-Key: abc123 </span><span> </span><span># Retrying with same key returns cached response </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 /tanuki/blog/blog/dark-mode-best-practices/ /tanuki/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 data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#b48ead;">@media </span><span>(prefers-color-scheme: dark) { </span><span> </span><span style="color:#8fa1b3;">:</span><span style="color:#b48ead;">root </span><span>{ </span><span> --bg: </span><span style="color:#96b5b4;">#1e1e2e</span><span>; </span><span> --text: </span><span style="color:#96b5b4;">#cdd6f4</span><span>; </span><span> } </span><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 data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">:</span><span style="color:#b48ead;">root </span><span>{ </span><span> --bg: </span><span style="color:#96b5b4;">#eff1f5</span><span>; </span><span> --text: </span><span style="color:#96b5b4;">#4c4f69</span><span>; </span><span>} </span><span> </span><span style="color:#8fa1b3;">[</span><span style="color:#d08770;">data-theme</span><span>=&quot;</span><span style="color:#a3be8c;">dark</span><span>&quot;</span><span style="color:#8fa1b3;">] </span><span>{ </span><span> --bg: </span><span style="color:#96b5b4;">#1e1e2e</span><span>; </span><span> --text: </span><span style="color:#96b5b4;">#cdd6f4</span><span>; </span><span>} </span><span> </span><span style="color:#bf616a;">body </span><span>{ </span><span> background: </span><span style="color:#96b5b4;">var</span><span>(--bg); </span><span> color: </span><span style="color:#96b5b4;">var</span><span>(--text); </span><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 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 data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#b48ead;">const </span><span style="color:#bf616a;">theme </span><span>= </span><span style="color:#bf616a;">localStorage</span><span>.</span><span style="color:#96b5b4;">getItem</span><span>(&#39;</span><span style="color:#a3be8c;">theme</span><span>&#39;) || &#39;</span><span style="color:#a3be8c;">auto</span><span>&#39;; </span><span>document.documentElement.</span><span style="color:#96b5b4;">setAttribute</span><span>(&#39;</span><span style="color:#a3be8c;">data-theme</span><span>&#39;, </span><span style="color:#bf616a;">theme</span><span>); </span></code></pre> <h2 id="smooth-transitions">Smooth Transitions</h2> <p>Add a subtle transition to prevent jarring switches:</p> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#bf616a;">body </span><span>{ </span><span> transition: background-color </span><span style="color:#d08770;">0.2s </span><span>ease, color </span><span style="color:#d08770;">0.2s </span><span>ease; </span><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 /tanuki/blog/blog/modern-javascript-features/ /tanuki/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 data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#65737e;">// Before </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">city </span><span>= </span><span style="color:#bf616a;">user </span><span>&amp;&amp; </span><span style="color:#bf616a;">user</span><span>.</span><span style="color:#bf616a;">address </span><span>&amp;&amp; </span><span style="color:#bf616a;">user</span><span>.</span><span style="color:#bf616a;">address</span><span>.</span><span style="color:#bf616a;">city</span><span>; </span><span> </span><span style="color:#65737e;">// After </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">city </span><span>= </span><span style="color:#bf616a;">user</span><span>?.</span><span style="color:#bf616a;">address</span><span>?.</span><span style="color:#bf616a;">city</span><span>; </span></code></pre> <p>Works with methods and arrays too:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#b48ead;">const </span><span style="color:#bf616a;">result </span><span>= </span><span style="color:#bf616a;">obj</span><span>.method?.(); </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">first </span><span>= </span><span style="color:#bf616a;">arr</span><span>?.[</span><span style="color:#d08770;">0</span><span>]; </span></code></pre> <h2 id="nullish-coalescing">Nullish Coalescing (??)</h2> <p>Default values that respect <code>0</code> and <code>''</code>:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#65737e;">// Problem with || </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">count </span><span>= </span><span style="color:#bf616a;">response</span><span>.</span><span style="color:#bf616a;">count </span><span>|| </span><span style="color:#d08770;">10</span><span>; </span><span style="color:#65737e;">// 0 becomes 10! </span><span> </span><span style="color:#65737e;">// Solution with ?? </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">count </span><span>= </span><span style="color:#bf616a;">response</span><span>.</span><span style="color:#bf616a;">count </span><span>?? </span><span style="color:#d08770;">10</span><span>; </span><span style="color:#65737e;">// 0 stays 0 </span></code></pre> <h2 id="logical-assignment-operators">Logical Assignment Operators</h2> <p>Combine logical operators with assignment:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#65737e;">// ||= assigns if falsy </span><span style="color:#bf616a;">options</span><span>.</span><span style="color:#bf616a;">timeout </span><span>||= </span><span style="color:#d08770;">3000</span><span>; </span><span> </span><span style="color:#65737e;">// ??= assigns if nullish </span><span style="color:#bf616a;">user</span><span>.name ??= &#39;</span><span style="color:#a3be8c;">Anonymous</span><span>&#39;; </span><span> </span><span style="color:#65737e;">// &amp;&amp;= assigns if truthy </span><span style="color:#bf616a;">config</span><span>.</span><span style="color:#bf616a;">debug </span><span>&amp;&amp;= </span><span style="color:#8fa1b3;">validateDebugMode</span><span>(); </span></code></pre> <h2 id="array-methods">Array Methods</h2> <h3 id="at-negative-indexing">at() - Negative Indexing</h3> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#b48ead;">const </span><span style="color:#bf616a;">arr </span><span>= [</span><span style="color:#d08770;">1</span><span>, </span><span style="color:#d08770;">2</span><span>, </span><span style="color:#d08770;">3</span><span>, </span><span style="color:#d08770;">4</span><span>, </span><span style="color:#d08770;">5</span><span>]; </span><span> </span><span style="color:#65737e;">// Before </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">last </span><span>= </span><span style="color:#bf616a;">arr</span><span>[</span><span style="color:#bf616a;">arr</span><span>.length - </span><span style="color:#d08770;">1</span><span>]; </span><span> </span><span style="color:#65737e;">// After </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">last </span><span>= </span><span style="color:#bf616a;">arr</span><span>.</span><span style="color:#8fa1b3;">at</span><span>(-</span><span style="color:#d08770;">1</span><span>); </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">secondLast </span><span>= </span><span style="color:#bf616a;">arr</span><span>.</span><span style="color:#8fa1b3;">at</span><span>(-</span><span style="color:#d08770;">2</span><span>); </span></code></pre> <h3 id="findlast-and-findlastindex">findLast() and findLastIndex()</h3> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#b48ead;">const </span><span style="color:#bf616a;">transactions </span><span>= [ </span><span> { type: &#39;</span><span style="color:#a3be8c;">credit</span><span>&#39;, amount: </span><span style="color:#d08770;">100 </span><span>}, </span><span> { type: &#39;</span><span style="color:#a3be8c;">debit</span><span>&#39;, amount: </span><span style="color:#d08770;">50 </span><span>}, </span><span> { type: &#39;</span><span style="color:#a3be8c;">credit</span><span>&#39;, amount: </span><span style="color:#d08770;">200 </span><span>}, </span><span>]; </span><span> </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">lastCredit </span><span>= </span><span style="color:#bf616a;">transactions</span><span>.</span><span style="color:#8fa1b3;">findLast</span><span>(</span><span style="color:#bf616a;">t </span><span style="color:#b48ead;">=&gt; </span><span style="color:#bf616a;">t</span><span>.type === &#39;</span><span style="color:#a3be8c;">credit</span><span>&#39;); </span><span style="color:#65737e;">// { type: &#39;credit&#39;, amount: 200 } </span></code></pre> <h3 id="tosorted-toreversed-tospliced">toSorted(), toReversed(), toSpliced()</h3> <p>Non-mutating array operations:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#b48ead;">const </span><span style="color:#bf616a;">original </span><span>= [</span><span style="color:#d08770;">3</span><span>, </span><span style="color:#d08770;">1</span><span>, </span><span style="color:#d08770;">2</span><span>]; </span><span> </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">sorted </span><span>= </span><span style="color:#bf616a;">original</span><span>.</span><span style="color:#8fa1b3;">toSorted</span><span>(); </span><span style="color:#65737e;">// sorted: [1, 2, 3] </span><span style="color:#65737e;">// original: [3, 1, 2] - unchanged! </span><span> </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">reversed </span><span>= </span><span style="color:#bf616a;">original</span><span>.</span><span style="color:#8fa1b3;">toReversed</span><span>(); </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">removed </span><span>= </span><span style="color:#bf616a;">original</span><span>.</span><span style="color:#8fa1b3;">toSpliced</span><span>(</span><span style="color:#d08770;">1</span><span>, </span><span style="color:#d08770;">1</span><span>); </span></code></pre> <h2 id="object-groupby">Object.groupBy()</h2> <p>Native grouping without lodash:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#b48ead;">const </span><span style="color:#bf616a;">inventory </span><span>= [ </span><span> { name: &#39;</span><span style="color:#a3be8c;">apples</span><span>&#39;, type: &#39;</span><span style="color:#a3be8c;">fruit</span><span>&#39; }, </span><span> { name: &#39;</span><span style="color:#a3be8c;">bananas</span><span>&#39;, type: &#39;</span><span style="color:#a3be8c;">fruit</span><span>&#39; }, </span><span> { name: &#39;</span><span style="color:#a3be8c;">carrots</span><span>&#39;, type: &#39;</span><span style="color:#a3be8c;">vegetable</span><span>&#39; }, </span><span>]; </span><span> </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">grouped </span><span>= </span><span style="color:#ebcb8b;">Object</span><span>.</span><span style="color:#8fa1b3;">groupBy</span><span>(</span><span style="color:#bf616a;">inventory</span><span>, </span><span style="color:#bf616a;">item </span><span style="color:#b48ead;">=&gt; </span><span style="color:#bf616a;">item</span><span>.type); </span><span style="color:#65737e;">// { </span><span style="color:#65737e;">// fruit: [{ name: &#39;apples&#39;, ... }, { name: &#39;bananas&#39;, ... }], </span><span style="color:#65737e;">// vegetable: [{ name: &#39;carrots&#39;, ... }] </span><span style="color:#65737e;">// } </span></code></pre> <h2 id="promise-allsettled">Promise.allSettled()</h2> <p>Wait for all promises regardless of rejection:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#b48ead;">const </span><span style="color:#bf616a;">results </span><span>= </span><span style="color:#b48ead;">await </span><span style="color:#ebcb8b;">Promise</span><span>.</span><span style="color:#8fa1b3;">allSettled</span><span>([ </span><span> </span><span style="color:#8fa1b3;">fetch</span><span>(&#39;</span><span style="color:#a3be8c;">/api/users</span><span>&#39;), </span><span> </span><span style="color:#8fa1b3;">fetch</span><span>(&#39;</span><span style="color:#a3be8c;">/api/posts</span><span>&#39;), </span><span> </span><span style="color:#8fa1b3;">fetch</span><span>(&#39;</span><span style="color:#a3be8c;">/api/comments</span><span>&#39;), </span><span>]); </span><span> </span><span style="color:#bf616a;">results</span><span>.</span><span style="color:#96b5b4;">forEach</span><span>(</span><span style="color:#bf616a;">result </span><span style="color:#b48ead;">=&gt; </span><span>{ </span><span> </span><span style="color:#b48ead;">if </span><span>(</span><span style="color:#bf616a;">result</span><span>.status === &#39;</span><span style="color:#a3be8c;">fulfilled</span><span>&#39;) { </span><span> </span><span style="color:#ebcb8b;">console</span><span>.</span><span style="color:#96b5b4;">log</span><span>(</span><span style="color:#bf616a;">result</span><span>.value); </span><span> } </span><span style="color:#b48ead;">else </span><span>{ </span><span> </span><span style="color:#ebcb8b;">console</span><span>.</span><span style="color:#96b5b4;">error</span><span>(</span><span style="color:#bf616a;">result</span><span>.</span><span style="color:#bf616a;">reason</span><span>); </span><span> } </span><span>}); </span></code></pre> <h2 id="private-class-fields">Private Class Fields</h2> <p>True privacy with <code>#</code>:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#b48ead;">class </span><span style="color:#ebcb8b;">Counter </span><span style="color:#eff1f5;">{ </span><span style="color:#eff1f5;"> </span><span style="color:#bf616a;">#count </span><span>= </span><span style="color:#d08770;">0</span><span style="color:#eff1f5;">; </span><span style="color:#eff1f5;"> </span><span style="color:#eff1f5;"> </span><span style="color:#8fa1b3;">increment</span><span>() </span><span style="color:#eff1f5;">{ </span><span style="color:#eff1f5;"> </span><span style="color:#bf616a;">this</span><span style="color:#eff1f5;">.</span><span style="color:#bf616a;">#count</span><span>++</span><span style="color:#eff1f5;">; </span><span style="color:#eff1f5;"> } </span><span style="color:#eff1f5;"> </span><span style="color:#eff1f5;"> </span><span style="color:#b48ead;">get </span><span style="color:#8fa1b3;">value</span><span>() </span><span style="color:#eff1f5;">{ </span><span style="color:#eff1f5;"> </span><span style="color:#b48ead;">return </span><span style="color:#bf616a;">this</span><span style="color:#eff1f5;">.</span><span style="color:#bf616a;">#count</span><span style="color:#eff1f5;">; </span><span style="color:#eff1f5;"> } </span><span style="color:#eff1f5;">} </span><span> </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">counter </span><span>= new Counter(); </span><span style="color:#bf616a;">counter</span><span>.</span><span style="color:#8fa1b3;">increment</span><span>(); </span><span style="color:#ebcb8b;">console</span><span>.</span><span style="color:#96b5b4;">log</span><span>(</span><span style="color:#bf616a;">counter</span><span>.value); </span><span style="color:#65737e;">// 1 </span><span style="color:#ebcb8b;">console</span><span>.</span><span style="color:#96b5b4;">log</span><span>(</span><span style="color:#bf616a;">counter</span><span>.</span><span style="color:#bf616a;">#count</span><span>); </span><span style="color:#65737e;">// SyntaxError! </span></code></pre> <h2 id="static-blocks">Static Blocks</h2> <p>Complex static initialization:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#b48ead;">class </span><span style="color:#ebcb8b;">Config </span><span style="color:#eff1f5;">{ </span><span style="color:#eff1f5;"> </span><span style="color:#b48ead;">static </span><span style="color:#bf616a;">values</span><span style="color:#eff1f5;">; </span><span style="color:#eff1f5;"> </span><span style="color:#eff1f5;"> </span><span style="color:#b48ead;">static </span><span style="color:#eff1f5;">{ </span><span style="color:#eff1f5;"> </span><span style="color:#b48ead;">try </span><span style="color:#eff1f5;">{ </span><span style="color:#eff1f5;"> </span><span style="color:#bf616a;">this</span><span style="color:#eff1f5;">.</span><span style="color:#bf616a;">values </span><span>= </span><span style="color:#eff1f5;">JSON.</span><span style="color:#96b5b4;">parse</span><span style="color:#eff1f5;">(</span><span style="color:#bf616a;">localStorage</span><span style="color:#eff1f5;">.</span><span style="color:#96b5b4;">getItem</span><span style="color:#eff1f5;">(</span><span>&#39;</span><span style="color:#a3be8c;">config</span><span>&#39;</span><span style="color:#eff1f5;">)); </span><span style="color:#eff1f5;"> } </span><span style="color:#b48ead;">catch </span><span style="color:#eff1f5;">{ </span><span style="color:#eff1f5;"> </span><span style="color:#bf616a;">this</span><span style="color:#eff1f5;">.</span><span style="color:#bf616a;">values </span><span>= </span><span style="color:#eff1f5;">{ theme: </span><span>&#39;</span><span style="color:#a3be8c;">dark</span><span>&#39; </span><span style="color:#eff1f5;">}; </span><span style="color:#eff1f5;"> } </span><span style="color:#eff1f5;"> } </span><span style="color:#eff1f5;">} </span></code></pre> <h2 id="top-level-await">Top-Level Await</h2> <p>Use <code>await</code> outside async functions in modules:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#65737e;">// config.js </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">response </span><span>= </span><span style="color:#b48ead;">await </span><span style="color:#8fa1b3;">fetch</span><span>(&#39;</span><span style="color:#a3be8c;">/api/config</span><span>&#39;); </span><span style="color:#b48ead;">export const </span><span style="color:#bf616a;">config </span><span>= </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">response</span><span>.</span><span style="color:#8fa1b3;">json</span><span>(); </span><span> </span><span style="color:#65737e;">// main.js </span><span style="color:#b48ead;">import </span><span>{ </span><span style="color:#bf616a;">config </span><span>} </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">./config.js</span><span>&#39;; </span><span style="color:#65737e;">// config is already resolved </span></code></pre> <h2 id="temporal-api-coming-soon">Temporal API (Coming Soon)</h2> <p>Finally, a sane date/time API:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#65737e;">// Current (painful) </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">date </span><span>= new Date(); </span><span style="color:#bf616a;">date</span><span>.</span><span style="color:#96b5b4;">setDate</span><span>(</span><span style="color:#bf616a;">date</span><span>.</span><span style="color:#96b5b4;">getDate</span><span>() + </span><span style="color:#d08770;">7</span><span>); </span><span> </span><span style="color:#65737e;">// Temporal (clear) </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">date </span><span>= </span><span style="color:#bf616a;">Temporal</span><span>.</span><span style="color:#bf616a;">Now</span><span>.</span><span style="color:#8fa1b3;">plainDateISO</span><span>(); </span><span style="color:#b48ead;">const </span><span style="color:#bf616a;">nextWeek </span><span>= </span><span style="color:#bf616a;">date</span><span>.</span><span style="color:#96b5b4;">add</span><span>({ days: </span><span style="color:#d08770;">7 </span><span>}); </span></code></pre> <h2 id="error-cause">Error Cause</h2> <p>Chain errors with context:</p> <pre data-lang="javascript" style="background-color:#2b303b;color:#c0c5ce;" class="language-javascript "><code class="language-javascript" data-lang="javascript"><span style="color:#b48ead;">try </span><span>{ </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#8fa1b3;">fetchUserData</span><span>(</span><span style="color:#bf616a;">userId</span><span>); </span><span>} </span><span style="color:#b48ead;">catch </span><span>(</span><span style="color:#bf616a;">error</span><span>) { </span><span> </span><span style="color:#b48ead;">throw </span><span>new Error(&#39;</span><span style="color:#a3be8c;">Failed to load user profile</span><span>&#39;, { </span><span> cause: </span><span style="color:#bf616a;">error </span><span> }); </span><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 href="https://caniuse.com">caniuse.com</a> for browser support before using in production.</p> Wed, 18 Dec 2024 00:00:00 +0000 Unknown /tanuki/blog/blog/introduction-to-webassembly/ /tanuki/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 style="background-color:#2b303b;color:#c0c5ce;"><code><span>Source Code → Compiler → .wasm binary → Browser Runtime </span><span>(Rust, C++) (portable) (sandboxed) </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 data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#65737e;"># Install the Wasm target </span><span style="color:#bf616a;">rustup</span><span> target add wasm32-unknown-unknown </span><span> </span><span style="color:#65737e;"># Install wasm-pack </span><span style="color:#bf616a;">cargo</span><span> install wasm-pack </span></code></pre> <h3 id="2-create-a-project">2. Create a Project</h3> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">cargo</span><span> new</span><span style="color:#bf616a;"> --lib</span><span> hello-wasm </span><span style="color:#96b5b4;">cd</span><span> hello-wasm </span></code></pre> <h3 id="3-configure-cargo-toml">3. Configure Cargo.toml</h3> <pre data-lang="toml" style="background-color:#2b303b;color:#c0c5ce;" class="language-toml "><code class="language-toml" data-lang="toml"><span>[package] </span><span style="color:#bf616a;">name </span><span>= &quot;</span><span style="color:#a3be8c;">hello-wasm</span><span>&quot; </span><span style="color:#bf616a;">version </span><span>= &quot;</span><span style="color:#a3be8c;">0.1.0</span><span>&quot; </span><span style="color:#bf616a;">edition </span><span>= &quot;</span><span style="color:#a3be8c;">2021</span><span>&quot; </span><span> </span><span>[lib] </span><span style="color:#bf616a;">crate-type </span><span>= [&quot;</span><span style="color:#a3be8c;">cdylib</span><span>&quot;] </span><span> </span><span>[dependencies] </span><span style="color:#bf616a;">wasm-bindgen </span><span>= &quot;</span><span style="color:#a3be8c;">0.2</span><span>&quot; </span></code></pre> <h3 id="4-write-rust-code">4. Write Rust Code</h3> <pre data-lang="rust" style="background-color:#2b303b;color:#c0c5ce;" class="language-rust "><code class="language-rust" data-lang="rust"><span style="color:#b48ead;">use </span><span>wasm_bindgen::prelude::*; </span><span> </span><span>#[</span><span style="color:#bf616a;">wasm_bindgen</span><span>] </span><span style="color:#b48ead;">pub fn </span><span style="color:#8fa1b3;">greet</span><span>(</span><span style="color:#bf616a;">name</span><span>: &amp;</span><span style="color:#b48ead;">str</span><span>) -&gt; String { </span><span> format!(&quot;</span><span style="color:#a3be8c;">Hello, </span><span style="color:#d08770;">{}</span><span style="color:#a3be8c;">!</span><span>&quot;, name) </span><span>} </span><span> </span><span>#[</span><span style="color:#bf616a;">wasm_bindgen</span><span>] </span><span style="color:#b48ead;">pub fn </span><span style="color:#8fa1b3;">fibonacci</span><span>(</span><span style="color:#bf616a;">n</span><span>: </span><span style="color:#b48ead;">u32</span><span>) -&gt; </span><span style="color:#b48ead;">u32 </span><span>{ </span><span> </span><span style="color:#b48ead;">match</span><span> n { </span><span> </span><span style="color:#d08770;">0 </span><span>=&gt; </span><span style="color:#d08770;">0</span><span>, </span><span> </span><span style="color:#d08770;">1 </span><span>=&gt; </span><span style="color:#d08770;">1</span><span>, </span><span> _ =&gt; </span><span style="color:#96b5b4;">fibonacci</span><span>(n - </span><span style="color:#d08770;">1</span><span>) + </span><span style="color:#96b5b4;">fibonacci</span><span>(n - </span><span style="color:#d08770;">2</span><span>), </span><span> } </span><span>} </span></code></pre> <h3 id="5-build">5. Build</h3> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">wasm-pack</span><span> build</span><span style="color:#bf616a;"> --target</span><span> web </span></code></pre> <h3 id="6-use-in-javascript">6. Use in JavaScript</h3> <pre data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span>&lt;</span><span style="color:#bf616a;">script </span><span style="color:#d08770;">type</span><span>=&quot;</span><span style="color:#a3be8c;">module</span><span>&quot;&gt; </span><span> </span><span style="color:#b48ead;">import </span><span style="color:#bf616a;">init</span><span>, { </span><span style="color:#bf616a;">greet</span><span>, </span><span style="color:#bf616a;">fibonacci </span><span>} </span><span style="color:#b48ead;">from </span><span>&#39;</span><span style="color:#a3be8c;">./pkg/hello_wasm.js</span><span>&#39;; </span><span> </span><span> </span><span style="color:#b48ead;">async function </span><span style="color:#8fa1b3;">main</span><span>() { </span><span> </span><span style="color:#b48ead;">await </span><span style="color:#bf616a;">init</span><span>(); </span><span> console.</span><span style="color:#96b5b4;">log</span><span>(</span><span style="color:#bf616a;">greet</span><span>(&quot;</span><span style="color:#a3be8c;">World</span><span>&quot;)); </span><span> console.</span><span style="color:#96b5b4;">log</span><span>(</span><span style="color:#bf616a;">fibonacci</span><span>(</span><span style="color:#d08770;">40</span><span>)); </span><span style="color:#65737e;">// Much faster than JS </span><span> } </span><span> </span><span> </span><span style="color:#bf616a;">main</span><span>(); </span><span>&lt;/</span><span style="color:#bf616a;">script</span><span>&gt; </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 data-lang="rust" style="background-color:#2b303b;color:#c0c5ce;" class="language-rust "><code class="language-rust" data-lang="rust"><span style="color:#b48ead;">use </span><span>wasm_bindgen::prelude::*; </span><span style="color:#b48ead;">use </span><span>web_sys::console; </span><span> </span><span>#[</span><span style="color:#bf616a;">wasm_bindgen</span><span>(start)] </span><span style="color:#b48ead;">pub fn </span><span style="color:#8fa1b3;">main</span><span>() { </span><span> console::log_1(&amp;&quot;</span><span style="color:#a3be8c;">Hello from Wasm!</span><span>&quot;.</span><span style="color:#96b5b4;">into</span><span>()); </span><span>} </span></code></pre> <pre data-lang="toml" style="background-color:#2b303b;color:#c0c5ce;" class="language-toml "><code class="language-toml" data-lang="toml"><span style="color:#65737e;"># Add to Cargo.toml </span><span>[dependencies.web-sys] </span><span style="color:#bf616a;">version </span><span>= &quot;</span><span style="color:#a3be8c;">0.3</span><span>&quot; </span><span style="color:#bf616a;">features </span><span>= [&quot;</span><span style="color:#a3be8c;">console</span><span>&quot;] </span></code></pre> <h2 id="memory-management">Memory Management</h2> <p>Wasm has its own linear memory that JavaScript can read:</p> <pre data-lang="rust" style="background-color:#2b303b;color:#c0c5ce;" class="language-rust "><code class="language-rust" data-lang="rust"><span>#[</span><span style="color:#bf616a;">wasm_bindgen</span><span>] </span><span style="color:#b48ead;">pub fn </span><span style="color:#8fa1b3;">process_image</span><span>(</span><span style="color:#bf616a;">data</span><span>: &amp;[</span><span style="color:#b48ead;">u8</span><span>]) -&gt; Vec&lt;</span><span style="color:#b48ead;">u8</span><span>&gt; { </span><span> </span><span style="color:#65737e;">// Process and return new data </span><span> data.</span><span style="color:#96b5b4;">iter</span><span>().</span><span style="color:#96b5b4;">map</span><span>(|&amp;</span><span style="color:#bf616a;">x</span><span>| </span><span style="color:#d08770;">255 </span><span>- x).</span><span style="color:#96b5b4;">collect</span><span>() </span><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 /tanuki/blog/blog/why-static-sites/ /tanuki/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 data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#65737e;"># Install Zola </span><span style="color:#bf616a;">brew</span><span> install zola </span><span> </span><span style="color:#65737e;"># Create a new site </span><span style="color:#bf616a;">zola</span><span> init my-site </span><span style="color:#96b5b4;">cd</span><span> my-site </span><span> </span><span style="color:#65737e;"># Start the dev server </span><span style="color:#bf616a;">zola</span><span> serve </span></code></pre> <p>The future is static—and it's faster than ever.</p> Sun, 15 Dec 2024 00:00:00 +0000 Unknown /tanuki/blog/blog/css-grid-vs-flexbox/ /tanuki/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 data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">navbar </span><span>{ </span><span> display: flex; </span><span> justify-content: space-between; </span><span> align-items: center; </span><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 data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">tags </span><span>{ </span><span> display: flex; </span><span> flex-wrap: wrap; </span><span> gap: </span><span style="color:#d08770;">0.5rem</span><span>; </span><span>} </span><span> </span><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">tag </span><span>{ </span><span> </span><span style="color:#65737e;">/* Each tag sizes to its content */ </span><span> padding: </span><span style="color:#d08770;">0.25rem 0.5rem</span><span>; </span><span>} </span></code></pre> <h3 id="centering-things">Centering Things</h3> <p>The classic centering trick:</p> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">centered </span><span>{ </span><span> display: flex; </span><span> justify-content: center; </span><span> align-items: center; </span><span>} </span></code></pre> <h2 id="use-grid-when">Use Grid When...</h2> <h3 id="creating-page-layouts">Creating Page Layouts</h3> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">page </span><span>{ </span><span> display: grid; </span><span> grid-template-columns: </span><span style="color:#d08770;">250px 1fr</span><span>; </span><span> grid-template-rows: auto </span><span style="color:#d08770;">1fr </span><span>auto; </span><span> grid-template-areas: </span><span> &quot;</span><span style="color:#a3be8c;">sidebar header</span><span>&quot; </span><span> &quot;</span><span style="color:#a3be8c;">sidebar main</span><span>&quot; </span><span> &quot;</span><span style="color:#a3be8c;">sidebar footer</span><span>&quot;; </span><span>} </span></code></pre> <h3 id="equal-width-columns">Equal-Width Columns</h3> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">card-grid </span><span>{ </span><span> display: grid; </span><span> grid-template-columns: </span><span style="color:#96b5b4;">repeat</span><span>(</span><span style="color:#d08770;">3</span><span>, </span><span style="color:#d08770;">1fr</span><span>); </span><span> gap: </span><span style="color:#d08770;">1.5rem</span><span>; </span><span>} </span></code></pre> <h3 id="overlapping-elements">Overlapping Elements</h3> <p>Grid allows items to occupy the same cells:</p> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">hero </span><span>{ </span><span> display: grid; </span><span>} </span><span> </span><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">hero </span><span style="color:#b48ead;">&gt; </span><span style="color:#bf616a;">* </span><span>{ </span><span> grid-area: </span><span style="color:#d08770;">1</span><span> / </span><span style="color:#d08770;">1</span><span>; </span><span>} </span><span> </span><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">hero-image </span><span>{ </span><span> z-index: </span><span style="color:#d08770;">1</span><span>; </span><span>} </span><span> </span><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">hero-text </span><span>{ </span><span> z-index: </span><span style="color:#d08770;">2</span><span>; </span><span>} </span></code></pre> <h2 id="use-both-together">Use Both Together</h2> <p>The real power comes from combining them:</p> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#65737e;">/* Grid for the overall layout */ </span><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">dashboard </span><span>{ </span><span> display: grid; </span><span> grid-template-columns: </span><span style="color:#96b5b4;">repeat</span><span>(auto-fit, </span><span style="color:#96b5b4;">minmax</span><span>(</span><span style="color:#d08770;">300px</span><span>, </span><span style="color:#d08770;">1fr</span><span>)); </span><span> gap: </span><span style="color:#d08770;">1rem</span><span>; </span><span>} </span><span> </span><span style="color:#65737e;">/* Flexbox for card internals */ </span><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">card </span><span>{ </span><span> display: flex; </span><span> flex-direction: column; </span><span>} </span><span> </span><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">card-footer </span><span>{ </span><span> margin-top: auto; </span><span style="color:#65737e;">/* Push to bottom */ </span><span> display: flex; </span><span> justify-content: space-between; </span><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 data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">card-grid </span><span>{ </span><span> display: grid; </span><span> grid-template-columns: </span><span style="color:#96b5b4;">repeat</span><span>(</span><span style="color:#d08770;">3</span><span>, </span><span style="color:#d08770;">1fr</span><span>); </span><span>} </span><span> </span><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">card </span><span>{ </span><span> display: grid; </span><span> grid-template-rows: subgrid; </span><span> grid-row: span </span><span style="color:#d08770;">3</span><span>; </span><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 /tanuki/blog/blog/typography-for-developers/ /tanuki/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 data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">prose </span><span>{ </span><span> max-width: </span><span style="color:#d08770;">65ch</span><span>; </span><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 data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">:</span><span style="color:#b48ead;">root </span><span>{ </span><span> --text-xs: </span><span style="color:#d08770;">0.75rem</span><span>; </span><span style="color:#65737e;">/* 12px */ </span><span> --text-sm: </span><span style="color:#d08770;">0.875rem</span><span>; </span><span style="color:#65737e;">/* 14px */ </span><span> --text-base: </span><span style="color:#d08770;">1rem</span><span>; </span><span style="color:#65737e;">/* 16px */ </span><span> --text-lg: </span><span style="color:#d08770;">1.125rem</span><span>; </span><span style="color:#65737e;">/* 18px */ </span><span> --text-xl: </span><span style="color:#d08770;">1.25rem</span><span>; </span><span style="color:#65737e;">/* 20px */ </span><span> --text-2xl: </span><span style="color:#d08770;">1.5rem</span><span>; </span><span style="color:#65737e;">/* 24px */ </span><span> --text-3xl: </span><span style="color:#d08770;">1.875rem</span><span>; </span><span style="color:#65737e;">/* 30px */ </span><span> --text-4xl: </span><span style="color:#d08770;">2.25rem</span><span>; </span><span style="color:#65737e;">/* 36px */ </span><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 data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#bf616a;">h1</span><span style="color:#b48ead;">, </span><span style="color:#bf616a;">h2</span><span style="color:#b48ead;">, </span><span style="color:#bf616a;">h3 </span><span>{ </span><span> line-height: </span><span style="color:#d08770;">1.2</span><span>; </span><span>} </span><span> </span><span style="color:#bf616a;">p </span><span>{ </span><span> line-height: </span><span style="color:#d08770;">1.6</span><span>; </span><span>} </span></code></pre> <h2 id="vertical-rhythm">Vertical Rhythm</h2> <p>Consistent spacing creates visual harmony:</p> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">prose </span><span style="color:#b48ead;">&gt; </span><span style="color:#bf616a;">* </span><span style="color:#b48ead;">+ </span><span style="color:#bf616a;">* </span><span>{ </span><span> margin-top: </span><span style="color:#d08770;">1.5rem</span><span>; </span><span>} </span><span> </span><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">prose </span><span style="color:#bf616a;">h2 </span><span>{ </span><span> margin-top: </span><span style="color:#d08770;">3rem</span><span>; </span><span>} </span></code></pre> <h2 id="font-loading">Font Loading</h2> <p>Use <code>font-display: swap</code> to prevent invisible text:</p> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#b48ead;">@font-face </span><span>{ </span><span> font-family: &#39;</span><span style="color:#a3be8c;">Geist</span><span>&#39;; </span><span> src: </span><span style="color:#96b5b4;">url</span><span>(&#39;</span><span style="color:#a3be8c;">/fonts/Geist-Variable.woff2</span><span>&#39;) </span><span style="color:#96b5b4;">format</span><span>(&#39;</span><span style="color:#a3be8c;">woff2</span><span>&#39;); </span><span> font-display: swap; </span><span>} </span></code></pre> <h2 id="responsive-typography">Responsive Typography</h2> <p>Scale fonts based on viewport:</p> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#bf616a;">html </span><span>{ </span><span> font-size: clamp(</span><span style="color:#d08770;">16px</span><span>, </span><span style="color:#d08770;">1vw</span><span> + </span><span style="color:#d08770;">14px</span><span>, </span><span style="color:#d08770;">20px</span><span>); </span><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 /tanuki/blog/blog/building-accessible-websites/ /tanuki/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 data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span style="color:#65737e;">&lt;!-- Bad --&gt; </span><span>&lt;</span><span style="color:#bf616a;">div </span><span style="color:#d08770;">class</span><span>=&quot;</span><span style="color:#a3be8c;">button</span><span>&quot; </span><span style="color:#d08770;">onclick</span><span>=&quot;</span><span style="color:#bf616a;">submit</span><span>()&quot;&gt;Submit&lt;/</span><span style="color:#bf616a;">div</span><span>&gt; </span><span> </span><span style="color:#65737e;">&lt;!-- Good --&gt; </span><span>&lt;</span><span style="color:#bf616a;">button </span><span style="color:#d08770;">type</span><span>=&quot;</span><span style="color:#a3be8c;">submit</span><span>&quot;&gt;Submit&lt;/</span><span style="color:#bf616a;">button</span><span>&gt; </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 data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#65737e;">/* Make focus visible */ </span><span style="color:#8fa1b3;">:</span><span style="color:#b48ead;">focus </span><span>{ </span><span> outline: </span><span style="color:#d08770;">2px </span><span>solid </span><span style="color:#96b5b4;">var</span><span>(--accent); </span><span> outline-offset: </span><span style="color:#d08770;">2px</span><span>; </span><span>} </span><span> </span><span style="color:#65737e;">/* Don&#39;t hide focus outlines */ </span><span style="color:#8fa1b3;">:</span><span style="color:#b48ead;">focus</span><span style="color:#8fa1b3;">:</span><span style="color:#b48ead;">not(</span><span style="color:#8fa1b3;">:</span><span style="color:#b48ead;">focus-visible) </span><span>{ </span><span> outline: none; </span><span>} </span><span style="color:#8fa1b3;">:</span><span style="color:#b48ead;">focus-visible </span><span>{ </span><span> outline: </span><span style="color:#d08770;">2px </span><span>solid </span><span style="color:#96b5b4;">var</span><span>(--accent); </span><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 data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span style="color:#65737e;">&lt;!-- Informative image --&gt; </span><span>&lt;</span><span style="color:#bf616a;">img </span><span style="color:#d08770;">src</span><span>=&quot;</span><span style="color:#a3be8c;">chart.png</span><span>&quot; </span><span style="color:#d08770;">alt</span><span>=&quot;</span><span style="color:#a3be8c;">Sales increased 50% in Q4 2024</span><span>&quot;&gt; </span><span> </span><span style="color:#65737e;">&lt;!-- Decorative image --&gt; </span><span>&lt;</span><span style="color:#bf616a;">img </span><span style="color:#d08770;">src</span><span>=&quot;</span><span style="color:#a3be8c;">divider.png</span><span>&quot; </span><span style="color:#d08770;">alt</span><span>=&quot;&quot; </span><span style="color:#d08770;">role</span><span>=&quot;</span><span style="color:#a3be8c;">presentation</span><span>&quot;&gt; </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 data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span style="color:#65737e;">&lt;!-- Bad: color only --&gt; </span><span>&lt;</span><span style="color:#bf616a;">span </span><span style="color:#d08770;">class</span><span>=&quot;</span><span style="color:#a3be8c;">error</span><span>&quot;&gt;Invalid email&lt;/</span><span style="color:#bf616a;">span</span><span>&gt; </span><span> </span><span style="color:#65737e;">&lt;!-- Good: color + icon + text --&gt; </span><span>&lt;</span><span style="color:#bf616a;">span </span><span style="color:#d08770;">class</span><span>=&quot;</span><span style="color:#a3be8c;">error</span><span>&quot;&gt; </span><span> &lt;</span><span style="color:#bf616a;">svg </span><span style="color:#d08770;">aria-hidden</span><span>=&quot;</span><span style="color:#a3be8c;">true</span><span>&quot;&gt;</span><span style="color:#65737e;">&lt;!-- error icon --&gt;</span><span>&lt;/</span><span style="color:#bf616a;">svg</span><span>&gt; </span><span> Invalid email address </span><span>&lt;/</span><span style="color:#bf616a;">span</span><span>&gt; </span></code></pre> <h2 id="aria-labels">ARIA Labels</h2> <p>Use ARIA when HTML semantics aren't enough:</p> <pre data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span>&lt;</span><span style="color:#bf616a;">button </span><span style="color:#d08770;">aria-label</span><span>=&quot;</span><span style="color:#a3be8c;">Close dialog</span><span>&quot;&gt; </span><span> &lt;</span><span style="color:#bf616a;">svg</span><span>&gt;</span><span style="color:#65737e;">&lt;!-- X icon --&gt;</span><span>&lt;/</span><span style="color:#bf616a;">svg</span><span>&gt; </span><span>&lt;/</span><span style="color:#bf616a;">button</span><span>&gt; </span><span> </span><span>&lt;</span><span style="color:#bf616a;">nav </span><span style="color:#d08770;">aria-label</span><span>=&quot;</span><span style="color:#a3be8c;">Main navigation</span><span>&quot;&gt; </span><span> </span><span style="color:#65737e;">&lt;!-- links --&gt; </span><span>&lt;/</span><span style="color:#bf616a;">nav</span><span>&gt; </span><span> </span><span>&lt;</span><span style="color:#bf616a;">div </span><span style="color:#d08770;">role</span><span>=&quot;</span><span style="color:#a3be8c;">alert</span><span>&quot; </span><span style="color:#d08770;">aria-live</span><span>=&quot;</span><span style="color:#a3be8c;">polite</span><span>&quot;&gt; </span><span> Your changes have been saved. </span><span>&lt;/</span><span style="color:#bf616a;">div</span><span>&gt; </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 data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span>&lt;</span><span style="color:#bf616a;">a </span><span style="color:#d08770;">href</span><span>=&quot;</span><span style="color:#a3be8c;">#main-content</span><span>&quot; </span><span style="color:#d08770;">class</span><span>=&quot;</span><span style="color:#a3be8c;">skip-link</span><span>&quot;&gt; </span><span> Skip to main content </span><span>&lt;/</span><span style="color:#bf616a;">a</span><span>&gt; </span><span> </span><span style="color:#65737e;">&lt;!-- ... navigation ... --&gt; </span><span> </span><span>&lt;</span><span style="color:#bf616a;">main </span><span style="color:#8fa1b3;">id</span><span>=&quot;</span><span style="color:#a3be8c;">main-content</span><span>&quot;&gt; </span><span> </span><span style="color:#65737e;">&lt;!-- content --&gt; </span><span>&lt;/</span><span style="color:#bf616a;">main</span><span>&gt; </span></code></pre> <pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">skip-link </span><span>{ </span><span> position: absolute; </span><span> top: </span><span style="color:#d08770;">-100%</span><span>; </span><span>} </span><span style="color:#8fa1b3;">.</span><span style="color:#d08770;">skip-link</span><span style="color:#8fa1b3;">:</span><span style="color:#b48ead;">focus </span><span>{ </span><span> top: </span><span style="color:#d08770;">0</span><span>; </span><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 /tanuki/blog/blog/git-workflow-for-content/ /tanuki/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 data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">git</span><span> checkout</span><span style="color:#bf616a;"> -b</span><span> post/new-article-title </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 data-lang="markdown" style="background-color:#2b303b;color:#c0c5ce;" class="language-markdown "><code class="language-markdown" data-lang="markdown"><span>+++ </span><span>title = &quot;My New Article&quot; </span><span>date = 2024-12-08 </span><span>+++ </span><span> </span><span>Article content goes here... </span></code></pre> <h3 id="3-commit-your-work">3. Commit Your Work</h3> <p>Save your changes with a descriptive message:</p> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">git</span><span> add content/my-new-article.md </span><span style="color:#bf616a;">git</span><span> commit</span><span style="color:#bf616a;"> -m </span><span>&quot;</span><span style="color:#a3be8c;">Add article about Git workflows</span><span>&quot; </span></code></pre> <h3 id="4-push-and-create-a-pull-request">4. Push and Create a Pull Request</h3> <pre data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">git</span><span> push origin post/new-article-title </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 data-lang="bash" style="background-color:#2b303b;color:#c0c5ce;" class="language-bash "><code class="language-bash" data-lang="bash"><span style="color:#bf616a;">git</span><span> pull origin main </span><span style="color:#65737e;"># Resolve conflicts in your editor </span><span style="color:#bf616a;">git</span><span> add . </span><span style="color:#bf616a;">git</span><span> commit</span><span style="color:#bf616a;"> -m </span><span>&quot;</span><span style="color:#a3be8c;">Resolve merge conflict</span><span>&quot; </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>