<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: ShipInAnHour</title>
    <description>The latest articles on DEV Community by ShipInAnHour (@shipinanhour).</description>
    <link>https://dev.to/shipinanhour</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4193175%2F7fb6e504-b535-4754-9473-43bbd30e2fb8.png</url>
      <title>DEV Community: ShipInAnHour</title>
      <link>https://dev.to/shipinanhour</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/shipinanhour"/>
    <language>en</language>
    <item>
      <title>Your AI-built budget app says you're -$0.00 over budget: 6 money bugs in JavaScript (and the prompts that fix them)</title>
      <dc:creator>ShipInAnHour</dc:creator>
      <pubDate>Thu, 05 Nov 2026 13:20:49 +0000</pubDate>
      <link>https://dev.to/shipinanhour/your-ai-built-budget-app-says-youre-000-over-budget-6-money-bugs-in-javascript-and-the-222d</link>
      <guid>https://dev.to/shipinanhour/your-ai-built-budget-app-says-youre-000-over-budget-6-money-bugs-in-javascript-and-the-222d</guid>
      <description>&lt;p&gt;AI coding assistants usually store money in a budget app as a plain JavaScript number, and that one choice causes most of the small, embarrassing bugs people find after the app "works." None of them crash anything. The totals just come out a fraction of a cent wrong, and the UI turns that fraction into a red label.&lt;/p&gt;

&lt;p&gt;The budget app prompts I started from are in a &lt;a href="https://shipinanhour.gumroad.com/l/ckmqef" rel="noopener noreferrer"&gt;free sample&lt;/a&gt; if you want them.&lt;/p&gt;

&lt;p&gt;Here are six of them, what the assistant usually writes, and a prompt line for each fix. We ran the first five in Node (v24). The examples come from the kind of expense tracker you'd build in an afternoon with Cursor or Claude: expenses, categories, monthly limits, a "remaining" number, and a progress bar.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. $1.10 + $2.20 is over a $3.30 budget
&lt;/h2&gt;

&lt;p&gt;You've probably seen &lt;code&gt;0.1 + 0.2&lt;/code&gt; before. It's &lt;code&gt;0.30000000000000004&lt;/code&gt;, because numbers are binary floating point and most decimal cents can't be stored exactly. The part that matters for a budget app is what happens next.&lt;/p&gt;

&lt;p&gt;The typical generated code looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;spent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;expenses&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reduce&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;t&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;remaining&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;limit&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;spent&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;pct&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;spent&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="nx"&gt;limit&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;span&lt;/span&gt; &lt;span class="na"&gt;className&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="nx"&gt;remaining&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;text-red-600&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;""&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="nf"&gt;formatMoney&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;remaining&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;span&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;div&lt;/span&gt; &lt;span class="na"&gt;className&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="nx"&gt;pct&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;bg-red-500&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;bg-green-500&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt; &lt;span class="na"&gt;style&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;width&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;pct&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt;&lt;span class="s2"&gt;%`&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt; &lt;span class="p"&gt;/&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The budget page in our test app does exactly this. We ran the same math in Node with its own &lt;code&gt;formatMoney&lt;/code&gt; and &lt;code&gt;parseAmount&lt;/code&gt; helpers, using two expenses of $1.10 and $2.20 against a $3.30 limit:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;spent:     3.3000000000000003
remaining: -4.440892098500626e-16   -&amp;gt; red
shown as:  "-$0.00"
pct:       100.00000000000003        -&amp;gt; red bar
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;So the user spent exactly their budget and the app says they're over it, by negative zero dollars. It goes the other way too: ten $0.10 charges add up to &lt;code&gt;0.9999999999999999&lt;/code&gt;, so a "you've hit $1.00" check never fires.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The fix&lt;/strong&gt; is to stop doing arithmetic on fractional dollars. Store integer cents (&lt;code&gt;1999&lt;/code&gt; for $19.99), add and compare integers, and only divide by 100 when you format. Integers up to &lt;code&gt;Number.MAX_SAFE_INTEGER&lt;/code&gt; add exactly, which covers any personal budget.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Store every amount as an integer number of cents (&lt;code&gt;amountCents: number&lt;/code&gt;). All sums, comparisons, and "remaining" math use cents. Convert to dollars only inside &lt;code&gt;formatMoney(cents)&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;If you already have data stored in dollars, a migration step can do &lt;code&gt;Math.round(amount * 100)&lt;/code&gt; once on load. That's safe for values that were already rounded to 2 decimals.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Rounding with &lt;code&gt;Math.round(n * 100) / 100&lt;/code&gt; or &lt;code&gt;toFixed&lt;/code&gt;
&lt;/h2&gt;

&lt;p&gt;When you ask for "round to 2 decimals," you'll usually get one of these two:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;round&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mf"&gt;1.005&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;   &lt;span class="c1"&gt;// 1, not 1.01&lt;/span&gt;
&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mf"&gt;1.005&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;toFixed&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;              &lt;span class="c1"&gt;// "1.00"&lt;/span&gt;
&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mf"&gt;2.675&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;toFixed&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;              &lt;span class="c1"&gt;// "2.67"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;1.005 * 100&lt;/code&gt; is &lt;code&gt;100.49999999999999&lt;/code&gt;, so it rounds down. Our test app's &lt;code&gt;parseAmount&lt;/code&gt; uses that exact &lt;code&gt;round2&lt;/code&gt; helper, and &lt;code&gt;parseAmount("1.005")&lt;/code&gt; returns &lt;code&gt;1&lt;/code&gt;. For a budget app that's a minor surprise, but it's a sign the rounding happens in the wrong place.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;toFixed&lt;/code&gt; has a second trap: it returns a string. Once a string amount gets into state, you get things like:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;10.00&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;9.50&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;100.00&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;].&lt;/span&gt;&lt;span class="nf"&gt;sort&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;   &lt;span class="c1"&gt;// ["10.00", "100.00", "9.50"]&lt;/span&gt;
&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;10.00&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;9.50&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;                     &lt;span class="c1"&gt;// "10.009.50"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;The fix&lt;/strong&gt; is to never round a float to get cents. Parse the text the user typed straight into cents, and use &lt;code&gt;toFixed&lt;/code&gt; or &lt;code&gt;Intl&lt;/code&gt; only for display.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Never use &lt;code&gt;toFixed&lt;/code&gt; or &lt;code&gt;Math.round(n * 100) / 100&lt;/code&gt; for stored values. &lt;code&gt;toFixed&lt;/code&gt; is display-only and returns a string.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  3. &lt;code&gt;parseFloat&lt;/code&gt; accepts things that aren't amounts
&lt;/h2&gt;

&lt;p&gt;The quick version of "read the amount field" is &lt;code&gt;parseFloat(value)&lt;/code&gt; or &lt;code&gt;Number(value)&lt;/code&gt;. Both are more forgiving than you want:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nf"&gt;parseFloat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;12abc&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;      &lt;span class="c1"&gt;// 12&lt;/span&gt;
&lt;span class="nf"&gt;parseFloat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;1,299.00&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;   &lt;span class="c1"&gt;// 1&lt;/span&gt;
&lt;span class="nc"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;""&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;               &lt;span class="c1"&gt;// 0&lt;/span&gt;
&lt;span class="nc"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;  &lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;             &lt;span class="c1"&gt;// 0&lt;/span&gt;
&lt;span class="nc"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;1e3&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;            &lt;span class="c1"&gt;// 1000&lt;/span&gt;
&lt;span class="nc"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;0x10&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;           &lt;span class="c1"&gt;// 16&lt;/span&gt;
&lt;span class="nc"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;12,50&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;          &lt;span class="c1"&gt;// NaN&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;1,299.00&lt;/code&gt; one hurts. Someone pastes a price from a receipt and the app records $1. An empty field becoming &lt;code&gt;0&lt;/code&gt; is how you get $0.00 expenses that slip past an &lt;code&gt;isNaN&lt;/code&gt; check.&lt;/p&gt;

&lt;p&gt;A small parser that only accepts the shapes you expect, and returns cents directly, fixes both this and #2:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;parseCents&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;m&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="sr"&gt;/^&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;*&lt;/span&gt;&lt;span class="se"&gt;(\d&lt;/span&gt;&lt;span class="sr"&gt;+&lt;/span&gt;&lt;span class="se"&gt;)(?:\.(\d{1,2}))?\s&lt;/span&gt;&lt;span class="sr"&gt;*$/&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;exec&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;input&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;m&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;cents&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;m&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;])&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nc"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;m&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="dl"&gt;""&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;padEnd&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;0&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;cents&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;cents&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In Node, &lt;code&gt;"19.99"&lt;/code&gt; gives &lt;code&gt;1999&lt;/code&gt;, &lt;code&gt;"12.5"&lt;/code&gt; gives &lt;code&gt;1250&lt;/code&gt;, and &lt;code&gt;"1.005"&lt;/code&gt;, &lt;code&gt;"12abc"&lt;/code&gt;, &lt;code&gt;""&lt;/code&gt;, &lt;code&gt;"1e3"&lt;/code&gt; and &lt;code&gt;"0"&lt;/code&gt; all give &lt;code&gt;null&lt;/code&gt;. And $1.10 plus $2.20 becomes &lt;code&gt;110 + 220&lt;/code&gt;, which is exactly &lt;code&gt;330&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Parse amounts with one &lt;code&gt;parseCents(input)&lt;/code&gt; helper: digits, optional dot, at most 2 decimals, greater than zero. Reject everything else with an inline error. Don't use &lt;code&gt;parseFloat&lt;/code&gt; or &lt;code&gt;Number()&lt;/code&gt; on raw input.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Whether commas count as thousands separators or as a decimal mark depends on your users, so decide that on purpose instead of letting &lt;code&gt;parseFloat&lt;/code&gt; decide.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Formatting: negative zero, and currencies that aren't USD
&lt;/h2&gt;

&lt;p&gt;Even with cents, it's worth knowing what &lt;code&gt;Intl.NumberFormat&lt;/code&gt; does with edge cases, since the assistant tends to reach for it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;usd&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nx"&gt;Intl&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;NumberFormat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;en-US&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;style&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;currency&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;currency&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;USD&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="nx"&gt;usd&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;    &lt;span class="c1"&gt;// "-$0.00"&lt;/span&gt;
&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nx"&gt;Intl&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;NumberFormat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;en-US&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;style&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;currency&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;currency&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;USD&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;signDisplay&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;negative&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="nf"&gt;format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;  &lt;span class="c1"&gt;// "$0.00"&lt;/span&gt;
&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nx"&gt;Intl&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;NumberFormat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;en-US&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;style&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;currency&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;currency&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;USD&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;currencySign&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;accounting&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="nf"&gt;format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mf"&gt;12.5&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;  &lt;span class="c1"&gt;// "($12.50)"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;signDisplay: "negative"&lt;/code&gt; drops the sign on zero, which is a cheap safety net. The bigger issue shows up when the app grows a currency setting. Not every currency has 2 decimals:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nx"&gt;Intl&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;NumberFormat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;en-US&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;style&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;currency&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;currency&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;JPY&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="nf"&gt;resolvedOptions&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nx"&gt;maximumFractionDigits&lt;/span&gt;  &lt;span class="c1"&gt;// 0&lt;/span&gt;
&lt;span class="c1"&gt;// KWD -&amp;gt; 3, USD and TWD -&amp;gt; 2&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the code hard-codes &lt;code&gt;/ 100&lt;/code&gt; and &lt;code&gt;.toFixed(2)&lt;/code&gt;, a yen amount is off by a factor of 100 or shows decimals the currency doesn't have. Formatting 1234.5 as JPY gives &lt;code&gt;¥1,235&lt;/code&gt;, so a fractional yen amount gets rounded silently too. For a personal tracker, the simple rule is to store the minor-unit count and read the digit count from &lt;code&gt;Intl&lt;/code&gt; rather than assuming 2.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Create one formatter per currency with &lt;code&gt;Intl.NumberFormat&lt;/code&gt;, &lt;code&gt;signDisplay: "negative"&lt;/code&gt;. Don't hard-code 2 decimals; use &lt;code&gt;resolvedOptions().maximumFractionDigits&lt;/code&gt; if the app supports more than USD.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  5. Percentages with no budget set
&lt;/h2&gt;

&lt;p&gt;Progress bars divide by the limit, and new categories don't have one yet:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="mi"&gt;50&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;            &lt;span class="c1"&gt;// Infinity&lt;/span&gt;
&lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;             &lt;span class="c1"&gt;// NaN&lt;/span&gt;
&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;round&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;NaN&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;%&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;   &lt;span class="c1"&gt;// "NaN%"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;Math.min(Infinity, 100)&lt;/code&gt; quietly caps the first case at a full bar, which looks like the user blew a budget they never set. &lt;code&gt;NaN&lt;/code&gt; ends up as &lt;code&gt;width: NaN%&lt;/code&gt; and a "NaN%" label. Our test app guards this (&lt;code&gt;limit ? (spent / limit) * 100 : 0&lt;/code&gt;, and the summary shows a dash when there are no limits) because the prompt asked for "No budget set" explicitly. If yours didn't say that, check it.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;If a category has no limit (or a limit of 0), don't compute a percentage. Show "No budget set" and no bar. Never render &lt;code&gt;NaN&lt;/code&gt; or &lt;code&gt;Infinity&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  6. Adding up different currencies
&lt;/h2&gt;

&lt;p&gt;A common "next feature" is letting each expense have its own currency. Adding a currency code field is easy. The trap is that every total, summary card, and chart still does &lt;code&gt;reduce((t, e) =&amp;gt; t + e.amount, 0)&lt;/code&gt; across all of them, so $20 plus €20 shows as "$40.00."&lt;/p&gt;

&lt;p&gt;Unless you add exchange rates (which is a bigger decision than it looks: which rate, from which date, and what happens offline), the honest version is to group by currency.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Every total, budget, and chart is per currency. Never add amounts with different &lt;code&gt;currency&lt;/code&gt; values. If a month has more than one currency, show one total per currency.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Put the rules where the assistant reads them every time
&lt;/h2&gt;

&lt;p&gt;Each of these fixes tends to get undone the next time you ask for a feature, because the assistant falls back to its default habits. Put them in your project rules file (&lt;code&gt;.cursor/rules&lt;/code&gt;, &lt;code&gt;CLAUDE.md&lt;/code&gt;, or &lt;code&gt;AGENTS.md&lt;/code&gt;) as one block:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Money rules for this project: store amounts as integer cents. Parse input only with &lt;code&gt;parseCents&lt;/code&gt;. Do all sums and comparisons in cents. Format only with &lt;code&gt;formatMoney(cents, currency)&lt;/code&gt; using &lt;code&gt;Intl.NumberFormat&lt;/code&gt; with &lt;code&gt;signDisplay: "negative"&lt;/code&gt;. No &lt;code&gt;parseFloat&lt;/code&gt;, no &lt;code&gt;toFixed&lt;/code&gt; for stored values, no percentages when the limit is missing or 0, and no totals across different currencies.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Then ask it to check its own work with numbers that break floats: add $1.10 and $2.20 against a $3.30 limit and confirm the remaining amount reads &lt;code&gt;$0.00&lt;/code&gt; with no red and the bar isn't red. Ten $0.10 expenses should hit a $1.00 limit exactly. It's a quick check, and it catches the float bug from #1 before a user does.&lt;/p&gt;

&lt;p&gt;If you want the step-by-step prompts for the whole budget app these examples come from, the &lt;a href="https://shipinanhour.gumroad.com/l/ckmqef" rel="noopener noreferrer"&gt;free sample of the Vibe Budget App prompt pack&lt;/a&gt; has the first few prompts and checkpoints.&lt;/p&gt;

</description>
      <category>javascript</category>
      <category>nextjs</category>
      <category>ai</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Your AI-built Next.js 16 landing page looks fine. Its link preview might not: 6 metadata traps and the prompts that fix them</title>
      <dc:creator>ShipInAnHour</dc:creator>
      <pubDate>Tue, 03 Nov 2026 13:18:26 +0000</pubDate>
      <link>https://dev.to/shipinanhour/your-ai-built-nextjs-16-landing-page-looks-fine-its-link-preview-might-not-6-metadata-traps-and-35lf</link>
      <guid>https://dev.to/shipinanhour/your-ai-built-nextjs-16-landing-page-looks-fine-its-link-preview-might-not-6-metadata-traps-and-35lf</guid>
      <description>&lt;p&gt;An AI-built Next.js 16 landing page can look perfect in your browser while its link previews, &lt;code&gt;robots.txt&lt;/code&gt;, and sitemap still point at &lt;code&gt;localhost:3000&lt;/code&gt;, lose their image on every subpage, or show up as a blank card. Here are six metadata traps, each checked on a real build, with a fix and a prompt you can paste into Cursor, Claude Code, or ChatGPT.&lt;/p&gt;

&lt;p&gt;The examples come from a waitlist landing page built prompt by prompt on &lt;code&gt;create-next-app&lt;/code&gt; 16.4 (Next.js 16.4, React 19.3, Tailwind v4). None of these show up when you click around on &lt;code&gt;localhost&lt;/code&gt;, which is why they slip through. You only notice when someone shares the link.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. &lt;code&gt;localhost:3000&lt;/code&gt; ends up in production
&lt;/h2&gt;

&lt;p&gt;Ask an assistant for a site config and you'll almost always get this line. Our own prompt asked for exactly this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;NEXT_PUBLIC_SITE_URL&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;http://localhost:3000&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That fallback is fine for local dev. The problem is that nothing complains when the variable is missing in production. We built the app without it and checked the output. &lt;code&gt;robots.txt&lt;/code&gt; said &lt;code&gt;Sitemap: http://localhost:3000/sitemap.xml&lt;/code&gt;, every &lt;code&gt;&amp;lt;loc&amp;gt;&lt;/code&gt; in the sitemap was &lt;code&gt;http://localhost:3000&lt;/code&gt;, and the static admin page had an &lt;code&gt;og:image&lt;/code&gt; on localhost. The build passed without a single error.&lt;/p&gt;

&lt;p&gt;If the assistant skips &lt;code&gt;metadataBase&lt;/code&gt; entirely, Next.js does warn you, but only once, buried in the build log:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;⚠ metadataBase property in metadata export is not set for resolving social open graph or twitter images, using "http://localhost:3000".
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Also remember that &lt;code&gt;.env.local&lt;/code&gt; never reaches Vercel. The default &lt;code&gt;.gitignore&lt;/code&gt; from &lt;code&gt;create-next-app&lt;/code&gt; ignores &lt;code&gt;.env*&lt;/code&gt;, so the variable has to be set in the project settings.&lt;/p&gt;

&lt;p&gt;The fix is to make a missing URL break the build where it matters. This goes at the top of &lt;code&gt;next.config.ts&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;siteUrl&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;NEXT_PUBLIC_SITE_URL&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="dl"&gt;""&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;VERCEL_ENV&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;production&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;siteUrl&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;siteUrl&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;includes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;localhost&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)))&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`NEXT_PUBLIC_SITE_URL is "&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;siteUrl&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;". Set it to your real domain for Production and redeploy.`&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;VERCEL_ENV&lt;/code&gt; is a Vercel system variable that's available at build time, so local builds and preview deploys are left alone. In our test, faking &lt;code&gt;VERCEL_ENV=production&lt;/code&gt; with an empty URL or a localhost URL failed the build. A real domain passed.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;In &lt;code&gt;next.config.ts&lt;/code&gt;, fail the build when &lt;code&gt;VERCEL_ENV&lt;/code&gt; is &lt;code&gt;"production"&lt;/code&gt; and &lt;code&gt;NEXT_PUBLIC_SITE_URL&lt;/code&gt; is empty or contains &lt;code&gt;localhost&lt;/code&gt;. Keep the localhost fallback in &lt;code&gt;lib/site.ts&lt;/code&gt; for dev. Add &lt;code&gt;NEXT_PUBLIC_SITE_URL&lt;/code&gt; to &lt;code&gt;.env.example&lt;/code&gt; with a comment saying it must be set in Vercel's Production environment.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  2. Setting the variable after the build doesn't fix it
&lt;/h2&gt;

&lt;p&gt;The natural reaction is to add the variable in the Vercel dashboard and refresh. That doesn't work, for two reasons.&lt;/p&gt;

&lt;p&gt;First, &lt;code&gt;NEXT_PUBLIC_&lt;/code&gt; variables are inlined when you run &lt;code&gt;next build&lt;/code&gt;. The Next.js docs say they're "frozen with the value evaluated at build time." We built with &lt;code&gt;https://a.example&lt;/code&gt; and started the server with &lt;code&gt;https://b.example&lt;/code&gt;. The page and &lt;code&gt;robots.txt&lt;/code&gt; both still said &lt;code&gt;a.example&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Second, a lot of your SEO output is static. In our test runs, &lt;code&gt;npm run build&lt;/code&gt; marked the OG image, &lt;code&gt;robots.txt&lt;/code&gt;, &lt;code&gt;sitemap.xml&lt;/code&gt;, and the icon as static routes. The docs call &lt;code&gt;robots.js&lt;/code&gt; and &lt;code&gt;sitemap.js&lt;/code&gt; special Route Handlers that are "cached by default." When we built without the variable and only set it at &lt;code&gt;next start&lt;/code&gt;, the dynamic home page picked it up, but &lt;code&gt;robots.txt&lt;/code&gt;, the sitemap, and the static admin page stayed on localhost.&lt;/p&gt;

&lt;p&gt;Vercel's docs are explicit too: environment variable changes "only apply to new deployments. You must redeploy." And a variable you add only for Preview won't exist in Production.&lt;/p&gt;

&lt;p&gt;If you'd rather not maintain a variable at all, Vercel sets &lt;code&gt;VERCEL_PROJECT_PRODUCTION_URL&lt;/code&gt; on every deployment, previews included, and its docs suggest it for OG image URLs. It has no &lt;code&gt;https://&lt;/code&gt;, and since it doesn't start with &lt;code&gt;NEXT_PUBLIC_&lt;/code&gt; it won't reach client components, so only use it in server code.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;After changing any &lt;code&gt;NEXT_PUBLIC_&lt;/code&gt; variable or anything used by &lt;code&gt;robots.ts&lt;/code&gt;, &lt;code&gt;sitemap.ts&lt;/code&gt;, or &lt;code&gt;opengraph-image.tsx&lt;/code&gt;, tell me to redeploy, not just refresh. Add a line about this to the README's deploy notes.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  3. One page's &lt;code&gt;openGraph&lt;/code&gt; wipes out the layout's
&lt;/h2&gt;

&lt;p&gt;This one is easy to miss. The root layout sets a full &lt;code&gt;openGraph&lt;/code&gt; object, and then the assistant gives the pricing page its own share title:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;metadata&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Metadata&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;title&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Pricing&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;openGraph&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;title&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Pricing&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Next.js merges metadata shallowly, so a page that defines &lt;code&gt;openGraph&lt;/code&gt; replaces the parent's whole &lt;code&gt;openGraph&lt;/code&gt; object. On our build, that page lost &lt;code&gt;og:url&lt;/code&gt;, &lt;code&gt;og:site_name&lt;/code&gt;, &lt;code&gt;og:type&lt;/code&gt;, &lt;code&gt;og:image&lt;/code&gt;, and &lt;code&gt;twitter:image&lt;/code&gt;. The root &lt;code&gt;opengraph-image.tsx&lt;/code&gt; still existed, but the page no longer pointed at it. Share that link and you get a card with no image.&lt;/p&gt;

&lt;p&gt;The docs suggest pulling the shared fields into a variable and spreading it. Include the image, or you'll get everything back except the part people actually see:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/seo.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;site&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/site&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;sharedOpenGraph&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;siteName&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;site&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;website&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="kd"&gt;as const&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;images&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[{&lt;/span&gt; &lt;span class="na"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;/opengraph-image&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;width&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1200&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;height&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;630&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;alt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;site&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt; &lt;span class="p"&gt;}],&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;

&lt;span class="c1"&gt;// app/pricing/page.tsx&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;metadata&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Metadata&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;title&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Pricing&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;openGraph&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="p"&gt;...&lt;/span&gt;&lt;span class="nx"&gt;sharedOpenGraph&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;title&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Pricing&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;/pricing&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With that, the page had &lt;code&gt;og:image&lt;/code&gt; and &lt;code&gt;twitter:image&lt;/code&gt; again. The opposite case is quieter. A page that defines no &lt;code&gt;openGraph&lt;/code&gt; inherits everything, including the layout's &lt;code&gt;og:url&lt;/code&gt;. Our status page announced the homepage as its URL.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Create &lt;code&gt;lib/seo.ts&lt;/code&gt; exporting &lt;code&gt;sharedOpenGraph&lt;/code&gt; (siteName, type, and the OG image as &lt;code&gt;/opengraph-image&lt;/code&gt;, 1200×630). Every page that sets &lt;code&gt;openGraph&lt;/code&gt; must spread it first and set its own &lt;code&gt;title&lt;/code&gt; and &lt;code&gt;url&lt;/code&gt;. Never set a partial &lt;code&gt;openGraph&lt;/code&gt; object on a page.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  4. The OG image renderer isn't a browser
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;opengraph-image.tsx&lt;/code&gt; with &lt;code&gt;ImageResponse&lt;/code&gt; looks like normal JSX, so assistants write it like a normal component. It isn't one. The docs say: "Only flexbox and a subset of CSS properties are supported. Advanced layouts (e.g. &lt;code&gt;display: grid&lt;/code&gt;) will not work." There's also a 500 KB bundle limit (fonts and images count), and only &lt;code&gt;ttf&lt;/code&gt;, &lt;code&gt;otf&lt;/code&gt;, and &lt;code&gt;woff&lt;/code&gt; fonts.&lt;/p&gt;

&lt;p&gt;We tried two failure modes. A &lt;code&gt;&amp;lt;div&amp;gt;&lt;/code&gt; with three children and no &lt;code&gt;display: "flex"&lt;/code&gt; breaks the build, which at least tells you:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Error: Expected &amp;lt;div&amp;gt; to have explicit "display: flex", "display: contents", or "display: none" if it has more than one child node.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Tailwind classes are worse, because nothing complains. With &lt;code&gt;className="flex h-full w-full bg-violet-700 text-white text-6xl"&lt;/code&gt; the build passed and the route returned a valid 1200×630 PNG with a transparent background and tiny black text in the top-left corner.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;In &lt;code&gt;app/opengraph-image.tsx&lt;/code&gt;, use only inline &lt;code&gt;style&lt;/code&gt; objects, no &lt;code&gt;className&lt;/code&gt;. Every &lt;code&gt;div&lt;/code&gt; with more than one child gets &lt;code&gt;display: "flex"&lt;/code&gt;. No grid. If you load a custom font, use a &lt;code&gt;.ttf&lt;/code&gt; or &lt;code&gt;.otf&lt;/code&gt; file. After building, open &lt;code&gt;/opengraph-image&lt;/code&gt; and describe what you see.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  5. &lt;code&gt;themeColor&lt;/code&gt; in &lt;code&gt;metadata&lt;/code&gt; is ignored
&lt;/h2&gt;

&lt;p&gt;Older tutorials put &lt;code&gt;themeColor&lt;/code&gt; and &lt;code&gt;viewport&lt;/code&gt; inside &lt;code&gt;metadata&lt;/code&gt;, and assistants still copy that. Both have been deprecated there since Next.js 14. On 16.4 the build passes and prints a warning for each prerendered route:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;⚠ Unsupported metadata themeColor is configured in metadata export in /admin. Please move it to viewport export instead.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The HTML had no &lt;code&gt;theme-color&lt;/code&gt; tag at all. Moving it fixed it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;Metadata&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;Viewport&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;next&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;viewport&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Viewport&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;themeColor&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;#7c3aed&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;After that the page had &lt;code&gt;&amp;lt;meta name="theme-color" content="#7c3aed"/&amp;gt;&lt;/code&gt;. You don't need a &lt;code&gt;viewport&lt;/code&gt; string either, since Next.js adds &lt;code&gt;width=device-width, initial-scale=1&lt;/code&gt; by default.&lt;/p&gt;

&lt;p&gt;A related one, and this time the build tells you: if the assistant puts &lt;code&gt;"use client"&lt;/code&gt; on a page that exports &lt;code&gt;metadata&lt;/code&gt;, the build fails with "You are attempting to export "metadata" from a component marked with "use client"". Don't let it "fix" that by deleting the metadata. Keep the page a Server Component and move the interactive part into its own client component.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Never put &lt;code&gt;themeColor&lt;/code&gt;, &lt;code&gt;colorScheme&lt;/code&gt;, or &lt;code&gt;viewport&lt;/code&gt; in &lt;code&gt;metadata&lt;/code&gt;; use &lt;code&gt;export const viewport: Viewport&lt;/code&gt;. Pages that export &lt;code&gt;metadata&lt;/code&gt; stay Server Components. Move hooks and handlers into a separate &lt;code&gt;"use client"&lt;/code&gt; file.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  6. &lt;code&gt;robots.txt&lt;/code&gt; and &lt;code&gt;noindex&lt;/code&gt; cancel each other out
&lt;/h2&gt;

&lt;p&gt;A careful assistant will both disallow &lt;code&gt;/admin&lt;/code&gt; in &lt;code&gt;robots.ts&lt;/code&gt; and set &lt;code&gt;robots: { index: false }&lt;/code&gt; on the admin page. The test app built from our own pack does exactly that. It sounds like belt and braces, but Google's docs say: "For the noindex rule to be effective, the page or resource must not be blocked by a robots.txt file." If the crawler can't fetch the page, it never sees the &lt;code&gt;noindex&lt;/code&gt;, and the URL can still be listed if something links to it.&lt;/p&gt;

&lt;p&gt;Pick one per path. For pages you want out of search results, leave them crawlable and use &lt;code&gt;noindex&lt;/code&gt;. Use &lt;code&gt;Disallow&lt;/code&gt; for things like &lt;code&gt;/api/&lt;/code&gt; that you just don't want crawled. And neither one is access control. &lt;code&gt;robots.txt&lt;/code&gt; is a public file that lists your admin path for anyone who reads it, so the password check is what actually protects it.&lt;/p&gt;

&lt;p&gt;Previews mostly take care of themselves. Vercel adds &lt;code&gt;X-Robots-Tag: noindex&lt;/code&gt; to preview deployments and to outdated production deployments, except when a custom domain is assigned to a non-production branch. A &lt;code&gt;staging.yourdomain.com&lt;/code&gt; branch domain can be indexed unless you add the header yourself.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;In &lt;code&gt;robots.ts&lt;/code&gt;, disallow only &lt;code&gt;/api/&lt;/code&gt;. Keep &lt;code&gt;robots: { index: false }&lt;/code&gt; on &lt;code&gt;/admin&lt;/code&gt; and &lt;code&gt;/status&lt;/code&gt;. Add a comment that robots rules aren't security, and that the admin route must check the password on the server.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  A two-minute check before you share the link
&lt;/h2&gt;

&lt;p&gt;Run this against the production URL after every deploy that touches metadata:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nv"&gt;URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;https://your-domain.com
&lt;span class="k"&gt;for &lt;/span&gt;p &lt;span class="k"&gt;in&lt;/span&gt; / /status&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;do
  &lt;/span&gt;&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"== &lt;/span&gt;&lt;span class="nv"&gt;$p&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;
  curl &lt;span class="nt"&gt;-s&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$URL$p&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; | &lt;span class="nb"&gt;grep&lt;/span&gt; &lt;span class="nt"&gt;-oE&lt;/span&gt; &lt;span class="s1"&gt;'&amp;lt;meta (property|name)="(og:url|og:image|twitter:card|twitter:image)" content="[^"]*"'&lt;/span&gt;
&lt;span class="k"&gt;done
&lt;/span&gt;curl &lt;span class="nt"&gt;-s&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$URL&lt;/span&gt;&lt;span class="s2"&gt;/robots.txt"&lt;/span&gt; | &lt;span class="nb"&gt;grep&lt;/span&gt; &lt;span class="nt"&gt;-i&lt;/span&gt; sitemap
curl &lt;span class="nt"&gt;-s&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$URL&lt;/span&gt;&lt;span class="s2"&gt;/sitemap.xml"&lt;/span&gt; | &lt;span class="nb"&gt;grep&lt;/span&gt; &lt;span class="nt"&gt;-c&lt;/span&gt; localhost   &lt;span class="c"&gt;# should print 0&lt;/span&gt;
curl &lt;span class="nt"&gt;-sI&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$URL&lt;/span&gt;&lt;span class="s2"&gt;/opengraph-image"&lt;/span&gt; | &lt;span class="nb"&gt;grep&lt;/span&gt; &lt;span class="nt"&gt;-i&lt;/span&gt; &lt;span class="s1"&gt;'^content-type'&lt;/span&gt;   &lt;span class="c"&gt;# image/png&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Every page should print an &lt;code&gt;og:image&lt;/code&gt; on your real domain, the sitemap line should not say localhost, and the image route should return &lt;code&gt;image/png&lt;/code&gt;. Then open &lt;code&gt;/opengraph-image&lt;/code&gt; in a browser and look at it, because a transparent card still returns &lt;code&gt;image/png&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;It also helps to put the rules in &lt;code&gt;AGENTS.md&lt;/code&gt; or &lt;code&gt;.cursor/rules/seo.mdc&lt;/code&gt; (with &lt;code&gt;alwaysApply: true&lt;/code&gt;), so the assistant still follows them twenty prompts later:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;SEO rules:
- Site URL comes from NEXT_PUBLIC_SITE_URL; the Vercel production build fails without it.
- Pages that set openGraph spread sharedOpenGraph from lib/seo.ts.
- opengraph-image.tsx: inline styles only, display:flex on multi-child divs.
- themeColor lives in the viewport export, never in metadata.
- noindex pages are not disallowed in robots.ts.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you're starting a landing page from scratch, the &lt;a href="https://shipinanhour.gumroad.com/l/qfzgeg" rel="noopener noreferrer"&gt;free Landing Page + Waitlist sample&lt;/a&gt; has four prompts from our pack: a scaffold that won't break &lt;code&gt;npm run build&lt;/code&gt;, a Tailwind v4 dark-mode toggle, and rescues for build failures and invisible colors. The metadata prompt isn't in it, so add the prompts above yourself.&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>seo</category>
      <category>webdev</category>
      <category>ai</category>
    </item>
    <item>
      <title>Your AI-built Next.js app stores everything in localStorage? 6 ways it quietly loses data</title>
      <dc:creator>ShipInAnHour</dc:creator>
      <pubDate>Thu, 29 Oct 2026 13:06:30 +0000</pubDate>
      <link>https://dev.to/shipinanhour/your-ai-built-nextjs-app-stores-everything-in-localstorage-6-ways-it-quietly-loses-data-53np</link>
      <guid>https://dev.to/shipinanhour/your-ai-built-nextjs-app-stores-everything-in-localstorage-6-ways-it-quietly-loses-data-53np</guid>
      <description>&lt;p&gt;If an AI assistant built your Next.js side project on &lt;code&gt;localStorage&lt;/code&gt;, it probably works fine until a corrupt value, a full quota, a second tab, or Safari's 7-day cleanup wipes someone's data without a single error on screen. Here are six checks, each with a tested fix and a prompt you can paste into Cursor, Claude Code, or ChatGPT.&lt;/p&gt;

&lt;p&gt;The examples come from a small budget app (expenses, categories, monthly budgets) built prompt by prompt with no backend. Everything below was run in headless Chromium unless it says otherwise.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. "Return an empty array on bad JSON" deletes the data on the next save
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;JSON.parse&lt;/code&gt; throws on anything malformed, so assistants wrap it and fall back to &lt;code&gt;[]&lt;/code&gt;. That's the right instinct, and it's what our own test app did. A smoke test confirmed the page shows "No expenses yet" instead of crashing.&lt;/p&gt;

&lt;p&gt;The problem is the next line of code that runs. The user adds an expense, the app pushes it onto that empty array and saves. In our test, a truncated value with two records, &lt;code&gt;[{"id":1},{"id":2}&lt;/code&gt;, became &lt;code&gt;[{"id":3}]&lt;/code&gt; after one add. The two old records were gone, and nothing ever said so.&lt;/p&gt;

&lt;p&gt;Keep the broken value before you replace it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;load&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;boolean&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;items&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="nb"&gt;window&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;undefined&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;items&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;raw&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;localStorage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getItem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;raw&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;items&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;parsed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;JSON&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;parse&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Array&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isArray&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;parsed&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;items&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;parsed&lt;/span&gt; &lt;span class="kd"&gt;as &lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// fall through and keep a copy below&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="nx"&gt;localStorage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setItem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;:corrupt-&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// keep the evidence&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;items&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When &lt;code&gt;ok&lt;/code&gt; is &lt;code&gt;false&lt;/code&gt;, show a banner ("Some saved data couldn't be read. A copy was kept.") so the user knows to export before adding more.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;In &lt;code&gt;lib/storage.ts&lt;/code&gt;, when a stored value is missing, return &lt;code&gt;[]&lt;/code&gt;. When it's present but invalid JSON or not an array, copy the raw string to &lt;code&gt;&amp;lt;key&amp;gt;:corrupt-&amp;lt;timestamp&amp;gt;&lt;/code&gt; before returning &lt;code&gt;[]&lt;/code&gt;, and return a flag so the page can show a warning banner. Never overwrite a value you couldn't parse without keeping a copy.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  2. &lt;code&gt;setItem&lt;/code&gt; can throw, and the UI keeps pretending it saved
&lt;/h2&gt;

&lt;p&gt;MDN puts &lt;code&gt;localStorage&lt;/code&gt; at up to 5 MiB per origin, and &lt;code&gt;setItem&lt;/code&gt; throws &lt;code&gt;QuotaExceededError&lt;/code&gt; when you go over. In our test, writing values of a million characters each, the fifth &lt;code&gt;setItem&lt;/code&gt; threw:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;QuotaExceededError: Failed to execute 'setItem' on 'Storage':
Setting the value of 'big4' exceeded the quota.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A text-only budget app takes a long time to get there. Add something like receipt photos as base64 strings and you'll get there much sooner. The usual AI-generated code updates React state first and calls &lt;code&gt;setItem&lt;/code&gt; after, with no &lt;code&gt;try/catch&lt;/code&gt;. The new row shows up on screen and is gone on refresh.&lt;/p&gt;

&lt;p&gt;Make every save report whether it worked, and only update the UI from storage:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;items&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="p"&gt;[]):&lt;/span&gt; &lt;span class="nx"&gt;boolean&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;localStorage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setItem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;JSON&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stringify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;items&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nb"&gt;window&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;dispatchEvent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;CustomEvent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;app:storage-error&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="na"&gt;detail&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Could not save. Storage may be full.&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}));&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Our test app does exactly this, with a small banner component that listens for the event.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Wrap every &lt;code&gt;localStorage.setItem&lt;/code&gt; in &lt;code&gt;try/catch&lt;/code&gt; and return &lt;code&gt;true&lt;/code&gt; or &lt;code&gt;false&lt;/code&gt;. On failure, dispatch a &lt;code&gt;window&lt;/code&gt; event, and add a layout-level banner that listens for it and says "Could not save. Storage may be full." After saving, reload the list from storage instead of trusting the state you just set.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  3. Every project on &lt;code&gt;localhost:3000&lt;/code&gt; shares one storage
&lt;/h2&gt;

&lt;p&gt;Storage belongs to an origin, which is scheme plus hostname plus port. Your budget app, last week's todo app, and the tutorial you cloned yesterday all ran on &lt;code&gt;http://localhost:3000&lt;/code&gt;, so they all read and write the same &lt;code&gt;localStorage&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;In our test, a second tab on the same host and port saw a key set by the first. A tab on port 3082 saw nothing, and so did &lt;code&gt;127.0.0.1&lt;/code&gt; on the same port, because that's a different hostname. Then &lt;code&gt;localStorage.clear()&lt;/code&gt; from one "project" also wiped an unrelated &lt;code&gt;theme&lt;/code&gt; key.&lt;/p&gt;

&lt;p&gt;Two rules fix this. Prefix every key with the app name (&lt;code&gt;vibe-budget:expenses&lt;/code&gt;, not &lt;code&gt;expenses&lt;/code&gt;). And never call &lt;code&gt;localStorage.clear()&lt;/code&gt; in a "Reset data" button. Remove only your own keys:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nb"&gt;Object&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;keys&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;localStorage&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;k&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;k&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;startsWith&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;vibe-budget:&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;k&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;vibe-budget:theme&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;forEach&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;k&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;localStorage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;removeItem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;k&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the test, that removed the app's data and left both &lt;code&gt;other-app:todos&lt;/code&gt; and the saved theme alone.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Every &lt;code&gt;localStorage&lt;/code&gt; key in this project must start with &lt;code&gt;&amp;lt;app-name&amp;gt;:&lt;/code&gt;. Never call &lt;code&gt;localStorage.clear()&lt;/code&gt;. "Clear all data" removes only keys with our prefix, keeps the theme key, then re-seeds defaults.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  4. Two open tabs overwrite each other
&lt;/h2&gt;

&lt;p&gt;Most generated pages load data once in &lt;code&gt;useEffect&lt;/code&gt;, keep it in state, and save the whole array from state on every change. Open the app in two tabs and that becomes last-write-wins with stale data.&lt;/p&gt;

&lt;p&gt;We reproduced it with two tabs. Tab B added an item and saved. Tab A, still holding the old array in memory, added its own item and saved. B's item disappeared.&lt;/p&gt;

&lt;p&gt;Two small changes cover it. First, read the latest value from storage right before you write, instead of saving whatever is in state:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;addExpense&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Expense&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;current&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;loadExpenses&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt; &lt;span class="c1"&gt;// re-read, don't trust state&lt;/span&gt;
  &lt;span class="nf"&gt;saveExpenses&lt;/span&gt;&lt;span class="p"&gt;([...&lt;/span&gt;&lt;span class="nx"&gt;current&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;]);&lt;/span&gt;
  &lt;span class="nf"&gt;setExpenses&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;loadExpenses&lt;/span&gt;&lt;span class="p"&gt;());&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With that change the same test kept all three items. Second, listen for the &lt;code&gt;storage&lt;/code&gt; event so the other tab refreshes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nf"&gt;useEffect&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;onStorage&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="na"&gt;ev&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;StorageEvent&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;ev&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nf"&gt;startsWith&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;vibe-budget:&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="nf"&gt;setExpenses&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;loadExpenses&lt;/span&gt;&lt;span class="p"&gt;());&lt;/span&gt;
  &lt;span class="p"&gt;};&lt;/span&gt;
  &lt;span class="nb"&gt;window&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addEventListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;storage&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;onStorage&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return &lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nb"&gt;window&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;removeEventListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;storage&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;onStorage&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="p"&gt;[]);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;storage&lt;/code&gt; event fires in the other tabs of the same origin, not in the tab that made the change. Our test confirmed that, so don't count on it to refresh the tab doing the writing.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Every add, edit, or delete must read the current array from storage, apply the change, save it, then reload state from storage. Also add a &lt;code&gt;storage&lt;/code&gt; event listener on each page that reloads its data when a key with our prefix changes in another tab.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  5. Import accepts the file, but not safely
&lt;/h2&gt;

&lt;p&gt;Export/import is the only backup a &lt;code&gt;localStorage&lt;/code&gt; app has, so it's worth checking twice. Our test app does the basics well: it checks that &lt;code&gt;expenses&lt;/code&gt;, &lt;code&gt;categories&lt;/code&gt;, and &lt;code&gt;budgets&lt;/code&gt; are arrays with the right field types, rejects a bad file, and leaves existing data untouched. Export, clear site data, refresh, import, and everything came back.&lt;/p&gt;

&lt;p&gt;Two gaps were still there when we read the code. The export writes &lt;code&gt;version: 1&lt;/code&gt;, but import never looks at it. So the day you rename a field, an old backup will either fail validation or, worse, pass it. And import writes three keys one after another without checking whether each save worked. If the second write hits the quota, you end up with new categories and old expenses.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;In import: reject files whose &lt;code&gt;version&lt;/code&gt; is missing or higher than the current one, and run a &lt;code&gt;migrate(data, fromVersion)&lt;/code&gt; step for older versions. Before writing anything, keep a copy of the current data in memory. Save all three keys, check each &lt;code&gt;save()&lt;/code&gt; result, and if any fails, restore the copy and show an error.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  6. Safari deletes it after 7 days without a visit
&lt;/h2&gt;

&lt;p&gt;This is the one you can't fix in code. WebKit's tracking prevention deletes all of a site's script-writable storage, &lt;code&gt;localStorage&lt;/code&gt; included, "after seven days of Safari use without user interaction on the site." MDN describes the same proactive eviction and notes that only Safari does it. A web app added to the Home Screen has its own day counter, so it isn't affected the same way.&lt;/p&gt;

&lt;p&gt;So a Safari user who forgets your budget app for a week and a half can come back to an empty app. Private windows are worse: their &lt;code&gt;localStorage&lt;/code&gt; is gone when the last private tab closes.&lt;/p&gt;

&lt;p&gt;The honest fix is to tell users and make backups easy:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Say in the UI and README that data lives only in this browser, and recommend Export.&lt;/li&gt;
&lt;li&gt;Show "Last backup: never" or a date on the settings page, and nudge after a week.&lt;/li&gt;
&lt;li&gt;If you can't afford to lose the data, it needs a server. That's a different app.&lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
&lt;p&gt;Add a "Data is stored only in this browser" note on the settings page with an Export button next to it. Store the date of the last export under &lt;code&gt;&amp;lt;app-name&amp;gt;:lastExport&lt;/code&gt; and show it. If it's more than 7 days old or missing, show a small reminder to export.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Put the rules where the assistant reads them every time
&lt;/h2&gt;

&lt;p&gt;Ten prompts in, an assistant may no longer follow storage rules you gave it back in prompt 3. Put them in &lt;code&gt;AGENTS.md&lt;/code&gt; or &lt;code&gt;.cursor/rules/storage.mdc&lt;/code&gt; (with &lt;code&gt;alwaysApply: true&lt;/code&gt;) so they're loaded on every request:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Storage rules:
- All keys start with "vibe-budget:". Never call localStorage.clear().
- Never overwrite a value you couldn't parse; back it up first.
- setItem is always in try/catch and returns true/false.
- Read from storage right before every write; reload state after.
- Finish every change with: npm run lint &amp;amp;&amp;amp; npm run build
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then test the failure paths on purpose. Put &lt;code&gt;{corrupt&lt;/code&gt; in a key from DevTools and reload. Open two tabs and add something in each. Clear site data and import your last export. If you only test the happy path, you won't find any of these bugs.&lt;/p&gt;

&lt;p&gt;If you want to see the storage layer prompt our test app was built from, it's prompt 3 in the &lt;a href="https://shipinanhour.gumroad.com/l/ckmqef" rel="noopener noreferrer"&gt;free Vibe Budget App sample&lt;/a&gt;, along with the scaffold, types, seed data, and navigation prompts. It covers the parse fallback and prefixed keys, and since the Oct 30 update it also saves the unreadable value to a backup key before falling back, as section 1 suggests.&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>react</category>
      <category>javascript</category>
      <category>webdev</category>
    </item>
    <item>
      <title>AI-built waitlist forms in Next.js 16: 6 traps to check before launch (and the prompts that fix them)</title>
      <dc:creator>ShipInAnHour</dc:creator>
      <pubDate>Mon, 26 Oct 2026 13:13:47 +0000</pubDate>
      <link>https://dev.to/shipinanhour/ai-built-waitlist-forms-in-nextjs-16-6-traps-to-check-before-launch-and-the-prompts-that-fix-57dn</link>
      <guid>https://dev.to/shipinanhour/ai-built-waitlist-forms-in-nextjs-16-6-traps-to-check-before-launch-and-the-prompts-that-fix-57dn</guid>
      <description>&lt;p&gt;An AI-built Next.js waitlist form can look finished and still lose signups, let a script skip its rate limit, and put emails in the URL, so run these six checks before you share the link. The prompts and commands below are ready to copy.&lt;/p&gt;

&lt;p&gt;The setup is the usual first version for a launch page: a Client Component form that POSTs JSON to a Route Handler (&lt;code&gt;app/api/waitlist/route.ts&lt;/code&gt;), which writes to a small JSON file. Versions: Next.js 16.4.2, React 19.3, Node 20. If the scaffold itself is fighting you (&lt;code&gt;cacheComponents&lt;/code&gt; build errors, Tailwind v4 dark mode), that's in &lt;a href="https://dev.to/shipinanhour/nextjs-16-tailwind-v4-5-traps-ai-coding-assistants-keep-hitting-and-the-prompts-that-fix-them-3ioc"&gt;the earlier post on Next.js 16 + Tailwind v4 traps&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. The "loading" check isn't a lock
&lt;/h2&gt;

&lt;p&gt;The standard guard looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;onSubmit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;React&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;FormEvent&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;HTMLFormElement&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;preventDefault&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;loading&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// reads state from this render&lt;/span&gt;
  &lt;span class="nf"&gt;setStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;loading&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;/api/waitlist&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="cm"&gt;/* ... */&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For a real double-click, this plus &lt;code&gt;disabled={status === "loading"}&lt;/code&gt; holds up. In a Playwright check, a double-click and pressing Enter twice each sent one request. But &lt;code&gt;status&lt;/code&gt; is captured by this render's closure, so two submits in the same task both see &lt;code&gt;"idle"&lt;/code&gt;. Calling &lt;code&gt;form.requestSubmit()&lt;/code&gt; twice in a row sent two POSTs. Extensions, autofill scripts and your own tests can do exactly that.&lt;/p&gt;

&lt;p&gt;A ref changes immediately, so make it the lock and keep the state for the UI:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;inFlight&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;useRef&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;onSubmit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;React&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;FormEvent&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;HTMLFormElement&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;preventDefault&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;inFlight&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;current&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nx"&gt;inFlight&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;current&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;setStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;loading&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// fetch + handle response&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;finally&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;inFlight&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;current&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With that change all three checks sent one POST, and &lt;code&gt;npm run lint&lt;/code&gt; still reported 0 problems.&lt;/p&gt;

&lt;p&gt;If you move to a Server Action with &lt;code&gt;useActionState&lt;/code&gt;, the React docs say "React queues and executes multiple calls to &lt;code&gt;dispatchAction&lt;/code&gt; sequentially." A second submit gets queued, not dropped. Disable the button with &lt;code&gt;isPending&lt;/code&gt;, and make the server safe to call twice anyway.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;The waitlist form must not send two requests for one signup. Use a &lt;code&gt;useRef&lt;/code&gt; in-flight flag as the lock (set before &lt;code&gt;fetch&lt;/code&gt;, cleared in &lt;code&gt;finally&lt;/code&gt;) and keep &lt;code&gt;status&lt;/code&gt; state only for the button label and &lt;code&gt;disabled&lt;/code&gt;. The API must return the same result if the same email is posted twice.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  2. Duplicate signups and the file store race
&lt;/h2&gt;

&lt;p&gt;A prompt that only says "save signups to a JSON file" leaves room for the simplest version: read the file, push, write the file. That's fine for one request at a time. With a plain &lt;code&gt;fs/promises&lt;/code&gt; version and no lock, 20 concurrent signups with 20 different emails left one row in the file, in three runs out of three. Every request read the same empty array and the last write won.&lt;/p&gt;

&lt;p&gt;The same email twice at the same moment is worse: both requests reported "created", each with a different referral code, and only one was saved. Whoever got the losing response now shares a referral link that points at nothing.&lt;/p&gt;

&lt;p&gt;For a single-server file store, serialize every read-modify-write and write atomically:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;queue&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;unknown&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;resolve&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;withLock&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;fn&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;T&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;run&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;queue&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;then&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;fn&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;fn&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;queue&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;run&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;catch&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;run&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="c1"&gt;// inside withLock: read â†’ find existing by email â†’ push â†’ write to .tmp â†’ rename&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With the lock, eight parallel POSTs of the same email produced one row and one referral code. Normalize before comparing (&lt;code&gt;email.trim().toLowerCase()&lt;/code&gt;), so &lt;code&gt;" DUP@Test.com "&lt;/code&gt; matches &lt;code&gt;dup@test.com&lt;/code&gt;, and decide what a duplicate returns. A 200 with the existing spot is friendlier than an error. In our test runs the duplicate checkpoint returned &lt;code&gt;alreadyJoined: true&lt;/code&gt; with the same code.&lt;/p&gt;

&lt;p&gt;One tradeoff: that friendly response also tells anyone who types a stranger's email that the person is on your list, and hands over their referral code. For a pre-launch waitlist that may be fine. If it isn't, return the same "Check your inbox" message for new and existing emails and send the spot by email.&lt;/p&gt;

&lt;p&gt;On Postgres, let the database enforce it. The Postgres docs note that a unique index on &lt;code&gt;lower(email)&lt;/code&gt; rejects values that differ only in case:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;UNIQUE&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="n"&gt;signups_email_lower_idx&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;signups&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;lower&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;email&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  3. Validation and spam checks that only exist in the browser
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;type="email"&lt;/code&gt; and a regex in the component are UX, not protection. Your Route Handler is a public URL, and so is a Server Action: the Next.js data security guide says a Server Action "is reachable via a direct POST request, not just through your application's UI," and tells you to always validate client input. So the server repeats every check: string type, trimmed, at most 254 characters, a basic pattern, and an optional &lt;code&gt;ref&lt;/code&gt; that must match your code format.&lt;/p&gt;

&lt;p&gt;A honeypot is cheap. Add a field people never see, and if it's filled, return a normal-looking success without saving:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;div&lt;/span&gt; &lt;span class="na"&gt;aria-hidden&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"true"&lt;/span&gt; &lt;span class="na"&gt;className&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"absolute -left-[9999px]"&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;label&lt;/span&gt; &lt;span class="na"&gt;htmlFor&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"company"&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;Company&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;label&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;input&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"company"&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"company"&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"text"&lt;/span&gt; &lt;span class="na"&gt;tabIndex&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt; &lt;span class="na"&gt;autoComplete&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"off"&lt;/span&gt; &lt;span class="p"&gt;/&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;div&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It only catches bots that fill every field, so you still want a rate limit, and that's where the first version gets fragile. The quick version, and the one in our test app, is an in-memory &lt;code&gt;Map&lt;/code&gt; keyed by the first value of &lt;code&gt;x-forwarded-for&lt;/code&gt;. Two problems:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;That header is whatever the client sends unless a proxy you control overwrites it. A different &lt;code&gt;X-Forwarded-For&lt;/code&gt; on each request got 12 of 12 signups through a 10-per-minute limit. MDN's header reference lists "rate-limiter avoidance" as a consequence of trusting untrusted values.&lt;/li&gt;
&lt;li&gt;The &lt;code&gt;Map&lt;/code&gt; lives in one process. It resets on restart, and each extra instance gets its own.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Try it with the app running on port 3000:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="k"&gt;for &lt;/span&gt;i &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;seq &lt;/span&gt;1 12&lt;span class="si"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;do
  &lt;/span&gt;curl &lt;span class="nt"&gt;-s&lt;/span&gt; &lt;span class="nt"&gt;-o&lt;/span&gt; /dev/null &lt;span class="nt"&gt;-w&lt;/span&gt; &lt;span class="s2"&gt;"%{http_code} "&lt;/span&gt; &lt;span class="nt"&gt;-X&lt;/span&gt; POST localhost:3000/api/waitlist &lt;span class="se"&gt;\&lt;/span&gt;
    &lt;span class="nt"&gt;-H&lt;/span&gt; &lt;span class="s1"&gt;'content-type: application/json'&lt;/span&gt; &lt;span class="nt"&gt;-H&lt;/span&gt; &lt;span class="s2"&gt;"x-forwarded-for: 10.0.0.&lt;/span&gt;&lt;span class="nv"&gt;$i&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="se"&gt;\&lt;/span&gt;
    &lt;span class="nt"&gt;-d&lt;/span&gt; &lt;span class="s2"&gt;"{&lt;/span&gt;&lt;span class="se"&gt;\"&lt;/span&gt;&lt;span class="s2"&gt;email&lt;/span&gt;&lt;span class="se"&gt;\"&lt;/span&gt;&lt;span class="s2"&gt;:&lt;/span&gt;&lt;span class="se"&gt;\"&lt;/span&gt;&lt;span class="s2"&gt;t&lt;/span&gt;&lt;span class="nv"&gt;$i&lt;/span&gt;&lt;span class="s2"&gt;@test.com&lt;/span&gt;&lt;span class="se"&gt;\"&lt;/span&gt;&lt;span class="s2"&gt;}"&lt;/span&gt;
&lt;span class="k"&gt;done&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Twelve &lt;code&gt;200&lt;/code&gt;s means the limit is decorative. Read the client IP only from the header your host's proxy sets, and move the counter to shared storage once you run more than one instance. Leave headroom for your own checkpoints, too. In our test runs, 5 per minute tripped the curl checkpoint and was raised to 10.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Treat &lt;code&gt;app/api/waitlist/route.ts&lt;/code&gt; as a public endpoint. Re-validate everything on the server, add a hidden &lt;code&gt;company&lt;/code&gt; honeypot that returns a fake success without saving, and rate limit per IP. Only trust the client IP from the header my host's proxy sets. Note in the README that an in-memory limiter resets on restart and isn't shared across instances.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  4. Storage that disappears on deploy
&lt;/h2&gt;

&lt;p&gt;A file under &lt;code&gt;process.cwd()/data&lt;/code&gt; works on your laptop, a VPS, or a container with a volume. It doesn't on serverless hosts. Vercel's runtime docs describe a "read-only filesystem with writable &lt;code&gt;/tmp&lt;/code&gt; scratch space," and their files guide recommends object storage when you need to write.&lt;/p&gt;

&lt;p&gt;Put the decision in the prompt: keep storage behind a few functions (&lt;code&gt;readSignups&lt;/code&gt;, &lt;code&gt;addSignup&lt;/code&gt;, &lt;code&gt;deleteSignup&lt;/code&gt;) in one server-only module, so moving to a hosted database touches one file. Keep &lt;code&gt;/data/&lt;/code&gt; in &lt;code&gt;.gitignore&lt;/code&gt; so test emails never land in your repo.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Secrets that end up in client JavaScript
&lt;/h2&gt;

&lt;p&gt;Next.js inlines any &lt;code&gt;NEXT_PUBLIC_&lt;/code&gt; variable into the browser bundle at build time, and the value is frozen after &lt;code&gt;next build&lt;/code&gt;. Variables without the prefix stay on the server. When a Client Component can't read a value, the tempting fix, for you or the assistant, is to add the prefix, which ships that key to every visitor.&lt;/p&gt;

&lt;p&gt;Check after a build:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm run build
&lt;span class="nb"&gt;grep&lt;/span&gt; &lt;span class="nt"&gt;-rl&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;grep &lt;/span&gt;ADMIN_PASSWORD .env.local | &lt;span class="nb"&gt;cut&lt;/span&gt; &lt;span class="nt"&gt;-d&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nt"&gt;-f2&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; .next/static &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"LEAKED"&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"not in client bundle"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On the test app the admin password was in 0 client files, and the public site URL, which is meant to be public, was in 1. For a hard guarantee, the Next.js docs suggest &lt;code&gt;import "server-only"&lt;/code&gt; at the top of storage and auth modules, so importing them from a Client Component fails the build. One more from our test runs: the default &lt;code&gt;.env*&lt;/code&gt; rule in &lt;code&gt;.gitignore&lt;/code&gt; also hides &lt;code&gt;.env.example&lt;/code&gt;, so add &lt;code&gt;!.env.example&lt;/code&gt; if you want to commit one.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. The success state and accessibility
&lt;/h2&gt;

&lt;p&gt;Three things to check after the form "works":&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Focus.&lt;/strong&gt; When the success card replaces the form, the focused input is gone and focus drops to &lt;code&gt;&amp;lt;body&amp;gt;&lt;/code&gt;. Move it to the message:
&lt;/li&gt;
&lt;/ol&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;   &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;doneRef&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;useRef&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;HTMLParagraphElement&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
   &lt;span class="nf"&gt;useEffect&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
     &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;done&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nx"&gt;doneRef&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;current&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nf"&gt;focus&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
   &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt;&lt;span class="p"&gt;]);&lt;/span&gt;
   &lt;span class="c1"&gt;// &amp;lt;p ref={doneRef} tabIndex={-1}&amp;gt;You're #12 on the list&amp;lt;/p&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ol&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Live regions.&lt;/strong&gt; MDN says to establish the live region before updating its content, ideally in the initial markup. An &lt;code&gt;aria-live&lt;/code&gt; card that only mounts on success may not be announced. Keep one always-rendered message element with &lt;code&gt;aria-live="polite"&lt;/code&gt; for errors and success, and point the input's &lt;code&gt;aria-describedby&lt;/code&gt; at it.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Before hydration.&lt;/strong&gt; In our test runs, one smoke-test failure came from a click that landed before the page hydrated. That matters because a &lt;code&gt;&amp;lt;form&amp;gt;&lt;/code&gt; without &lt;code&gt;method&lt;/code&gt; submits as GET: with JavaScript disabled, the test app navigated to &lt;code&gt;/?email=early%40test.com&amp;amp;company=&lt;/code&gt;. That's an email in the URL, browser history, and maybe your analytics. At minimum add &lt;code&gt;method="post"&lt;/code&gt;. If the form should actually work before hydration, the React docs note that &lt;code&gt;useActionState&lt;/code&gt; with a Server Function can show the server's response before hydration completes.&lt;/p&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  One prompt to audit what you have
&lt;/h2&gt;

&lt;p&gt;If the form already exists, paste this before launch:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Audit my waitlist form and API, and fix only what fails: (1) two synchronous &lt;code&gt;requestSubmit()&lt;/code&gt; calls send one request; use a ref lock. (2) 20 concurrent POSTs with different emails save 20 rows, and the same email posted twice at once saves one row with one referral code. (3) the server re-validates email (trim, lowercase, â‰¤254 chars). (4) a hidden &lt;code&gt;company&lt;/code&gt; honeypot returns fake success without saving. (5) changing &lt;code&gt;X-Forwarded-For&lt;/code&gt; can't bypass the rate limit. (6) no secret appears in &lt;code&gt;.next/static&lt;/code&gt; after &lt;code&gt;npm run build&lt;/code&gt;. (7) after success, focus moves to the message and a persistent &lt;code&gt;aria-live&lt;/code&gt; element announces errors and success. (8) the &lt;code&gt;&amp;lt;form&amp;gt;&lt;/code&gt; has &lt;code&gt;method="post"&lt;/code&gt;. Show me the command or test you used for each item, then run &lt;code&gt;npm run lint&lt;/code&gt; and &lt;code&gt;npm run build&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Asking for the command behind each item matters more than the list itself. The AI will happily report "rate limiting added" for a limiter that one header walks right past.&lt;/p&gt;

&lt;p&gt;If you want the setup prompts that come before all this, the &lt;a href="https://shipinanhour.gumroad.com/l/qfzgeg" rel="noopener noreferrer"&gt;free sample&lt;/a&gt; has four prompts from our Landing Page + Waitlist pack: a build-safe Next.js 16 scaffold, a Tailwind v4 dark-mode toggle, and rescues for build failures and invisible colors or gradients.&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>react</category>
      <category>ai</category>
      <category>webdev</category>
    </item>
    <item>
      <title>How to prompt an AI to build a Next.js app step by step (budget app example, with checkpoints that catch bugs)</title>
      <dc:creator>ShipInAnHour</dc:creator>
      <pubDate>Thu, 22 Oct 2026 13:02:31 +0000</pubDate>
      <link>https://dev.to/shipinanhour/how-to-prompt-an-ai-to-build-a-nextjs-app-step-by-step-budget-app-example-with-checkpoints-that-cem</link>
      <guid>https://dev.to/shipinanhour/how-to-prompt-an-ai-to-build-a-nextjs-app-step-by-step-budget-app-example-with-checkpoints-that-cem</guid>
      <description>&lt;p&gt;"Build me a budget app" works for about ten minutes. Then the AI coding assistant fills in every decision you didn't make, and you're debugging choices you never saw.&lt;/p&gt;

&lt;p&gt;The fix is boring but it works. Split the app into small prompts, make each prompt decide everything up front, and end each step with a checkpoint you can see. This post walks through that structure with a real example: a Next.js 16 + Tailwind v4 expense tracker that stores everything in &lt;code&gt;localStorage&lt;/code&gt; (expenses, categories, monthly budgets, a summary page).&lt;/p&gt;

&lt;p&gt;We wrote a 25-prompt sequence for that app and ran it as written, one prompt at a time, reading each prompt literally the way an assistant would. Most of it worked. Where it broke, the cause wasn't hard code but a sentence that left a choice open. Those are below.&lt;/p&gt;

&lt;p&gt;Versions: &lt;code&gt;create-next-app&lt;/code&gt; 16.4.2 (Next.js 16.4.2, React 19.3, Tailwind CSS v4), Node 20.&lt;/p&gt;




&lt;h2&gt;
  
  
  The shape of a good step prompt
&lt;/h2&gt;

&lt;p&gt;Each prompt in the sequence has four parts:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;One job.&lt;/strong&gt; "Local storage layer." Not "storage, seed data, and the expense page."&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Exact names.&lt;/strong&gt; File paths, function names, storage keys, labels. The next prompt depends on them, so don't let the AI invent them.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No open choices.&lt;/strong&gt; If there are two reasonable ways to do something, pick one in the prompt.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A checkpoint you can see&lt;/strong&gt;, on any step where something can visibly break.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Here's a step in that shape:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Implement &lt;code&gt;lib/storage.ts&lt;/code&gt; with typed helpers: &lt;code&gt;loadExpenses&lt;/code&gt;, &lt;code&gt;saveExpenses&lt;/code&gt;, &lt;code&gt;loadCategories&lt;/code&gt;, &lt;code&gt;saveCategories&lt;/code&gt;, &lt;code&gt;loadBudgets&lt;/code&gt;, &lt;code&gt;saveBudgets&lt;/code&gt;. Use the keys &lt;code&gt;vibe-budget:expenses&lt;/code&gt;, &lt;code&gt;vibe-budget:categories&lt;/code&gt;, &lt;code&gt;vibe-budget:budgets&lt;/code&gt;. Every helper must return early if &lt;code&gt;typeof window === "undefined"&lt;/code&gt;. If data is missing, invalid JSON, or not an array, return &lt;code&gt;[]&lt;/code&gt; and do not crash.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;CHECKPOINT:&lt;/strong&gt; &lt;code&gt;npx tsc --noEmit&lt;/code&gt; shows no errors.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The vague version ("use distinct keys prefixed with &lt;code&gt;vibe-budget:&lt;/code&gt;", "handle SSR safely") also works, but leaves decisions that later prompts have to guess.&lt;/p&gt;

&lt;p&gt;Ahead of the steps, put a few &lt;strong&gt;house rules&lt;/strong&gt; that apply to every prompt. For this app there are three:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Every page that reads data is a Client Component (&lt;code&gt;"use client"&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Never read &lt;code&gt;localStorage&lt;/code&gt; or call &lt;code&gt;new Date()&lt;/code&gt; while rendering. Start state empty and load it in &lt;code&gt;useEffect&lt;/code&gt; or an event handler.&lt;/li&gt;
&lt;li&gt;Store dates as local &lt;code&gt;YYYY-MM-DD&lt;/code&gt; and months as &lt;code&gt;YYYY-MM&lt;/code&gt;. Never use &lt;code&gt;toISOString()&lt;/code&gt; for "today."&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Rule 2 avoids a group of Next.js 16 build and lint failures, covered in the &lt;a href="https://dev.to/shipinanhour/nextjs-16-tailwind-v4-5-traps-ai-coding-assistants-keep-hitting-and-the-prompts-that-fix-them-3ioc"&gt;previous post&lt;/a&gt;. Rule 3 gets its own section below.&lt;/p&gt;




&lt;h2&gt;
  
  
  7 ambiguous prompt lines that broke the test run
&lt;/h2&gt;

&lt;p&gt;For each one: the original wording, what went wrong when it was read literally, and the rewrite.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. "Use the latest stable create-next-app defaults"
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;What happened:&lt;/strong&gt; &lt;code&gt;create-next-app&lt;/code&gt; asks a series of questions (ESLint or Biome, React Compiler, &lt;code&gt;src/&lt;/code&gt;, import alias, AGENTS.md…). The prompt answered none of them.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Rewrite:&lt;/strong&gt; give the exact command.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npx create-next-app@latest vibe-budget &lt;span class="nt"&gt;--ts&lt;/span&gt; &lt;span class="nt"&gt;--tailwind&lt;/span&gt; &lt;span class="nt"&gt;--eslint&lt;/span&gt; &lt;span class="nt"&gt;--app&lt;/span&gt; &lt;span class="nt"&gt;--use-npm&lt;/span&gt; &lt;span class="nt"&gt;--yes&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With 16.4.2 this runs without asking anything. Pass the explicit flags as well as &lt;code&gt;--yes&lt;/code&gt;. According to the CLI docs, &lt;code&gt;--yes&lt;/code&gt; means "use previous preferences or defaults," so on a machine with saved preferences, &lt;code&gt;--yes&lt;/code&gt; alone might not give you the defaults you expect.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. "Under &lt;code&gt;src/&lt;/code&gt; (or the project's app root)"
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;What happened:&lt;/strong&gt; the default scaffold has no &lt;code&gt;src/&lt;/code&gt;. So where does &lt;code&gt;lib/&lt;/code&gt; go, and is the import &lt;code&gt;@/lib/...&lt;/code&gt; or &lt;code&gt;@/src/lib/...&lt;/code&gt;?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Rewrite:&lt;/strong&gt; "Use this structure at the project root (no &lt;code&gt;src/&lt;/code&gt; folder) … Import with the &lt;code&gt;@/&lt;/code&gt; alias, e.g. &lt;code&gt;import { loadExpenses } from "@/lib/storage"&lt;/code&gt;." Showing one import line settles the question.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. "Provide &lt;code&gt;ensureSeedData()&lt;/code&gt;, called once from the client layout or home page"
&lt;/h3&gt;

&lt;p&gt;This was the clearest example of a prompt that looked fine and caused a bug three steps later.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What happened:&lt;/strong&gt; the root layout is a Server Component, so "home page" was the only place it could go. Then, in a fresh browser, opening &lt;code&gt;/expenses&lt;/code&gt; first showed an &lt;strong&gt;empty category dropdown&lt;/strong&gt;, because the seed data only ran on &lt;code&gt;/&lt;/code&gt;. The add-expense form was useless.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Rewrite:&lt;/strong&gt; make the seed function safe to call repeatedly, and require every page to call it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/seed.ts&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;ensureSeedData&lt;/span&gt;&lt;span class="p"&gt;():&lt;/span&gt; &lt;span class="k"&gt;void&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="nb"&gt;window&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;undefined&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;loadCategories&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// safe to call on every page&lt;/span&gt;
  &lt;span class="nf"&gt;saveCategories&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;DEFAULTS&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(([&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;color&lt;/span&gt;&lt;span class="p"&gt;])&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt; &lt;span class="nx"&gt;name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;color&lt;/span&gt; &lt;span class="p"&gt;})));&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;blockquote&gt;
&lt;p&gt;Rule for all later prompts: every page calls &lt;code&gt;ensureSeedData()&lt;/code&gt; inside its &lt;code&gt;useEffect&lt;/code&gt; &lt;strong&gt;before&lt;/strong&gt; loading categories, so the app works no matter which page the user opens first.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The checkpoint changed too. The original was "you can add an expense and see it after refresh," which passes as long as you started on the home page. The new one targets the bug directly:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;CHECKPOINT:&lt;/strong&gt; In a fresh private window, open &lt;code&gt;/expenses&lt;/code&gt; directly. The category select lists 8 categories.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3&gt;
  
  
  4. "date ISO string"
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;What happened:&lt;/strong&gt; the type said "ISO string," and the form used &lt;code&gt;&amp;lt;input type="date"&amp;gt;&lt;/code&gt;. Those don't match. A date input's value is always &lt;code&gt;yyyy-mm-dd&lt;/code&gt; (MDN), while "ISO string" pushes the AI toward &lt;code&gt;new Date().toISOString()&lt;/code&gt;, which is in &lt;strong&gt;UTC&lt;/strong&gt;. Quick check in Node:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nv"&gt;$ TZ&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;Asia/Taipei node &lt;span class="nt"&gt;-e&lt;/span&gt; &lt;span class="s1"&gt;'const d=new Date(2026,9,19,7,30); console.log(d.toISOString().slice(0,10))'&lt;/span&gt;
2026-10-18   &lt;span class="c"&gt;# it's Oct 19 locally&lt;/span&gt;
&lt;span class="nv"&gt;$ TZ&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;America/Los_Angeles node &lt;span class="nt"&gt;-e&lt;/span&gt; &lt;span class="s1"&gt;'const d=new Date(2026,9,19,20,30); console.log(d.toISOString().slice(0,10))'&lt;/span&gt;
2026-10-20   &lt;span class="c"&gt;# it's Oct 19 locally&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The reverse also happens: &lt;code&gt;new Date("2026-10-19")&lt;/code&gt; is parsed as UTC midnight, so in New York it's the evening of Oct 18.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Rewrite:&lt;/strong&gt; name the format and the helper:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/dates.ts&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;todayISO&lt;/span&gt;&lt;span class="p"&gt;():&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;d&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;m&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;String&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getMonth&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;padStart&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;0&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;day&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;String&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getDate&lt;/span&gt;&lt;span class="p"&gt;()).&lt;/span&gt;&lt;span class="nf"&gt;padStart&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;0&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getFullYear&lt;/span&gt;&lt;span class="p"&gt;()}&lt;/span&gt;&lt;span class="s2"&gt;-&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;m&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;-&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;day&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;currentMonth&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;todayISO&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nf"&gt;slice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;7&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then compare dates as strings: &lt;code&gt;expense.date.startsWith(month)&lt;/code&gt;. For month arithmetic, use &lt;code&gt;new Date(year, monthIndex + delta, 1)&lt;/code&gt;. That form works in local time, and overflow carries into the next year, so December + 1 becomes January.&lt;/p&gt;

&lt;h3&gt;
  
  
  5. "Block delete or reassign to Other — pick one approach"
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;What happened:&lt;/strong&gt; either choice works until you look at the edge cases. Can "Other" itself be deleted? What happens to the deleted category's &lt;strong&gt;budgets&lt;/strong&gt;? In the test run, leftover budgets for a deleted category stayed in storage and &lt;strong&gt;inflated the Summary page's "sum of limits."&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Rewrite:&lt;/strong&gt; decide every branch:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Delete: confirm first, then move every expense in that category to "Other", delete any budgets for that category, then delete the category. "Other" itself cannot be deleted. Put this rule in a code comment.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;"Pick one" is fine in a conversation. In a prompt sequence it isn't, because later prompts can't know which option the AI picked.&lt;/p&gt;

&lt;h3&gt;
  
  
  6. "Reject non-numeric input"
&lt;/h3&gt;

&lt;p&gt;Every vibe-coded money form ends up with &lt;code&gt;NaN&lt;/code&gt; or &lt;code&gt;$12.3456&lt;/code&gt; somewhere. Don't just ask the AI to "validate amounts." Give it the function signature and the rules:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Create &lt;code&gt;lib/money.ts&lt;/code&gt; with &lt;code&gt;formatMoney(amount: number)&lt;/code&gt; and &lt;code&gt;parseAmount(input: string): number | null&lt;/code&gt; that accepts only plain positive numbers like &lt;code&gt;12&lt;/code&gt; or &lt;code&gt;12.5&lt;/code&gt;, rounds to 2 decimals, and returns &lt;code&gt;null&lt;/code&gt; otherwise. Use it in every form.&lt;br&gt;
&lt;/p&gt;
&lt;/blockquote&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;round2&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;n&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;round&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;n&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;parseAmount&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="sr"&gt;/^&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;*&lt;/span&gt;&lt;span class="se"&gt;\d&lt;/span&gt;&lt;span class="sr"&gt;+&lt;/span&gt;&lt;span class="se"&gt;(\.\d&lt;/span&gt;&lt;span class="sr"&gt;+&lt;/span&gt;&lt;span class="se"&gt;)?\s&lt;/span&gt;&lt;span class="sr"&gt;*$/&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;input&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;n&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;round2&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;input&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;n&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;n&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;"12.345"&lt;/code&gt; → &lt;code&gt;12.35&lt;/code&gt;. &lt;code&gt;"abc"&lt;/code&gt;, &lt;code&gt;""&lt;/code&gt;, &lt;code&gt;"-5"&lt;/code&gt;, &lt;code&gt;"0"&lt;/code&gt;, &lt;code&gt;"1,000"&lt;/code&gt;, &lt;code&gt;"$12"&lt;/code&gt; → &lt;code&gt;null&lt;/code&gt;. Store numbers; format only when displaying.&lt;/p&gt;

&lt;h3&gt;
  
  
  7. "Add a realistic week of demo data for the current month"
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;What happened:&lt;/strong&gt; on the 1st through the 6th of a month, "the last 7 days" goes back into the previous month. The demo data then ends up partly outside the month the budgets and summary are showing.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Rewrite:&lt;/strong&gt; "Keep every date inside the current month (if today is early in the month, use the 1st instead of going back into last month)."&lt;/p&gt;

&lt;p&gt;Two smaller ones: a prompt titled "Home redirect" whose body asked for a home &lt;em&gt;page&lt;/em&gt; (title and body must agree), and a checkpoint saying "all four/five routes render" (give the exact number).&lt;/p&gt;




&lt;h2&gt;
  
  
  Checkpoints: make them try to break things
&lt;/h2&gt;

&lt;p&gt;A checkpoint that only proves the happy path is decoration:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Weak&lt;/th&gt;
&lt;th&gt;Strong&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Dev server runs&lt;/td&gt;
&lt;td&gt;Open &lt;code&gt;localhost:3000&lt;/code&gt;: title on a light background, no errors in the console&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Helpers compile&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;npx tsc --noEmit&lt;/code&gt; shows no errors&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Adding an expense works&lt;/td&gt;
&lt;td&gt;Fresh private window, open &lt;code&gt;/expenses&lt;/code&gt; &lt;strong&gt;directly&lt;/strong&gt;, 8 categories in the select&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Budget bar updates&lt;/td&gt;
&lt;td&gt;Food budget 50, add $40 → amber bar, add $20 more → red bar&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Export works&lt;/td&gt;
&lt;td&gt;Export → DevTools "Clear site data" → refresh → import → everything is back&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The most important checkpoint is the final one. The original QA prompt was a manual click-through and never ran the build. In the test run, &lt;code&gt;npm run lint&lt;/code&gt; and &lt;code&gt;npm run build&lt;/code&gt; were exactly where the app broke. So the final prompt now starts with:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Run &lt;code&gt;npm run lint&lt;/code&gt; and &lt;code&gt;npm run build&lt;/code&gt; and fix every error. Then walk through: add/edit/delete an expense; filters; category add/rename/delete; budgets and bar colors; summary and month buttons; export/import; a 375px-wide window; a hard refresh on every page.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;After the fixes, the finished app passed &lt;code&gt;tsc&lt;/code&gt;, lint (0 problems), the build, and a 32-step Playwright smoke test.&lt;/p&gt;




&lt;h2&gt;
  
  
  Put the house rules where the assistant reads them every time
&lt;/h2&gt;

&lt;p&gt;Assistants don't remember earlier prompts reliably. Cursor's docs put it simply: "Large language models don't retain memory between completions." So don't just put the house rules at the top of prompt 1. Put them in a file the assistant loads on every request:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;AGENTS.md&lt;/code&gt; at the project root. Cursor reads it. &lt;code&gt;create-next-app&lt;/code&gt; 16.4 already generates one, with a block telling agents to read the docs bundled in &lt;code&gt;node_modules/next/dist/docs/&lt;/code&gt;. Add your rules below that block.&lt;/li&gt;
&lt;li&gt;Or &lt;code&gt;.cursor/rules/house-rules.mdc&lt;/code&gt; with &lt;code&gt;alwaysApply: true&lt;/code&gt; in its front matter.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Keep it short: the house rules, the folder/alias rule, the storage-key prefix, and "finish with &lt;code&gt;npm run lint &amp;amp;&amp;amp; npm run build&lt;/code&gt;."&lt;/p&gt;




&lt;h2&gt;
  
  
  When a checkpoint fails
&lt;/h2&gt;

&lt;p&gt;Don't start the next prompt. Paste &lt;strong&gt;one&lt;/strong&gt; narrow fix prompt that names the symptom, check it, then &lt;strong&gt;re-run the checkpoint that failed&lt;/strong&gt; before moving on. For the empty dropdown, this was enough:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Category select is empty when I open &lt;code&gt;/expenses&lt;/code&gt; directly in a fresh browser. Call &lt;code&gt;ensureSeedData()&lt;/code&gt; at the start of every page's &lt;code&gt;useEffect&lt;/code&gt;, before loading categories. Don't change types or storage keys.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;One more lesson: a fix prompt can sound right and still miss. In the test run, the generic "hydration / render &lt;code&gt;Loading…&lt;/code&gt; until mounted" rescue &lt;strong&gt;did not&lt;/strong&gt; fix a &lt;code&gt;new Date()&lt;/code&gt; build failure. The real cause was a config default. Run the checkpoint again after every fix, even when the fix sounds obviously right.&lt;/p&gt;

&lt;p&gt;If the assistant tries to switch stacks or "just add a database" to get unstuck, say no and keep it on the plan.&lt;/p&gt;




&lt;h2&gt;
  
  
  Recap
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;One job per prompt, with exact file, function, and key names.&lt;/li&gt;
&lt;li&gt;No "pick one" or "or": decide it in the prompt.&lt;/li&gt;
&lt;li&gt;Checkpoints that try to break things (fresh browser, direct URL, edge values), plus &lt;code&gt;npm run lint &amp;amp;&amp;amp; npm run build&lt;/code&gt; at the end.&lt;/li&gt;
&lt;li&gt;House rules in &lt;code&gt;AGENTS.md&lt;/code&gt; or an always-on Cursor rule, not just in prompt 1.&lt;/li&gt;
&lt;li&gt;When something fails, use one narrow fix, re-run the checkpoint, then continue.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you want to try this on the budget app, the first five prompts of the sequence (scaffold, folder structure and types, storage layer, seed data, app shell, with their checkpoints) are available as a &lt;a href="https://shipinanhour.gumroad.com/l/ckmqef" rel="noopener noreferrer"&gt;free sample of the first five prompts&lt;/a&gt;.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>nextjs</category>
      <category>webdev</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>Next.js 16 + Tailwind v4: 5 traps AI coding assistants keep hitting (and the prompts that fix them)</title>
      <dc:creator>ShipInAnHour</dc:creator>
      <pubDate>Mon, 19 Oct 2026 04:08:16 +0000</pubDate>
      <link>https://dev.to/shipinanhour/nextjs-16-tailwind-v4-5-traps-ai-coding-assistants-keep-hitting-and-the-prompts-that-fix-them-3ioc</link>
      <guid>https://dev.to/shipinanhour/nextjs-16-tailwind-v4-5-traps-ai-coding-assistants-keep-hitting-and-the-prompts-that-fix-them-3ioc</guid>
      <description>&lt;p&gt;A fresh &lt;code&gt;create-next-app&lt;/code&gt; in late 2026 gives you Next.js 16 and Tailwind CSS v4. Most AI coding assistants learned on years of Next 13–15 and Tailwind v3 code. That gap produces the same handful of failures again and again, and they often show up only at &lt;code&gt;npm run build&lt;/code&gt;, or only on a laptop set to dark mode.&lt;/p&gt;

&lt;p&gt;Below are five of them. For each one you get the symptom (with the exact error text where there is one), why the assistant gets it wrong, the fix, and a short prompt you can paste into Cursor, Claude Code, or ChatGPT.&lt;/p&gt;

&lt;p&gt;Versions used: &lt;code&gt;create-next-app&lt;/code&gt; 16.4.2 (Next.js 16.4.2, React 19.3), Tailwind CSS 4.3, Node 20.&lt;/p&gt;




&lt;h2&gt;
  
  
  Trap 1: &lt;code&gt;npm run build&lt;/code&gt; fails on a brand-new app (&lt;code&gt;cacheComponents&lt;/code&gt;)
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Symptom.&lt;/strong&gt; &lt;code&gt;npm run dev&lt;/code&gt; looks fine, then the build fails with one of these:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Route segment config "dynamic" is not compatible with `nextConfig.cacheComponents`. Please remove it.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Route "/expenses": Next.js encountered the unstable value `new Date()` in a Client Component.

This value would be evaluated during the prerender, instead of recomputed on each visit.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Why the assistant gets it wrong.&lt;/strong&gt; With its recommended defaults (&lt;code&gt;--yes&lt;/code&gt;), &lt;code&gt;create-next-app&lt;/code&gt; 16.4 now writes this into &lt;code&gt;next.config.ts&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;nextConfig&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;NextConfig&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;cacheComponents&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;partialPrefetching&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;turbopack&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="cm"&gt;/* … Tailwind CSS loader … */&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The Next.js caching docs say it directly: new App Router apps made with the recommended defaults "already have Cache Components and Partial Prefetching enabled." The assistant doesn't know this. It reaches for the Next 13–15 habit of &lt;code&gt;export const dynamic = "force-dynamic"&lt;/code&gt;, which Cache Components rejects, or it puts &lt;code&gt;new Date()&lt;/code&gt; in a component that now gets prerendered.&lt;/p&gt;

&lt;p&gt;In our test runs, both of our sample apps failed &lt;code&gt;npm run build&lt;/code&gt; at this point. One failed on the &lt;code&gt;dynamic&lt;/code&gt; export and one on a &lt;code&gt;new Date()&lt;/code&gt; default for a date input. The fix that worked was removing the two config lines.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Fix, option A: opt out&lt;/strong&gt; (fine for a localStorage app or a small landing page):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// next.config.ts&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;nextConfig&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;NextConfig&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="c1"&gt;// removed: cacheComponents: true,&lt;/span&gt;
  &lt;span class="c1"&gt;// removed: partialPrefetching: true,&lt;/span&gt;
  &lt;span class="na"&gt;turbopack&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="cm"&gt;/* keep this block: it loads Tailwind */&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You can also scaffold without it. In our check, the 16.4.2 CLI accepted &lt;code&gt;--no-cache-components&lt;/code&gt; even though &lt;code&gt;--help&lt;/code&gt; doesn't list it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npx create-next-app@latest my-app &lt;span class="nt"&gt;--ts&lt;/span&gt; &lt;span class="nt"&gt;--tailwind&lt;/span&gt; &lt;span class="nt"&gt;--eslint&lt;/span&gt; &lt;span class="nt"&gt;--app&lt;/span&gt; &lt;span class="nt"&gt;--use-npm&lt;/span&gt; &lt;span class="nt"&gt;--yes&lt;/span&gt; &lt;span class="nt"&gt;--no-cache-components&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;After either change, delete &lt;code&gt;.next/&lt;/code&gt; and rebuild.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Fix, option B: keep Cache Components and do it its way.&lt;/strong&gt; Remove the &lt;code&gt;dynamic&lt;/code&gt; export. The migration guide says to drop &lt;code&gt;force-dynamic&lt;/code&gt;, because uncached work already runs at request time. Then put the request-time part behind &lt;code&gt;&amp;lt;Suspense&amp;gt;&lt;/code&gt; and &lt;code&gt;await connection()&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;Suspense&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;react&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;connection&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;next/server&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;SignupCount&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;connection&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt; &lt;span class="c1"&gt;// render at request time&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;total&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;getTotal&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;p&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="nx"&gt;total&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt; people joined&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;p&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;Page&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Suspense&lt;/span&gt; &lt;span class="na"&gt;fallback&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;p&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;…&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;p&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
      &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;SignupCount&lt;/span&gt; &lt;span class="p"&gt;/&amp;gt;&lt;/span&gt;
    &lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nc"&gt;Suspense&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Prompt:&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;code&gt;npm run build&lt;/code&gt; fails with "Route segment config "dynamic" is not compatible with nextConfig.cacheComponents" or "encountered the unstable value &lt;code&gt;new Date()&lt;/code&gt;". This is Next.js 16, and &lt;code&gt;create-next-app&lt;/code&gt; enabled &lt;code&gt;cacheComponents&lt;/code&gt; by default. Open &lt;code&gt;next.config.ts&lt;/code&gt;, remove &lt;code&gt;cacheComponents: true&lt;/code&gt; and &lt;code&gt;partialPrefetching: true&lt;/code&gt;, and keep the &lt;code&gt;turbopack&lt;/code&gt; block. Make sure no component calls &lt;code&gt;new Date()&lt;/code&gt;, &lt;code&gt;Date.now()&lt;/code&gt;, or &lt;code&gt;Math.random()&lt;/code&gt; while rendering. Delete &lt;code&gt;.next/&lt;/code&gt; and re-run the build until it passes.&lt;/p&gt;
&lt;/blockquote&gt;




&lt;h2&gt;
  
  
  Trap 2: &lt;code&gt;new Date()&lt;/code&gt; and &lt;code&gt;localStorage&lt;/code&gt; during render (and the lint errors after you fix it)
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Symptom.&lt;/strong&gt; Hydration warnings. Data that flashes and disappears. A "today" date that is one day off. A default month that is frozen at whatever month you ran the build in. Once you fix those, &lt;code&gt;npm run lint&lt;/code&gt; fails with &lt;code&gt;react-hooks/set-state-in-effect&lt;/code&gt; or &lt;code&gt;react-hooks/purity&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why the assistant gets it wrong.&lt;/strong&gt; Its go-to patterns are &lt;code&gt;useState(new Date())&lt;/code&gt;, &lt;code&gt;useState(() =&amp;gt; JSON.parse(localStorage.getItem(...)))&lt;/code&gt;, and &lt;code&gt;new Date().toISOString().slice(0, 10)&lt;/code&gt; for "today." All three either run during server prerendering or quietly use UTC. A common reflex is a &lt;code&gt;mounted&lt;/code&gt; flag that renders "Loading…" until the effect runs. In our test runs that didn't help. The &lt;code&gt;useState&lt;/code&gt; initializers still ran during prerender, and the build still failed.&lt;/p&gt;

&lt;p&gt;Two more things from the test runs. A month default set during render ended up baked into the static HTML. Then the standard fix (empty state, load in &lt;code&gt;useEffect&lt;/code&gt;) produced &lt;strong&gt;10&lt;/strong&gt; &lt;code&gt;react-hooks/set-state-in-effect&lt;/code&gt; errors under the ESLint config that Next 16 ships, which includes eslint-plugin-react-hooks 7.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Fix.&lt;/strong&gt; Start with empty state and read browser values in an effect or an event handler. That is also the "[defer]" option Next's own error message suggests.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;use client&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;expenses&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;setExpenses&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;useState&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;Expense&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;([]);&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;date&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;setDate&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;useState&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;""&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="nf"&gt;useEffect&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;setExpenses&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;loadExpenses&lt;/span&gt;&lt;span class="p"&gt;());&lt;/span&gt; &lt;span class="c1"&gt;// reads localStorage on the client only&lt;/span&gt;
  &lt;span class="nf"&gt;setDate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;todayISO&lt;/span&gt;&lt;span class="p"&gt;());&lt;/span&gt;
&lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="p"&gt;[]);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Build "today" from local time, not &lt;code&gt;toISOString()&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;todayISO&lt;/span&gt;&lt;span class="p"&gt;():&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;d&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;m&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;String&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getMonth&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;padStart&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;0&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;day&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;String&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getDate&lt;/span&gt;&lt;span class="p"&gt;()).&lt;/span&gt;&lt;span class="nf"&gt;padStart&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;0&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getFullYear&lt;/span&gt;&lt;span class="p"&gt;()}&lt;/span&gt;&lt;span class="s2"&gt;-&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;m&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;-&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;day&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For the lint rule you have two honest options. If loading from &lt;code&gt;localStorage&lt;/code&gt; once on mount is intentional, turn off just that rule and leave a comment saying why:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// eslint.config.mjs&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="c1"&gt;// Loading from localStorage once on mount is intentional in this app.&lt;/span&gt;
  &lt;span class="nl"&gt;rules&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;react-hooks/set-state-in-effect&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;off&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
&lt;span class="p"&gt;},&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Or design the effect away: derive the value, let CSS handle it (see Trap 4), or do the work in a handler. For &lt;code&gt;react-hooks/purity&lt;/code&gt;, take &lt;code&gt;Date.now()&lt;/code&gt; out of the component body and compute time-based values on the server, in a Route Handler or a server-only &lt;code&gt;lib/&lt;/code&gt; helper.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Prompt:&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;House rule for this project: never read &lt;code&gt;localStorage&lt;/code&gt; or call &lt;code&gt;new Date()&lt;/code&gt;/&lt;code&gt;Date.now()&lt;/code&gt; during render or in a &lt;code&gt;useState(...)&lt;/code&gt; initial value. Start state empty (&lt;code&gt;[]&lt;/code&gt; / &lt;code&gt;""&lt;/code&gt;) and load it in &lt;code&gt;useEffect&lt;/code&gt; or in a click/submit handler. Store dates as local &lt;code&gt;YYYY-MM-DD&lt;/code&gt; and never use &lt;code&gt;toISOString()&lt;/code&gt; for "today." A mounted-flag "Loading…" gate is not enough on its own. Then run &lt;code&gt;npm run lint&lt;/code&gt; and &lt;code&gt;npm run build&lt;/code&gt; and fix what they report.&lt;/p&gt;
&lt;/blockquote&gt;




&lt;h2&gt;
  
  
  Trap 3: The scaffold's CSS makes your app unreadable in dark mode, and borders look black
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Symptom.&lt;/strong&gt; On a computer set to dark mode, the page is near-black with light text, and your new &lt;code&gt;bg-white&lt;/code&gt; cards show light text on white. Every &lt;code&gt;border&lt;/code&gt; looks dark.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why the assistant gets it wrong.&lt;/strong&gt; It builds on top of the template's &lt;code&gt;app/globals.css&lt;/code&gt; without reading it. In 16.4.2 that file includes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="k"&gt;@media&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;prefers-color-scheme&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;dark&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nd"&gt;:root&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="py"&gt;--background&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;#0a0a0a&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="py"&gt;--foreground&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;#ededed&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="nt"&gt;body&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;background&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;var&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;--background&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nl"&gt;color&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;var&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;--foreground&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On top of that, Tailwind v4 changed the default border color from &lt;code&gt;gray-200&lt;/code&gt; to &lt;code&gt;currentColor&lt;/code&gt; (see the upgrade guide's "Default border color" section). v3-trained assistants assume borders are a soft gray. In our test runs, both problems showed up in the final QA pass: the UI was unreadable on a dark-mode OS, and the borders defaulted to black.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Fix.&lt;/strong&gt; Replace &lt;code&gt;globals.css&lt;/code&gt; with a minimal version and set colors on &lt;code&gt;&amp;lt;body&amp;gt;&lt;/code&gt; yourself:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="k"&gt;@import&lt;/span&gt; &lt;span class="s1"&gt;"tailwindcss"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;@layer&lt;/span&gt; &lt;span class="n"&gt;base&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="o"&gt;*,&lt;/span&gt; &lt;span class="nd"&gt;::before&lt;/span&gt;&lt;span class="o"&gt;,&lt;/span&gt; &lt;span class="nd"&gt;::after&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;border-color&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;var&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;--color-neutral-200&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;body&lt;/span&gt; &lt;span class="na"&gt;className&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"bg-neutral-50 text-neutral-900"&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Prompt:&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Text is unreadable on a computer set to dark mode, and all borders look black. In &lt;code&gt;app/globals.css&lt;/code&gt;, remove the default &lt;code&gt;:root&lt;/code&gt;, &lt;code&gt;prefers-color-scheme&lt;/code&gt;, and &lt;code&gt;body&lt;/code&gt; rules. Keep &lt;code&gt;@import "tailwindcss";&lt;/code&gt; and add &lt;code&gt;@layer base { *, ::before, ::after { border-color: var(--color-neutral-200); } }&lt;/code&gt;. Put &lt;code&gt;bg-neutral-50 text-neutral-900&lt;/code&gt; on &lt;code&gt;&amp;lt;body&amp;gt;&lt;/code&gt;. Tailwind only, no UI library.&lt;/p&gt;
&lt;/blockquote&gt;




&lt;h2&gt;
  
  
  Trap 4: The dark-mode toggle does nothing
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Symptom.&lt;/strong&gt; You click the toggle and nothing changes, or the page only goes dark when the OS is already dark. After a refresh you get a white flash.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why the assistant gets it wrong.&lt;/strong&gt; In Tailwind v3 you set &lt;code&gt;darkMode: "class"&lt;/code&gt; in &lt;code&gt;tailwind.config.js&lt;/code&gt;. In v4, &lt;code&gt;dark:&lt;/code&gt; follows &lt;code&gt;prefers-color-scheme&lt;/code&gt; by default, and class-based toggling is configured in CSS. Assistants still write the v3 config, or toggle the class on &lt;code&gt;&amp;lt;body&amp;gt;&lt;/code&gt; instead of &lt;code&gt;&amp;lt;html&amp;gt;&lt;/code&gt;. When we compiled Tailwind 4.3 without the override, &lt;code&gt;dark:&lt;/code&gt; utilities came out inside a &lt;code&gt;prefers-color-scheme&lt;/code&gt; media query, so a &lt;code&gt;.dark&lt;/code&gt; class had no effect. Our budget-app test run hit exactly this: the toggle did nothing until we added &lt;code&gt;@custom-variant dark&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Fix.&lt;/strong&gt; This one line is from the Tailwind dark-mode docs:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="k"&gt;@import&lt;/span&gt; &lt;span class="s1"&gt;"tailwindcss"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;@custom-variant&lt;/span&gt; &lt;span class="n"&gt;dark&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="err"&gt;&amp;amp;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;where&lt;/span&gt;&lt;span class="p"&gt;(.&lt;/span&gt;&lt;span class="n"&gt;dark&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;dark&lt;/span&gt; &lt;span class="err"&gt;*&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Toggle the class on &lt;code&gt;document.documentElement&lt;/code&gt;. Apply the saved theme before first paint with a small inline script, and let CSS pick the icon so there's no React state to mismatch on hydration:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/layout.tsx&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;themeScript&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;`try{if(localStorage.getItem("theme")==="dark")document.documentElement.classList.add("dark")}catch(e){}`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;html&lt;/span&gt; &lt;span class="na"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"en"&lt;/span&gt; &lt;span class="na"&gt;suppressHydrationWarning&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;head&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
    &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;script&lt;/span&gt; &lt;span class="na"&gt;dangerouslySetInnerHTML&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;__html&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;themeScript&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt; &lt;span class="p"&gt;/&amp;gt;&lt;/span&gt;
  &lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;head&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
  …
&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;html&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="c1"&gt;// components/ThemeToggle.tsx&lt;/span&gt;
&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;use client&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;ThemeToggle&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;toggle&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;isDark&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;documentElement&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;classList&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toggle&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;dark&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;localStorage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setItem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;theme&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;isDark&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;dark&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;light&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;return &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;button&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"button"&lt;/span&gt; &lt;span class="na"&gt;onClick&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="nx"&gt;toggle&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt; &lt;span class="na"&gt;aria-label&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"Toggle dark mode"&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
      &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;span&lt;/span&gt; &lt;span class="na"&gt;className&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"dark:hidden"&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;🌙&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;span&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
      &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;span&lt;/span&gt; &lt;span class="na"&gt;className&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"hidden dark:inline"&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;☀️&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;span&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
    &lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;button&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The CSS-picked icon also avoids the &lt;code&gt;set-state-in-effect&lt;/code&gt; lint error from Trap 2.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Prompt:&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;The dark-mode toggle does nothing. This is Tailwind v4: there is no &lt;code&gt;darkMode&lt;/code&gt; setting in a JS config. Add &lt;code&gt;@custom-variant dark (&amp;amp;:where(.dark, .dark *));&lt;/code&gt; to &lt;code&gt;globals.css&lt;/code&gt;. Toggle the &lt;code&gt;dark&lt;/code&gt; class on &lt;code&gt;document.documentElement&lt;/code&gt;, not &lt;code&gt;&amp;lt;body&amp;gt;&lt;/code&gt;. Add an inline &lt;code&gt;&amp;lt;head&amp;gt;&lt;/code&gt; script that applies the saved theme before paint, and add &lt;code&gt;suppressHydrationWarning&lt;/code&gt; on &lt;code&gt;&amp;lt;html&amp;gt;&lt;/code&gt;. Choose the icon with &lt;code&gt;dark:hidden&lt;/code&gt; / &lt;code&gt;hidden dark:inline&lt;/code&gt; instead of React state. Then add missing &lt;code&gt;dark:&lt;/code&gt; classes to cards, inputs, and the header.&lt;/p&gt;
&lt;/blockquote&gt;




&lt;h2&gt;
  
  
  Trap 5: Tailwind v3 habits (gradients, renamed utilities, the JS config)
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Symptom.&lt;/strong&gt; Shadows, corners, and blurs look slightly off. A custom brand color or gradient you asked for doesn't appear. The assistant creates a &lt;code&gt;tailwind.config.js&lt;/code&gt; or adds &lt;code&gt;@tailwind base;&lt;/code&gt; lines.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why the assistant gets it wrong.&lt;/strong&gt; Most of the Tailwind in its training data is v3. A common trap is a mix of v3 and v4 syntax:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;v3 habit&lt;/th&gt;
&lt;th&gt;v4&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;bg-gradient-to-r&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;bg-linear-to-r&lt;/code&gt; (renamed in v4.0)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;shadow-sm&lt;/code&gt; / &lt;code&gt;shadow&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;shadow-xs&lt;/code&gt; / &lt;code&gt;shadow-sm&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;rounded-sm&lt;/code&gt; / &lt;code&gt;rounded&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;rounded-xs&lt;/code&gt; / &lt;code&gt;rounded-sm&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;outline-none&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;outline-hidden&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;ring&lt;/code&gt; (3px)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ring-3&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@tailwind base; …&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;@import "tailwindcss";&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;tailwind.config.js&lt;/code&gt; theme&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;@theme { … }&lt;/code&gt; in CSS (JS config only loads via &lt;code&gt;@config&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;To be fair to &lt;code&gt;bg-gradient-to-r&lt;/code&gt;: when we compiled it with Tailwind 4.3, it still produced CSS as a legacy alias. The v4 docs only use &lt;code&gt;bg-linear-*&lt;/code&gt; (along with the new &lt;code&gt;bg-radial-*&lt;/code&gt; and &lt;code&gt;bg-conic-*&lt;/code&gt;), so standardize on that. A more common reason a gradient "doesn't show up" is that its colors are defined in a &lt;code&gt;tailwind.config.js&lt;/code&gt; that v4 never loads, so classes like &lt;code&gt;from-brand&lt;/code&gt; are never generated.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Fix.&lt;/strong&gt; Define custom colors in CSS:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="k"&gt;@import&lt;/span&gt; &lt;span class="s1"&gt;"tailwindcss"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;@theme&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="py"&gt;--color-brand&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;#7c3aed&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;span&lt;/span&gt; &lt;span class="na"&gt;className&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"bg-linear-to-r from-brand to-pink-600 bg-clip-text text-transparent"&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
  Ship it
&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;span&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Prompt:&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;This project uses Tailwind CSS v4, not v3. Don't create &lt;code&gt;tailwind.config.js&lt;/code&gt; or use &lt;code&gt;@tailwind&lt;/code&gt; directives. Theme values go in &lt;code&gt;@theme&lt;/code&gt; in &lt;code&gt;globals.css&lt;/code&gt;. Use v4 names: &lt;code&gt;bg-linear-to-*&lt;/code&gt; instead of &lt;code&gt;bg-gradient-to-*&lt;/code&gt;, &lt;code&gt;shadow-xs&lt;/code&gt;/&lt;code&gt;rounded-xs&lt;/code&gt; for the old &lt;code&gt;-sm&lt;/code&gt; sizes, &lt;code&gt;outline-hidden&lt;/code&gt; instead of &lt;code&gt;outline-none&lt;/code&gt;. Gradient text needs &lt;code&gt;bg-clip-text text-transparent&lt;/code&gt;. Search the codebase for v3 names and replace them.&lt;/p&gt;
&lt;/blockquote&gt;




&lt;h2&gt;
  
  
  Two smaller ones worth adding to your rules
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Internal links.&lt;/strong&gt; &lt;code&gt;&amp;lt;a href="/#features"&amp;gt;&lt;/code&gt; triggers &lt;code&gt;@next/next/no-html-link-for-pages&lt;/code&gt; in &lt;code&gt;npm run lint&lt;/code&gt;. In one test run it produced 6 errors. Use &lt;code&gt;&amp;lt;Link href="/#features"&amp;gt;&lt;/code&gt; from &lt;code&gt;next/link&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;searchParams&lt;/code&gt; is a Promise.&lt;/strong&gt; Type it as &lt;code&gt;searchParams: Promise&amp;lt;Record&amp;lt;string, string | string[] | undefined&amp;gt;&amp;gt;&lt;/code&gt; and &lt;code&gt;await&lt;/code&gt; it. Assistants still destructure it synchronously.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Make it stick
&lt;/h2&gt;

&lt;p&gt;Fixing these one at a time works, but the cheaper move is to stop the assistant from writing them in the first place. Put the house rules in a file your tool reads on every request: &lt;code&gt;AGENTS.md&lt;/code&gt; at the project root (Cursor reads it, and so do recent Claude Code versions when there's no &lt;code&gt;CLAUDE.md&lt;/code&gt;) or a &lt;code&gt;.cursor/rules/*.mdc&lt;/code&gt; file with &lt;code&gt;alwaysApply: true&lt;/code&gt;. &lt;code&gt;create-next-app&lt;/code&gt; 16.4 already generates an &lt;code&gt;AGENTS.md&lt;/code&gt; that tells agents to read the bundled docs in &lt;code&gt;node_modules/next/dist/docs/&lt;/code&gt;. Add your rules below that block. Then make &lt;code&gt;npm run lint &amp;amp;&amp;amp; npm run build&lt;/code&gt; the final checkpoint of every session, because that is where most of these failures show up.&lt;/p&gt;

&lt;p&gt;If you want these as ready-to-paste prompts, there's a free sample with four of them: the scaffold, the Tailwind v4 dark-mode toggle, and the build-failure and colors/gradients rescues. It's here: &lt;a href="https://shipinanhour.gumroad.com/l/qfzgeg" rel="noopener noreferrer"&gt;https://shipinanhour.gumroad.com/l/qfzgeg&lt;/a&gt;&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>tailwindcss</category>
      <category>ai</category>
      <category>webdev</category>
    </item>
  </channel>
</rss>
