Why Build Time Matters (And Why You're Watching It Slow Down)
Build time affects three people: you (during dev), your CI/CD pipeline (on every push), and users waiting for deploys. A 5-minute build means 50 deploys per day costs 250 minutes of developer time. That's half a workday you're not shipping. Add a second developer and it's a full day. Worse, slow builds create the "one big commit per day" pattern where you batch changes and deploy once, killing feedback loops.
Why does Astro get slow? By default, it renders pages serially: page 1, then page 2, then page 3. The build process is single-threaded. Image transforms happen per-request at build time. Tailwind scans all 47 component files and purges unused CSS from all of them, even though you only edited one button. The build cache doesn't persist between CI runs (or you don't know how to wire it). So every deploy, you're paying the same cost as the first deploy.
At 50 pages, this is fine. At 500+ pages, it compounds. Velocity X hit 3:20 builds before optimizations kicked in. That's because of 200+ blog posts, 50+ portfolio items, dynamic category pages, and a dashboard. Each one rendered serially. Each deploy was a wall of wait time.
Optimization 1: Parallel Rendering with `astro build` Threading
Astro 4.1+ supports parallel page rendering by default if you enable it in config. This is the single biggest win for multi-hundred-page sites.
{`// astro.config.mjs
export default defineConfig({
build: {
concurrency: 8, // render 8 pages simultaneously
},
});`}What this does: instead of rendering pages 1, 2, 3, 4 sequentially, Astro spawns 8 worker threads and renders pages 1–8 in parallel. When page 1 finishes, the thread picks up page 9. When page 2 finishes, it picks up page 10. All 200 pages still render, but on 8 cores instead of 1.
The win is real. Velocity X went from 2:10 to 1:35 just by setting `concurrency: 8`. Your mileage depends on your CPU count. Default is usually 1 (serial). Never assumed to be set. Most devs don't know it exists.
Cap it at your CPU count minus 1 (reserve one core for the OS). On a 16-core Netlify builder (which is what free tier gets), `concurrency: 12–14` is safe.
Optimization 2: Build Cache Persistence Across CI Runs
Netlify automatically persists the `.astro` cache folder between builds, but you have to tell Astro to use it. By default, Astro clears the cache on each `astro build` run—even if nothing changed.
{`// astro.config.mjs
export default defineConfig({
vite: {
ssr: {
noExternal: [], // no impact, just example
},
},
// Astro 5.0+: cache is persistent by default if you set cacheDir
cacheDir: '.astro/cache',
});`}Netlify's build cache works like this: after your first deploy, `/Users/aidenwood/.astro/cache` (or wherever Astro stores it) gets saved to Netlify's artifact storage. On the next deploy, Netlify restores that cache before building. Astro checks: "Did this file change? Is it in cache?" If no and yes, Astro skips re-rendering. If you only edited one blog post, Astro re-renders one file instead of 200.
The impact is enormous for incremental changes. A single blog post edit drops build time from 1:25 to 0:18. A button color change drops it from 1:25 to 0:32 (everything is cached except the one page that imports that button).
Set build cache in Netlify's UI: go to Build & Deploy → Build Cache. Toggle "Save & use cache from previous builds." It's free and automatic.
Optimization 3: Image Transform Memoization (Skip Redundant Sharp Calls)
Astro's image pipeline (via Sharp) converts images to WebP/AVIF at build time. If you reference the same image 5 times, Sharp runs 5 times by default. This is wasteful.
{`// src/lib/image-cache.ts
const imageTransformCache = new Map();
export function getCachedImageTransform(src: string, options: object) {
const key = JSON.stringify({ src, ...options });
if (imageTransformCache.has(key)) {
return imageTransformCache.get(key);
}
const result = transformImage(src, options); // Sharp call
imageTransformCache.set(key, result);
return result;
}`}In Velocity X, portfolio thumbnails appear on the homepage, category pages, and individual item pages. That's 3 references to the same hero image. Without memoization, Sharp processes it 3 times. With memoization, Sharp processes it once, cache serves the rest. Saves 2–8 seconds per 50-image site.
This is less critical if every image is unique, but if you reuse hero shots or brand assets across multiple pages, it's pure win.
Optimization 4: Tailwind Purge Scope — CSS Recompilation Only for Changed Files
Tailwind's purge step scans your templates to find which utility classes are actually used. By default, it scans everything on every build. Editing one button in one component file triggers a full Tailwind purge of all 15,000 utilities across all 47 components.
{`// tailwind.config.js
export default {
content: [
'./src/**/*.{astro,html,js,jsx,ts,tsx}',
],
cacheInvalidation: {
contentFiles: true, // default
buildDependencies: true, // default
},
};`}Velocity X uses Tailwind 3.3.3 (not 4, which has different purge logic). In 3.3.3, the trick is to ensure Tailwind only re-parses files that changed. Modern versions do this by default, but if you're on an older version or have a massive component library, you might see full re-purges.
Netlify build cache helps here too: on incremental changes, most CSS is cached. Only new or modified component files trigger re-parsing.
Rough impact: a single component edit saves 15–30 seconds of Tailwind re-compilation. Adds up fast across 10 commits.
Optimization 5: MDX and Blog Preprocessing
Velocity X uses `.astro` files for blog posts (not MDX), but if you do use MDX, preprocessing can be a bottleneck. Each MDX file is compiled to React components at build time. 100 posts = 100 compilations.
{`// astro.config.mjs
export default defineConfig({
integrations: [
mdx({
optimize: true, // pre-optimize AST, cache result
cacheFile: '.astro/mdx-cache',
}),
],
});`}If you use MDX (not the default in Velocity X), enable `optimize: true` and set a cache file. MDX caches the parsed AST, so re-builds skip re-parsing if the markdown source didn't change. On a 50-post blog, this can save 8–15 seconds per build.
For `.astro` blog posts like Velocity X uses, this doesn't apply—Astro already caches templates.
Before and After: Real Timings
Local machine (MacBook Pro 16-core M2 Max):
- Before: `astro build` with defaults = 3:20 (serial, no cache tuning)
- After: `astro build` with all 5 optimizations = 1:25
- Incremental (single blog post edit) = 0:18
Netlify CI (free tier, ~12-core builder):
- Before: 2:45 (parallel, no cache persistence)
- After: 1:18 with build cache enabled
- Incremental (single file change): 0:32
The speedup compounds. Velocity X went from 3:20 to 1:25 (59% faster). More pages = bigger win. If you ship 10 times a day, that's 30 minutes of developer time back per day. Over a year, that's 125 hours. At $150/hr billable, that's $18,750 in reclaimed productivity.
Six FAQs
What's the maximum concurrency I should set?
Cap it at (CPU count - 1). On a 16-core machine, use 14. On a 4-core laptop, use 3. Too high and the OS thrashes context-switching. Too low and you're leaving cores idle. Most CI runners (GitHub Actions, Netlify) give you 2–16 cores depending on tier.
Does Netlify build cache work for all build tools or just Astro?
Netlify build cache works for any tool. It caches whatever you tell it to cache via the `cache_dirs` setting in `netlify.toml`. Set it to `.astro/cache` and you're golden. Other tools: `.next`, `node_modules` (if pre-built), `.gatsby`, etc.
Will parallel rendering break if I have race conditions or shared state?
No. Each page renders in isolation; they don't share memory. If you're using Astro's `getStaticPaths()` to generate dynamic pages, each path still renders independently. The only caveat: if you're writing to the filesystem during build (e.g., logging per-page metrics), you might have file contention. But that's rare.
What if I'm using dynamic routes (SSR)?
Parallel rendering only applies to static builds. If you're doing SSR (Netlify functions, Vercel Serverless), the server handles request timing. Build time is not the bottleneck.
Can I cache images per-environment (dev, staging, production)?
Yes. Set `cacheDir` in your Astro config to a custom location, and wire Netlify (or your CI runner) to cache that folder. You can have separate cache strategies for dev (loose, fast) and prod (strict, thorough).
How do I know if my build is slow because of images or because of page count?
Run `astro build` with `--verbose` flag. Astro logs each step: rendering pages, image transforms, CSS purge, bundling. Look for any single step taking >30 seconds. If image transforms are 60% of the time, optimize images. If page rendering is 60%, increase `concurrency`. If Tailwind is the bottleneck, you likely have a massive stylesheet or overly generic selectors.
The Bottom Line
Build time scales with page count, but it doesn't have to scale linearly. Velocity X's 200+ pages in 90 seconds proves that smart caching, parallel rendering, and build-system tuning can keep even large static sites fast. The patterns work at 50 pages (less impact) and 5000 pages (enormous impact). For a deeper look at how Velocity X's image optimization pipeline integrates with build performance, see Image Optimisation in Astro 5. When you're ready to ship large-scale sites without waiting for builds, check Velocity X pricing.