Why Fast AI Website Demos Become Slow Production Sites

The first screen is usually fast because it is empty of consequences

Early AI website demos have favorable conditions. There is one route, placeholder copy, a few local images, no consent manager, no analytics, and no real content stress. The page runs on a developer’s machine with a warm cache. It feels instant.

Production adds consequences. Marketing installs scripts. Images arrive at their original camera dimensions. A custom font gains four weights. Components hydrate because the agent chose a client framework by habit. Content makes headings wrap. The CDN is configured, but the HTML still asks the browser to do too much.

Performance is not a final optimization sprint. It is the accumulated result of architectural defaults.

JavaScript should need an alibi

For a marketing or editorial page, the primary content, navigation, CTA, and most visual treatment can exist in HTML and CSS. Client JavaScript belongs where the browser must manage interaction or state.

Agents often reach for familiar interactive components even when the output is static. A card list becomes a hydrated component. An accordion loads a framework runtime for content that could use native disclosure behavior. A decorative entrance animation ships observers and event handlers on every route.

Review each hydrated island with three questions:

1. What user behavior requires client execution?
2. Can a native HTML element or CSS provide the same result?
3. Can loading wait until the component is visible or otherwise needed?

Astro makes zero client JavaScript a practical baseline for ordinary components. The team still has to preserve that baseline when selecting integrations and hydration directives.

The Claude Code and Astro guide shows how to encode this rule in repository instructions instead of repeating it in every prompt.

Images fail before the network request

An image problem begins when the asset enters the project. If nobody records its role, intrinsic dimensions, crop, and priority, the implementation has to guess.

Common production mistakes include:

• publishing a source image far larger than its rendered size;
• using one wide crop for every viewport;
• omitting dimensions and creating layout movement;
• eagerly loading below-the-fold imagery;
• lazy-loading the likely largest contentful image;
• compressing text or interface screenshots until they become difficult to read;
• writing alt text that repeats the filename or nearby caption.

Use the framework’s image pipeline where it fits. Generate modern formats and responsive sources. Reserve layout space. Treat the lead visual differently from supporting imagery. Performance and accessibility meet at the asset decision, not in separate audits.

Fonts are a system, not a decoration

A type family may contain many weights and styles. The website rarely needs all of them. Every font file adds transfer and can affect when text becomes stable.

Choose the smallest set that supports the actual hierarchy. Prefer a variable font when its file and browser behavior make sense for the project, or subset static files to the weights in use. Preload only the critical face. Use a fallback stack with compatible proportions. Avoid shipping an icon font for a handful of symbols.

Then test with real headings. A late-loading font that changes line breaks can move everything below the fold even when its file is well compressed.

Third parties spend a budget they did not earn

Analytics, ad pixels, chat widgets, video embeds, scheduling tools, and consent platforms can dominate a carefully built page. Their cost includes network connections, parsing, main-thread work, and privacy complexity.

Create an owner and purpose for every third party. Decide whether it loads on all routes, after consent, after interaction, or only on the page that needs it. A screenshot linking to a video can be a better initial experience than an eager iframe. A plain purchase link may be better than a heavy embedded checkout for a simple product.

The performance conversation becomes more useful when framed as business tradeoffs: what decision will this script inform, and is that decision worth its effect on the reader?

A CDN cannot repair the document

Global edge delivery reduces distance and can serve immutable assets efficiently. It does not remove unused JavaScript, fix oversized images, or prevent layout shift. CDN work begins after the page has a disciplined output.

For a static Astro site on Cloudflare, separate caching by artifact:

The Astro on Cloudflare deployment guide covers the boundary between a good build and a good edge configuration.

Measure the result, not the framework’s reputation

Core Web Vitals describe user-centered loading, interaction, and visual-stability outcomes. They are not a substitute for examining the build. A field metric can reveal real experience while still leaving the cause unclear. A lab trace can expose a cause while missing the conditions of actual visitors.

Use both perspectives when traffic permits. During development, track artifacts that the team controls directly:

• total client JavaScript by representative route;
• CSS and font transfer;
• image dimensions, formats, and loading policy;
• third-party origins and execution;
• rendered HTML size;
• layout shifts under real content;
• slow-network and mid-tier-device behavior.

Do not promise a universal score. A checkout, interactive tool, and text article have different jobs. Set route-level budgets that reflect those jobs, then investigate regressions.

Diagnose in the order the browser pays

Begin with the production build. List the HTML, CSS, JavaScript, fonts, and large media attached to one slow route. Compare that inventory with a simple route using the same layout. The difference often points to the feature or content pattern that introduced the cost.

Next, inspect loading order. Which resource competes with the primary heading or lead image? Which origin requires a new connection? Which script executes before the reader can use the page? Check whether the likely largest contentful element is discoverable in the initial HTML and whether its dimensions reserve space.

Then inspect runtime behavior. Look for long tasks, repeated layout calculation, scroll listeners, animation work, and components that hydrate but never receive interaction. A small compressed bundle can still block the main thread; byte size and execution cost answer different questions.

Finally, compare laboratory findings with field data when the site has enough valid traffic. Segment by route type and device context. Do not treat a sitewide average as proof that every template is healthy.

CSS can create invisible work

Static output does not guarantee a cheap rendering path. Large global stylesheets can carry unused component rules to every route. Complex selectors, oversized effects, backdrop filters, and layout animations can increase rendering cost. An agent may also append local overrides until the cascade becomes difficult to reason about.

Keep design primitives small and composable. Prefer tokens for shared values and component styles for real patterns. Remove rules when a component is retired. Animate opacity and transforms where motion is justified, and honor prefers-reduced-motion. Do not hide content until a client script adds an entrance class; the no-script experience should remain complete.

Review responsive CSS with actual content. A desktop layout that relies on fixed heights often causes overflow or clipping after headings wrap. The performance symptom may appear as layout movement, but the cause is a brittle composition rule.

Failure modes that escape a fast laptop

Route-wide prefetching

Prefetch can make the next navigation feel quick while consuming bandwidth for links a visitor never opens. Use framework behavior deliberately. A page with dozens of editorial cards needs a different policy from a short product page with one obvious next step.

Duplicate libraries

Two integrations may bring overlapping utilities, date handling, or icon packages. The build can succeed and tree-shaking can help, but inspect the emitted chunks. Removing duplication at the dependency boundary is safer than hoping compression makes it irrelevant.

Global analytics initialization

A tool needed for one campaign can become part of every route through the base layout. Scope scripts to the routes and consent state that require them. Verify the event still fires rather than assuming a delayed load preserved behavior.

Decorative media promoted to critical

Preloading several hero candidates, poster images, and background textures can crowd out the one resource the reader needs first. Priority is a scarce signal. Assign it to the actual lead content for each template.

Example: the animated product hero

An agent builds a convincing hero with a large background video, a WebGL accent, two font families, and a hydrated carousel. On the development machine, all assets are cached and the movement feels polished. On a new mobile visit, the heading competes with media downloads, controls appear late, and the layout changes when the font arrives.

The correction starts with the communication goal. If the video proves the product, provide an optimized poster, avoid autoplay under constrained or reduced-motion conditions, and load the full media after the primary content. If the WebGL accent is decorative, replace it with a static asset or delay it. Reduce the carousel to a static lead example unless user-controlled switching adds real value. Load only the font faces used above the fold and tune fallbacks.

The final design may still be expressive. The browser no longer has to execute every idea before showing the message.

Encode prevention without chasing one score

Add build reporting for route-level scripts, stylesheet size, font files, and large assets. Set budgets based on the project’s current baseline and the job of each template. Fail on clear regressions that the team has agreed to prevent; warn on unusual changes that need inspection.

Document approved exceptions. If a product demo requires a larger interactive bundle, keep it isolated to that route and explain why. This prevents the next agent from copying the exception into a generic layout.

After deployment, verify cache headers and compression on the real domain. Request a cold route from more than one network context when possible. Production evidence closes the loop between source rules and reader experience.

Performance belongs in the change request

Suppose a stakeholder asks for an autoplaying background video. The question is not whether the agent can implement it. The change needs an explicit decision about compression, mobile behavior, poster image, reduced motion, data use, and its effect on the lead content.

When requirements change, update the performance model with them. This is how teams avoid the late-stage ritual where engineering is asked to recover speed without removing any of the work that made the site slow.

The durable fix

Start with static output. Establish asset and hydration rules. Set budgets in the build. Test representative routes with final content. Verify production delivery. Require exceptions to name their user or business value.

An agent can then move fast because the repository answers the recurring question: is this allowed to make the page heavier? Without that answer, generated code will optimize for the visible request and leave the browser to absorb the cost.