50 Lessons from Shipping 3,000 Pages
Practical Wisdom from Building at Scale with AI
Every lesson was learned the hard way — through failed builds, broken deploys, and late-night debugging sessions. These are the rules that emerged from building 3,000+ pages with Claude Code, Next.js, and Vercel.
50
Lessons
6
Categories
3,000+
Pages Built
/10
Importance Score
The Essential Ten
Top 10 Lessons (Importance: 10/10)
If you only read ten things, read these.
ISR Is Non-Negotiable at Scale
ArchitecturePre-render what matters, generate the rest on demand.
Pre-rendering 3,000+ pages would take 45+ minutes on Vercel. Only 50 blog posts are pre-rendered at build time. Everything else uses ISR with dynamicParams = true. Build time dropped from 45+ minutes to under 10.
Components Are Your Foundation
ArchitectureBuild once, use everywhere. Consistency requires composability.
SiteNavBar, SiteFooter, EmailCapture, ExploreMore, MotionWrappers. Every page assembles from the same building blocks. When a component changes, hundreds of pages update. Without shared components, 3,000 pages would be unmaintainable.
Every Page Is a Long-Tail Asset
Content3,000 pages means 3,000 chances to rank.
Each page targets different keywords. Billionaire profiles rank for name searches. Blog posts rank for financial topics. Tool pages rank for software queries. The site compounds over time as pages index and climb.
Internal Links Are a Superpower
ContentEvery page should link to 5-10 other pages.
ExploreMore component at the bottom of every page. Contextual links in body text. Cross-links between related topics. This creates a dense internal link graph that search engines reward heavily and keeps users engaged.
Schema Everything with JSON-LD
SEOIf it exists on your site, it should have structured data.
Article schema, FAQPage schema, Person schema on every page. Google's rich results require structured data. JSON-LD is the format Google recommends. Each page includes two script tags: one for Article, one for FAQPage.
CLAUDE.md Is Your AI Constitution
AIOne file to rule all AI behavior in your project.
The CLAUDE.md file at the project root contains every rule the AI must follow: deployment commands, styling conventions, component patterns, and hard constraints. This single file is the difference between chaos and consistency when running multiple AI agents.
AI Makes Mistakes. Review Everything.
AITrust but verify. Always.
Claude Code occasionally introduces bugs, forgets patterns, or over-engineers solutions. The key is reviewing output, catching patterns early, and updating CLAUDE.md with new rules when mistakes repeat. Human oversight is non-negotiable.
Git Push Is the Only Deploy Command
DeploymentNever use vercel deploy. Ever.
The working directory is 34,000+ files and 1.5GB. Running vercel deploy uploads everything and kills internet bandwidth. Git push only uploads the diff (kilobytes). Vercel's Git integration builds and deploys automatically. This is the most important deployment rule.
Ship Today, Polish Tomorrow
SpeedA page that exists beats a page you are still planning.
Every page on this site was shipped before it was perfect. Typos get fixed, sections get expanded, designs get refined. But the page exists and is indexing from day one. Perfectionism is the enemy of velocity.
Architecture Lessons
(9)ISR Is Non-Negotiable at Scale
10/10Pre-render what matters, generate the rest on demand.
Pre-rendering 3,000+ pages would take 45+ minutes on Vercel. Only 50 blog posts are pre-rendered at build time. Everything else uses ISR with dynamicParams = true. Build time dropped from 45+ minutes to under 10.
Server Components Are the Default
9/10Ship less JavaScript. Let the server do the work.
Every page is a server component unless it needs interactivity. Client components are islands: animations, search, forms. This dramatically reduces the JavaScript bundle sent to browsers and improves performance.
Components Are Your Foundation
10/10Build once, use everywhere. Consistency requires composability.
SiteNavBar, SiteFooter, EmailCapture, ExploreMore, MotionWrappers. Every page assembles from the same building blocks. When a component changes, hundreds of pages update. Without shared components, 3,000 pages would be unmaintainable.
File-Based Routing Scales Beautifully
8/10One folder, one page. The filesystem is your sitemap.
Next.js App Router means every page is a folder with a page.tsx. Managing 250+ pages is just managing 250+ folders. No routing config, no manifest files. The filesystem itself is the source of truth.
TypeScript Catches What You Miss
9/10Type safety prevents entire classes of bugs at scale.
When AI generates hundreds of files, TypeScript catches mismatched props, missing fields, and structural errors before they ship. Strict mode catches issues at compile time that would otherwise appear at runtime across 3,000 pages.
CSS Variables Beat Hardcoded Colors
7/10Theme once, apply everywhere.
Tailwind 4 CSS variables (text-foreground, bg-card, border-border, accent) create a consistent design system. Changing the entire site theme means changing a few variables, not editing thousands of class strings. Amber accents tie everything together.
API Routes Should Be Serverless
7/10No servers to manage. Functions that scale to zero.
Vercel serverless functions handle search, analytics, email capture, and more. Pay nothing when they are idle, scale automatically under load. No Docker, no EC2, no infrastructure management.
Layouts Prevent Repetition
8/10Shared structure belongs in layout.tsx, not every page.
Next.js layouts wrap pages with shared UI. The root layout handles fonts, metadata, and global providers. Page-specific layouts handle section navigation. Without layouts, every page would duplicate boilerplate.
Keep Build Artifacts Out of Git
8/10node_modules and .next have no place in version control.
The working directory is 1.5GB with node_modules. A proper .gitignore is the difference between git push uploading kilobytes (the diff) and uploading gigabytes (the world). This is especially critical with Vercel's Git-based deployment.
Content Lessons
(9)Every Page Is a Long-Tail Asset
10/103,000 pages means 3,000 chances to rank.
Each page targets different keywords. Billionaire profiles rank for name searches. Blog posts rank for financial topics. Tool pages rank for software queries. The site compounds over time as pages index and climb.
Internal Links Are a Superpower
10/10Every page should link to 5-10 other pages.
ExploreMore component at the bottom of every page. Contextual links in body text. Cross-links between related topics. This creates a dense internal link graph that search engines reward heavily and keeps users engaged.
Depth Beats Breadth on Individual Pages
8/10One topic, covered thoroughly, beats ten topics covered lightly.
Each page goes deep on a single subject with data, details, and multiple sections. Google rewards comprehensive coverage. A 2,000-word page that answers every question outranks a 200-word page that answers one.
Consistency Builds Brand Recognition
7/10Same header, same footer, same tone on every page.
Users who land on any page instantly recognize the site. SiteNavBar at top, SiteFooter at bottom, amber accents, dark theme. Consistency communicates professionalism and builds trust across thousands of pages.
FAQ Sections Serve Double Duty
9/10Answer questions for users and for Google.
Every page has an FAQ section with JSON-LD FAQPage schema. Users get their questions answered. Google can show rich snippets. The FAQ also naturally incorporates long-tail keywords that the main content might miss.
Cross-Reference Everything
8/10If two pages are related, they should link to each other.
Billionaire pages link to their books. Book pages link to the billionaires who recommend them. Tool pages link to architecture pages. This bidirectional linking creates topic clusters that search engines recognize as authority signals.
Data-Driven Content Engages Better
7/10Numbers, rankings, and scores make content scannable.
Scored lists (importance /10, usefulness /10) give readers a quick way to evaluate content. Rankings create natural hierarchy. Stats sections break up text. Data-driven content is easier to consume and more shareable.
Email Capture on Every Page
8/10Every page is an opportunity to build the list.
The EmailCapture component appears on every content page. Not intrusive, just present. Even a low conversion rate across 3,000+ pages adds up. The email list is the only audience you truly own.
Disclaimers Protect You
6/10A small note at the bottom saves future headaches.
Every page includes a disclaimer noting AI assistance, approximate stats, and that content is not financial advice. Small investment in text, large investment in legal protection. Never skip disclaimers on content at scale.
SEO Lessons
(9)Schema Everything with JSON-LD
10/10If it exists on your site, it should have structured data.
Article schema, FAQPage schema, Person schema on every page. Google's rich results require structured data. JSON-LD is the format Google recommends. Each page includes two script tags: one for Article, one for FAQPage.
Canonical URLs Prevent Duplicate Content
9/10One URL per page. Tell Google which one is real.
Every page sets alternates.canonical in its Metadata export. Without canonicals, Google might index URL variants as separate pages, diluting ranking signals. One canonical URL consolidates all authority.
Meta Descriptions Are Your Ad Copy
8/10150 characters to convince someone to click.
Every page has a custom meta description that reads like ad copy. Not a generic summary, but a compelling reason to click. At 3,000+ pages, writing individual descriptions matters because each one appears in search results.
OG Images Drive Social Click-Through
7/10A branded image in the preview is worth a thousand plain links.
Satori generates OG images dynamically for pages. Every share on Twitter/X, LinkedIn, or Discord shows a branded preview image. The visual presence in social feeds dramatically increases click-through rates.
Keywords in Metadata Actually Matter
8/10The keywords meta tag is dead. Keywords in title and description are not.
Every page includes 10-15 targeted keywords in the metadata export. More importantly, primary keywords appear in the title tag and meta description. This helps Google understand page relevance and rank accordingly.
Headings Create Content Hierarchy
7/10H1 for the title, H2 for sections, H3 for subsections.
Proper heading hierarchy helps search engines understand content structure. One H1 per page, logical H2/H3 nesting. Screen readers rely on heading structure for accessibility. Headings are both SEO and UX.
URL Slugs Should Be Human-Readable
7/10Clean URLs rank better and get clicked more.
/tech-stack reads better than /page?id=47. /lessons-from-shipping is self-descriptive. Next.js App Router automatically creates clean URLs from folder names. Short, descriptive slugs with hyphens perform best.
Page Speed Is a Ranking Factor
8/10Faster pages rank higher. Server components help.
Server-rendered HTML loads instantly. Minimal client JavaScript means fast time-to-interactive. Vercel's edge network reduces latency globally. Image optimization prevents large downloads. Speed is not just UX, it's SEO.
Sitemap Generation Is Automatic
7/10Next.js generates sitemaps. Let the framework do its job.
Next.js can auto-generate sitemaps from the file structure. Submitting the sitemap to Google Search Console accelerates indexing. At 3,000+ pages, manual sitemap management is impossible.
AI Lessons
(9)CLAUDE.md Is Your AI Constitution
10/10One file to rule all AI behavior in your project.
The CLAUDE.md file at the project root contains every rule the AI must follow: deployment commands, styling conventions, component patterns, and hard constraints. This single file is the difference between chaos and consistency when running multiple AI agents.
AI Makes Mistakes. Review Everything.
10/10Trust but verify. Always.
Claude Code occasionally introduces bugs, forgets patterns, or over-engineers solutions. The key is reviewing output, catching patterns early, and updating CLAUDE.md with new rules when mistakes repeat. Human oversight is non-negotiable.
Parallelism Is the Multiplier
9/10Nine agents working simultaneously means nine developers.
Run multiple Claude Code agents on different tasks in parallel. While one builds profiles, another migrates posts, another generates schemas. The velocity multiplier is massive. Serial work with AI wastes most of its potential.
Give AI Context, Not Just Instructions
9/10Show a pattern. Then ask for more of the same.
Instead of describing what a page should look like, show the AI an existing page and say 'make ten more like this.' Pattern-following is where AI coding assistants excel. One good example is worth a thousand words of specification.
Guardrails Prevent Catastrophes
9/10Hard rules in CLAUDE.md prevent expensive mistakes.
Never run vercel deploy (kills internet). Never use git add -A (commits secrets). Never use framer-motion (use motion/react). These rules exist because the mistakes were made once. Guardrails are lessons encoded as constraints.
AI Scales Content, Not Just Code
8/10The same tool that writes TypeScript can write copy.
Claude Code generates page content, FAQ sections, meta descriptions, and JSON-LD schema. Not just the code structure, but the words on the page. AI as a content engine is as valuable as AI as a code engine.
Incremental Complexity Beats Big Bang
8/10Build simple first. Add complexity one layer at a time.
Start with a basic page that renders. Add styling. Add animations. Add schema. Add FAQ. Each step is small and verifiable. When AI tries to build everything at once, the error surface is massive. Incremental wins compound.
Code Review Is Still Essential
8/10AI-written code needs human judgment.
Checking generated code for security issues, performance problems, and architectural drift is critical. AI can write a working page, but only a human can tell if it belongs in the codebase. Review standards do not change because AI wrote the code.
AI Needs Feedback Loops
7/10Tell the AI what went wrong. It gets better.
When Claude Code makes a mistake, documenting it in CLAUDE.md creates a feedback loop. The AI reads the rules on every new session. Over time, the quality baseline rises. The CLAUDE.md file is the accumulated intelligence of every past error.
Deployment Lessons
(7)Git Push Is the Only Deploy Command
10/10Never use vercel deploy. Ever.
The working directory is 34,000+ files and 1.5GB. Running vercel deploy uploads everything and kills internet bandwidth. Git push only uploads the diff (kilobytes). Vercel's Git integration builds and deploys automatically. This is the most important deployment rule.
Stage Specific Files, Never Everything
9/10git add filename.tsx, not git add -A.
Git add -A stages everything including .env files, node_modules residue, and build artifacts. Always stage specific files by name. This prevents accidental secret exposure and keeps commits clean and purposeful.
Every Commit Should Be Deployable
8/10If it hits master, it should work in production.
Since every push to master triggers a production deploy, every commit must be production-ready. No work-in-progress commits to master. No broken builds. Test locally, commit when confident, push when ready.
Preview Deployments Catch Surprises
7/10Branch deploys let you check before going live.
Vercel creates preview deployments for non-master branches. Use them to verify visual changes, test new pages, and catch layout issues before they hit production. The few minutes of checking saves hours of debugging.
Build Errors Are Deployment Blockers
8/10If it does not build, it does not ship.
TypeScript errors, missing imports, and invalid JSX prevent Vercel builds from completing. This is a feature, not a bug. The build process is the last line of defense against shipping broken code to production.
Environment Variables Stay Secret
9/10API keys belong in Vercel's dashboard, not in git.
Upstash Redis URLs, ConvertKit keys, and other secrets are stored in Vercel environment variables. The .env file is gitignored. Committing secrets is irreversible. Once pushed, they are in git history forever.
Rollbacks Are One Click Away
7/10Vercel keeps every deployment. Revert instantly.
Every deploy on Vercel is immutable and stored. If a deploy breaks something, roll back to the previous deployment in the Vercel dashboard. No need to revert git commits or force push. One click, instant rollback.
Speed Lessons
(7)Ship Today, Polish Tomorrow
10/10A page that exists beats a page you are still planning.
Every page on this site was shipped before it was perfect. Typos get fixed, sections get expanded, designs get refined. But the page exists and is indexing from day one. Perfectionism is the enemy of velocity.
Prefetching Makes Navigation Instant
7/10Next.js prefetches links in the viewport.
When a link appears on screen, Next.js prefetches the page in the background. By the time the user clicks, the page is already loaded. This makes the site feel instantaneous despite having 3,000+ pages.
Motion Wrappers Add Polish Without Cost
6/10Subtle animations make pages feel alive.
FadeInUp, StaggerContainer, and StaggerItem add scroll-triggered animations to every section. The motion/react library is lightweight. Animations are only triggered once (viewport.once = true). Polish that costs almost nothing in bundle size.
Batch Changes, Batch Deploys
7/10Group related changes into one commit and push.
Instead of pushing after every file change, batch related work. Build five pages, review them all, commit, push once. Fewer deploys means fewer builds, which means less Vercel usage and faster iteration cycles.
Caching Is Free Performance
8/10Let the CDN do the heavy lifting.
Vercel caches static pages at the edge. ISR pages are cached after first generation. Redis queries are fast but caching prevents unnecessary calls. Every layer of caching is free performance that reduces server load.
Measure What Matters
7/10Track page views, not vanity metrics.
Upstash Redis tracks which pages get traffic, which searches are popular, and where users engage. These metrics inform what to build next. Analytics should drive content strategy, not gut feeling.
The Changelog Is the Proof
8/10Document what you ship. The history speaks for itself.
Every feature, every page batch, every optimization is logged. The changelog is proof of velocity and commitment. When someone asks what you have been building, point them to the changelog. Show, do not tell.
Related Reading
Frequently Asked Questions
What are the most important lessons from building 3,000+ pages?
The top lessons are: ISR is non-negotiable at scale (keeps build times under 10 minutes), components are your foundation (consistency requires composability), every page is a long-tail SEO asset, CLAUDE.md is your AI constitution, and shipping today beats planning forever.
How does ISR help with large-scale websites?
Incremental Static Regeneration (ISR) means only a small subset of pages are pre-rendered at build time. The rest are generated on-demand when first requested. For glenbradford.com, only 50 blog posts are pre-rendered, while 2,950+ pages use ISR. This reduces build time from 45+ minutes to under 10.
What is the CLAUDE.md file?
CLAUDE.md is a project configuration file that provides rules and constraints for Claude Code (Anthropic's AI coding assistant). It contains deployment rules, coding conventions, component patterns, and hard constraints that the AI reads on every session. It is the accumulated intelligence of every past mistake.
How do you maintain quality when shipping fast?
Quality is maintained through TypeScript (catches errors at compile time), shared components (consistency across pages), code review (human oversight of AI output), and guardrails in CLAUDE.md (prevents known mistakes). Ship fast but review everything before pushing to master.
What role does AI play in content creation at scale?
Claude Code generates both code and content: page structures, FAQ sections, meta descriptions, JSON-LD schema, and body text. Running multiple agents in parallel means building many pages simultaneously. The human role is direction, review, and quality control.
How important is SEO when building at scale?
Extremely important. Every page needs JSON-LD schema, canonical URLs, meta descriptions, proper heading hierarchy, and internal links. At 3,000+ pages, each page is a long-tail keyword opportunity. Schema and structured data help Google understand and surface content in rich results.
What deployment strategy works best for large Next.js sites?
Git-based deployment through Vercel. Never use the Vercel CLI to deploy directly. Git push only uploads the diff (kilobytes), while vercel deploy would upload the entire 1.5GB working directory. Stage specific files, commit production-ready code, and push to master.
How do you decide what to build next?
Analytics drive the content strategy. Upstash Redis tracks which pages get traffic and which searches are popular. Pages that rank are expanded. Topics with search demand get new pages. Data-driven decisions beat gut feelings when managing 3,000+ pages.
Get Glen's Musings
Occasional thoughts on AI, Claude, investing, and building things. Free. No spam.
Unsubscribe anytime. I respect your inbox more than Congress respects property rights.
Keep Exploring
Building with AI
The full story of how glenbradford.com was built with Claude Code.
Read moreTechThe Tech Stack
Next.js 16, TypeScript, Tailwind 4, Vercel, Upstash, Claude Code.
Read moreOpen Source & Community
Tools, contributions, and philosophy for indie builders.
Read moreUpdatesChangelog
Every update, every feature, every deploy. The living history.
Read moreCobra Kai Philosophy
Strike First, Strike Hard, No Mercy. Applied to shipping.
Read moreAbout Glen Bradford
The person behind the 3,000+ pages. Investor, builder, kiteboarder.
Read moreNote: These lessons reflect experience as of March 2026. The site continues to evolve and new lessons continue to emerge. Some statistics are approximate. Not financial advice. This page was built with Claude Code.