Build and Deploy
The full pipeline — dev server, production build, Pagefind search, and Cloudflare Pages.
On this page
The Three Commands
This assumes you have shipped content collections and understand markdown rendering. For the wider stack philosophy see the mental model and the way .astro files compose into static output.
| Command | What It Does | Analogy |
|---|---|---|
npm run dev | Starts live-reload dev server at localhost | jupyter notebook — hot-reloading preview |
npm run build | Compiles everything to dist/ | make all — full production build |
npm run preview | Serves dist/ locally | Opening the final PDF to check it |
Dev Server
npm run devOpens http://localhost:4321. When you edit an .astro, .md, or .css file, the browser auto-refreshes. Use this while writing content and tweaking design.
The dev server runs your build pipeline on every change, but incrementally — only recompiling what changed. It’s fast because Astro uses Vite under the hood, which does hot module replacement.
Production Build
npm run buildkrowdev’s build command chains three steps:
"build": "node scripts/check-mermaid-cache.mjs && astro build && npx pagefind --site dist"node scripts/check-mermaid-cache.mjs— verifies the pre-rendered Mermaid diagram cache is current before the buildastro build— compiles all pages, optimizes images, downloads fonts, generates sitemapnpx pagefind --site dist— scans the HTML output and builds a search index
The output lands in dist/:
- dist/
- ├── index.html# homepage
- ├── guide/
- │ ├── agentic-coding-getting-started/index.html
- │ ├── agentic-coding-prompt-patterns/index.html
- │ ├── astro-mental-model/index.html
- │ └── ... (one per guide entry)
- ├── article/
- │ └── welcome-to-krowdev/index.html
- ├── _astro/
- │ ├── fonts/# self-hosted Inter + JetBrains Mono
- │ └── *.css# compiled stylesheets
- ├── pagefind/# search index
- │ ├── pagefind-entry.json
- │ └── fragment/...
- ├── favicon.svg
- └── sitemap-index.xml
This dist/ folder is your final artifact — like a compiled binary or a rendered PDF. Everything needed to serve the site is in there. No runtime dependencies, no database, no server process.
Pagefind — Build-Time Search
Pagefind creates a client-side search engine from your static HTML. It:
- Scans all
.htmlfiles indist/ - Extracts text from elements with
data-pagefind-body - Builds a compressed search index
- Ships a tiny JS widget that searches the index in the browser
The search index is typically 10-50KB — small enough to load instantly. No server needed.
In krowdev, kb entries have data-pagefind-body on their content area:
<article data-pagefind-body> <slot /></article>This tells Pagefind: “index the content inside this element.” Headers, footers, and sidebars are excluded.
Cloudflare Pages Deployment
Cloudflare Pages serves the dist/ folder. Setup:
- Push to GitHub — your repo containing the Astro project at the root
- Connect in Cloudflare Dashboard — Workers & Pages → Create → Connect to Git
- Configure build:
- Root directory: leave blank (or set to your subdirectory if you use a monorepo)
- Build command:
npm run build - Output directory:
dist - Environment variable:
NODE_VERSION=24(match your project’sengines.node)
- Auto-deploy — every push to
maintriggers a rebuild
Pushing code fires a GitHub webhook that triggers a Cloudflare Pages build, which publishes the site.
graph LR
accTitle: Push-to-deploy pipeline
accDescr: Pushing code fires a GitHub webhook that triggers a Cloudflare Pages build, which publishes the site.
push["You push code"] --> hook["GitHub webhook"] --> build["Cloudflare builds"] --> live["Site goes live"]You push code → GitHub webhook → Cloudflare builds → site goes liveCloudflare’s free tier: unlimited bandwidth, 500 builds/month, global CDN. More than enough for a personal blog.
krowdev’s Astro project lives at the repo root, so the root directory is left blank. Only set a root directory (and Cloudflare will cd into it before npm run build) if your Astro project sits in a subdirectory of a monorepo.
The Full Workflow
Here’s what a typical content workflow looks like:
1. Write markdown in content/kb/2. npm run dev → preview at localhost:43213. Happy with it? → git add + git commit4. git push → Cloudflare auto-deploys5. Site live at krowdev.pages.dev in ~30 secondsThis is like a LaTeX + Makefile + CI/CD pipeline:
Edit .tex → make preview → looks good → git push → CI runs pdflatex → PDF publishedSame flow, different tools.
What You’ve Learned
Over 9 lessons, you’ve covered the full Astro architecture:
| Lesson | Concept | One-Liner |
|---|---|---|
| 01 | Mental Model | Astro is a compiler, not a server |
| 02 | File Routing | src/pages/ directory = URL structure |
| 03 | .astro Files | Code fence (build time) + template (HTML output) |
| 04 | Components | Reusable pieces with props and slots |
| 05 | Layouts | Template inheritance via nested <slot /> |
| 06 | Content Collections | Typed, validated markdown with query API |
| 07 | Styling | Scoped CSS + global tokens + Catppuccin theming |
| 08 | Markdown & Code | Shiki highlighting, MDX for components in content |
| 09 | Build & Deploy | dist/ is the artifact, Cloudflare serves it |
You now understand every file in krowdev. The codebase has no mysteries.
Final Challenge: Add a real article end-to-end
Do the full workflow:
- Create a new kb entry:
content/kb/first-article.md - Write valid frontmatter (title, description, kind: guide, tags, maturity, origin, confidence)
- Add some content with a code block, a table, and a heading
- Preview with
npm run dev— check sidebar, ToC, syntax highlighting, dark/light mode - Build with
npm run build— verify it compiles and Pagefind indexes it - Check the output:
ls dist/guide/first-article/
If all that works, you’ve completed the course. You can now write and publish content to krowdev independently.
Sources
- Astro Docs, Build configuration
- Astro Docs, Server-side rendering
- Cloudflare Pages, Astro deployment
- Pagefind, Documentation