Files
skills/public/deployment-netlify-deployment.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

537 lines
26 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>deployment-netlify-deployment</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/deployment-netlify-deployment.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/deployment-netlify-deployment">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/deployment-netlify-deployment.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>deployment-netlify-deployment</h1><p class="lede">Deploying static sites, JAMstack apps, or frontend frameworks to Netlify</p><h1>Netlify Deployment</h1>
<p><strong>Scope</strong>: Netlify site deployment, build settings, continuous deployment, and configuration <strong>Lines</strong>: ~320 <strong>Last Updated</strong>: 2025-10-18</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Deploying static sites, JAMstack apps, or frontend frameworks to Netlify</li><li>Setting up continuous deployment from Git repositories (GitHub, GitLab, Bitbucket)</li><li>Configuring build settings, environment variables, and deploy contexts</li><li>Managing branch deploys, deploy previews, and production deployments</li><li>Setting up redirects, rewrites, and custom headers</li><li>Working with monorepo deployments or multiple sites</li><li>Troubleshooting build failures or deployment issues</li></ul>
<h2>Core Concepts</h2>
<h3>Deployment Workflow</h3>
<p><strong>Git-based deployment</strong>:</p>
<ul><li>Push to Git → Netlify detects change → Build triggered → Site deployed</li><li>Automatic deploys for production branch (main/master)</li><li>Deploy previews for pull requests</li><li>Branch deploys for feature branches</li></ul>
<p><strong>Deploy contexts</strong>:</p>
<ul><li><strong>Production</strong>: Main branch deploys</li><li><strong>Deploy previews</strong>: Pull request deploys</li><li><strong>Branch deploys</strong>: Other branches (optional)</li><li>Each context can have different build commands and env vars</li></ul>
<h3>Build Configuration</h3>
<p><strong>Three ways to configure</strong>:</p>
<ol><li><strong>netlify.toml</strong> (recommended): Version-controlled config file</li><li><strong>Netlify UI</strong>: Web dashboard settings</li><li><strong>Netlify CLI</strong>: Command-line configuration</li></ol>
<p><strong>Build settings hierarchy</strong>:</p>
<ul><li>netlify.toml overrides UI settings</li><li>Environment variables from UI merge with file config</li><li>Deploy context settings override base settings</li></ul>
<h3>Site Configuration</h3>
<p><strong>Required settings</strong>:</p>
<ul><li><strong>Base directory</strong>: Root of your project (monorepos)</li><li><strong>Build command</strong>: Command to build your site</li><li><strong>Publish directory</strong>: Where build outputs files</li><li><strong>Functions directory</strong>: Serverless functions location (optional)</li></ul>
<p><strong>Framework detection</strong>:</p>
<ul><li>Netlify auto-detects popular frameworks (Next.js, Astro, SvelteKit, etc.)</li><li>Suggests default build commands and publish directories</li><li>Can override with custom settings</li></ul>
<hr>
<h2>Patterns</h2>
<h3>Pattern 1: Basic netlify.toml Configuration</h3>
<pre><code class="lang-toml"># netlify.toml - Basic configuration
[build]
# Base directory for monorepos
base = &quot;apps/web&quot;
# Build command
command = &quot;npm run build&quot;
# Publish directory (relative to base)
publish = &quot;dist&quot;
# Functions directory
functions = &quot;netlify/functions&quot;
# Environment variables (non-sensitive only)
[build.environment]
NODE_VERSION = &quot;20&quot;
NPM_FLAGS = &quot;--legacy-peer-deps&quot;
# Production context
[context.production]
command = &quot;npm run build:prod&quot;
[context.production.environment]
NEXT_PUBLIC_API_URL = &quot;https://api.example.com&quot;
# Deploy preview context (PRs)
[context.deploy-preview]
command = &quot;npm run build:preview&quot;
[context.deploy-preview.environment]
NEXT_PUBLIC_API_URL = &quot;https://preview-api.example.com&quot;
# Branch deploy context
[context.branch-deploy]
command = &quot;npm run build:dev&quot;</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>All production deployments (version control config)</li><li>Need different settings per deploy context</li><li>Monorepo projects with base directory</li></ul>
<h3>Pattern 2: Framework-Specific Configurations</h3>
<pre><code class="lang-toml"># Next.js App Router
[build]
command = &quot;npm run build&quot;
publish = &quot;.next&quot;
[build.environment]
NODE_VERSION = &quot;20&quot;
NEXT_PRIVATE_TARGET = &quot;server&quot;
# Astro
[build]
command = &quot;npm run build&quot;
publish = &quot;dist&quot;
# SvelteKit
[build]
command = &quot;npm run build&quot;
publish = &quot;build&quot;
[build.environment]
NODE_VERSION = &quot;20&quot;
# Vite + React
[build]
command = &quot;npm run build&quot;
publish = &quot;dist&quot;
# Nuxt 3
[build]
command = &quot;npm run build&quot;
publish = &quot;.output/public&quot;</code></pre>
<p><strong>Framework-specific gotchas</strong>:</p>
<ul><li>Next.js: Use <code>.next</code> for publish dir, Netlify handles server rendering</li><li>Astro: Ensure <code>output: &#x27;static&#x27;</code> or <code>&#x27;hybrid&#x27;</code> in astro.config</li><li>SvelteKit: Use <code>@sveltejs/adapter-netlify</code></li><li>Nuxt: Use <code>nuxt build</code> with Nitro preset</li></ul>
<h3>Pattern 3: Redirects and Rewrites</h3>
<pre><code class="lang-toml"># netlify.toml redirects
[[redirects]]
from = &quot;/old-path/*&quot;
to = &quot;/new-path/:splat&quot;
status = 301
force = true
[[redirects]]
from = &quot;/api/*&quot;
to = &quot;https://api.example.com/:splat&quot;
status = 200
force = true
[[redirects]]
from = &quot;/blog/:slug&quot;
to = &quot;/articles/:slug&quot;
status = 301
# SPA fallback (catch-all)
[[redirects]]
from = &quot;/*&quot;
to = &quot;/index.html&quot;
status = 200
# Redirect with query params
[[redirects]]
from = &quot;/search&quot;
to = &quot;/search-results?q=:query&quot;
query = {query = &quot;:query&quot;}
status = 301
# Proxy API requests (no CORS)
[[redirects]]
from = &quot;/api-proxy/*&quot;
to = &quot;https://external-api.com/:splat&quot;
status = 200
headers = {X-Custom-Header = &quot;value&quot;}</code></pre>
<p><strong>Alternative: _redirects file</strong>:</p>
<pre><code># public/_redirects
/old-path/* /new-path/:splat 301
/api/* https://api.example.com/:splat 200
/* /index.html 200</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Migrating old URLs (301 redirects)</li><li>SPA routing (200 rewrite to index.html)</li><li>Proxying external APIs (avoid CORS)</li><li>Redirect based on conditions</li></ul>
<h3>Pattern 4: Custom Headers</h3>
<pre><code class="lang-toml"># netlify.toml headers
[[headers]]
for = &quot;/*&quot;
[headers.values]
X-Frame-Options = &quot;DENY&quot;
X-XSS-Protection = &quot;1; mode=block&quot;
X-Content-Type-Options = &quot;nosniff&quot;
Referrer-Policy = &quot;strict-origin-when-cross-origin&quot;
Permissions-Policy = &quot;camera=(), microphone=(), geolocation=()&quot;
[[headers]]
for = &quot;/assets/*&quot;
[headers.values]
Cache-Control = &quot;public, max-age=31536000, immutable&quot;
[[headers]]
for = &quot;/*.js&quot;
[headers.values]
Cache-Control = &quot;public, max-age=31536000, immutable&quot;
[[headers]]
for = &quot;/*.css&quot;
[headers.values]
Cache-Control = &quot;public, max-age=31536000, immutable&quot;
[[headers]]
for = &quot;/api/*&quot;
[headers.values]
Access-Control-Allow-Origin = &quot;https://example.com&quot;
Access-Control-Allow-Methods = &quot;GET, POST, PUT, DELETE&quot;
Access-Control-Allow-Headers = &quot;Content-Type, Authorization&quot;
[[headers]]
for = &quot;/index.html&quot;
[headers.values]
Cache-Control = &quot;public, max-age=0, must-revalidate&quot;</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Security headers (all production sites)</li><li>Cache control for assets</li><li>CORS headers for API routes</li><li>CSP (Content Security Policy)</li></ul>
<h3>Pattern 5: Netlify CLI Deployment</h3>
<pre><code class="lang-bash"># Install Netlify CLI
npm install -g netlify-cli
# Login to Netlify
netlify login
# Initialize new site
netlify init
# Link existing site
netlify link
# Deploy to draft URL (preview)
netlify deploy
# Deploy to production
netlify deploy --prod
# Deploy specific directory
netlify deploy --dir=dist --prod
# Open site in browser
netlify open
# View deployment status
netlify status
# Stream build logs
netlify watch
# Run dev server with Netlify features
netlify dev</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Manual deployments (not Git-based)</li><li>Testing before production deploy</li><li>Local development with Netlify features</li><li>CI/CD pipeline deployments</li></ul>
<h3>Pattern 6: Environment Variables</h3>
<pre><code class="lang-bash"># Set via CLI
netlify env:set API_KEY &quot;secret-key&quot;
netlify env:set API_URL &quot;https://api.example.com&quot; --context production
netlify env:set DEBUG_MODE &quot;true&quot; --context deploy-preview
# List environment variables
netlify env:list
# Import from .env file
netlify env:import .env.production
# Remove environment variable
netlify env:unset API_KEY</code></pre>
<p><strong>In netlify.toml</strong> (non-sensitive only):</p>
<pre><code class="lang-toml">[build.environment]
NODE_VERSION = &quot;20&quot;
NEXT_PUBLIC_APP_NAME = &quot;My App&quot;
[context.production.environment]
NEXT_PUBLIC_API_URL = &quot;https://api.example.com&quot;
[context.deploy-preview.environment]
NEXT_PUBLIC_API_URL = &quot;https://preview-api.example.com&quot;</code></pre>
<p><strong>Best practices</strong>:</p>
<ul><li>Never commit sensitive keys to netlify.toml</li><li>Use Netlify UI or CLI for secrets</li><li>Prefix public vars with <code>NEXT_PUBLIC_</code>, <code>VITE_</code>, <code>PUBLIC_</code> (framework-specific)</li><li>Use different values per deploy context</li></ul>
<h3>Pattern 7: Monorepo Deployment</h3>
<pre><code class="lang-toml"># netlify.toml in repo root
[build]
base = &quot;apps/marketing&quot;
command = &quot;npm run build&quot;
publish = &quot;dist&quot;
# Ignore builds if app didn&#x27;t change
ignore = &quot;git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF apps/marketing&quot;</code></pre>
<p><strong>Multiple sites from one repo</strong>:</p>
<pre><code class="lang-toml"># Site 1: apps/marketing/netlify.toml
[build]
base = &quot;apps/marketing&quot;
command = &quot;npm run build&quot;
publish = &quot;dist&quot;
# Site 2: apps/docs/netlify.toml
[build]
base = &quot;apps/docs&quot;
command = &quot;npm run build&quot;
publish = &quot;dist&quot;</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Monorepo with multiple deployable apps</li><li>Need selective builds (only build changed apps)</li><li>Sharing common packages</li></ul>
<hr>
<h2>Quick Reference</h2>
<h3>Common Build Commands</h3>
<pre><code>Framework | Build Command | Publish Directory
----------------|-------------------------|------------------
Next.js | npm run build | .next
Astro | npm run build | dist
SvelteKit | npm run build | build
Vite | npm run build | dist
Nuxt 3 | npm run build | .output/public
Gatsby | npm run build | public
Remix | npm run build | build/client
Eleventy | npx @11ty/eleventy | _site
Hugo | hugo | public
Jekyll | jekyll build | _site</code></pre>
<h3>Deploy Contexts</h3>
<pre><code>Context | Trigger | Use Case
-----------------|------------------------|---------------------------
production | Push to main branch | Live site
deploy-preview | Open pull request | PR previews
branch-deploy | Push to other branch | Feature branch testing</code></pre>
<h3>Critical Files</h3>
<pre><code>File | Purpose
-------------------|------------------------------------------
netlify.toml | Build config, redirects, headers
_redirects | Redirects (alternative to toml)
_headers | Headers (alternative to toml)
.nvmrc | Node version specification
package.json | Dependencies, build scripts</code></pre>
<h3>Deployment Checklist</h3>
<pre><code>✅ Build command configured
✅ Publish directory set correctly
✅ Environment variables added (production + preview)
✅ Redirects configured (especially SPA fallback)
✅ Security headers added
✅ Cache headers for static assets
✅ Node version specified (.nvmrc or netlify.toml)
✅ Git LFS configured (if using large files)
✅ Custom domain configured (if applicable)
✅ HTTPS enforced</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<p>❌ <strong>Wrong publish directory</strong>: Build succeeds but site shows 404 ✅ Check framework&#x27;s output directory (<code>.next</code>, <code>dist</code>, <code>build</code>, etc.)</p>
<p>❌ <strong>Missing SPA fallback redirect</strong>: Direct routes 404 in SPAs ✅ Add <code>/* /index.html 200</code> redirect for client-side routing</p>
<p>❌ <strong>Hardcoded environment variables</strong>: API URLs in source code ✅ Use environment variables, different per deploy context</p>
<p>❌ <strong>No cache headers</strong>: Static assets re-downloaded on every visit ✅ Set <code>Cache-Control: public, max-age=31536000, immutable</code> for hashed assets</p>
<p>❌ <strong>Sensitive keys in netlify.toml</strong>: API secrets committed to Git ✅ Use Netlify UI or CLI for sensitive environment variables</p>
<p>❌ <strong>Build command missing dependencies</strong>: Build fails after npm install ✅ Ensure all dependencies in package.json, test locally with <code>netlify dev</code></p>
<p>❌ <strong>Deploying build artifacts</strong>: Committing <code>dist/</code> or <code>.next/</code> to Git ✅ Add to .gitignore, let Netlify build on deploy</p>
<p>❌ <strong>No base directory in monorepo</strong>: Builds entire repo ✅ Set <code>base = &quot;apps/your-app&quot;</code> in netlify.toml</p>
<hr>
<h2>Related Skills</h2>
<ul><li><code>netlify-functions.md</code> - Serverless functions, Edge Functions, API endpoints</li><li><code>netlify-optimization.md</code> - Performance, caching, build optimization</li><li><code>nextjs-app-router.md</code> - Next.js specific deployment patterns</li><li><code>astro-deployment.md</code> - Astro SSR and hybrid deployment</li><li><code>github-actions-workflows.md</code> - Custom CI/CD before Netlify deploy</li><li><code>cloudflare-workers.md</code> - Alternative edge deployment platform</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-18 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/deployment-netlify-deployment.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>