No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL,Applies To,Status,Verified At
1,Architecture,Use Islands Architecture,Astro's partial hydration only loads JS for interactive components,Interactive components with client directives,Hydrate entire page like traditional SPA,<Counter client:load />,Everything as client component,High,https://docs.astro.build/en/concepts/islands/,astro 7.1.6,active,2026-08-13
2,Architecture,Default to zero JS,Astro ships zero JS by default - add only when needed,Static components without client directive,Add client:load to everything,<Header /> (static),<Header client:load /> (unnecessary),High,https://docs.astro.build/en/basics/astro-components/,astro 7.1.6,active,2026-08-13
3,Architecture,Choose right client directive,Different directives for different hydration timing,client:visible for below-fold client:idle for non-critical,client:load for everything,<Comments client:visible />,<Comments client:load />,Medium,https://docs.astro.build/en/reference/directives-reference/#client-directives,astro 7.1.6,active,2026-08-13
4,Architecture,Use content collections,Type-safe content management for blogs docs,Content collections for structured content,Loose markdown files without schema,const posts = await getCollection('blog'),import.meta.glob('./posts/*.md'),High,https://docs.astro.build/en/guides/content-collections/,astro 7.1.6,active,2026-08-13
5,Architecture,Define collection schemas,Zod schemas for content validation,Schema with required fields and types,No schema validation,defineCollection({ schema: z.object({...}) }),defineCollection({}),High,https://docs.astro.build/en/guides/content-collections/#defining-a-collection-schema,astro 7.1.6,active,2026-08-13
6,Routing,Use file-based routing,Create routes by adding .astro files in pages/,pages/ directory for routes,Manual route configuration,src/pages/about.astro,Custom router setup,Medium,https://docs.astro.build/en/basics/astro-pages/,astro 7.1.6,active,2026-08-13
7,Routing,Dynamic routes with brackets,Use [param] for dynamic routes,Bracket notation for params,Query strings for dynamic content,pages/blog/[slug].astro,pages/blog.astro?slug=x,Medium,https://docs.astro.build/en/guides/routing/#dynamic-routes,astro 7.1.6,active,2026-08-13
8,Routing,Use getStaticPaths for SSG,Generate static pages at build time,getStaticPaths for known dynamic routes,Fetch at runtime for static content,export async function getStaticPaths() { return [...] },No getStaticPaths with dynamic route,High,https://docs.astro.build/en/reference/api-reference/#getstaticpaths,astro 7.1.6,active,2026-08-13
9,Routing,Enable on-demand rendering when needed,Render only dynamic routes on demand or choose server output for a mostly dynamic site,export const prerender = false on selected routes,Use removed output: 'hybrid',export const prerender = false;,output: 'hybrid',Medium,https://docs.astro.build/en/guides/on-demand-rendering/,astro 7.1.6,active,2026-08-13
10,Components,Keep .astro for static,Use .astro components for static content,Astro components for layout structure,React/Vue for static markup,<Layout><slot /></Layout>,<ReactLayout>{children}</ReactLayout>,High,https://docs.astro.build/en/basics/astro-components/,astro 7.1.6,active,2026-08-13
11,Components,Use framework components for interactivity,React Vue Svelte for complex interactivity,Framework component with client directive,Astro component with inline scripts,<ReactCounter client:load />,<script> in .astro for complex state,Medium,https://docs.astro.build/en/guides/framework-components/,astro 7.1.6,active,2026-08-13
12,Components,Pass data via props,Astro components receive props in frontmatter,Astro.props for component data,Global state for simple data,const { title } = Astro.props;,Import global store,Low,https://docs.astro.build/en/basics/astro-components/#component-props,astro 7.1.6,active,2026-08-13
13,Components,Use slots for composition,Named and default slots for flexible layouts,<slot /> for child content,Props for HTML content,"<slot name=""header"" />",<Component header={<div>...</div>} />,Medium,https://docs.astro.build/en/basics/astro-components/#slots,astro 7.1.6,active,2026-08-13
14,Components,Colocate component styles,Scoped styles in component file,<style> in same .astro file,Separate CSS files for component styles,<style> .card { } </style>,import './Card.css',Low,,astro 7.1.6,active,2026-08-13
15,Styling,Use scoped styles by default,Astro scopes styles to component automatically,<style> for component-specific styles,Global styles for everything,<style> h1 { } </style> (scoped),<style is:global> for everything,Medium,https://docs.astro.build/en/guides/styling/#scoped-styles,astro 7.1.6,active,2026-08-13
16,Styling,Use is:global sparingly,Global styles only when truly needed,is:global for base styles or overrides,is:global for component styles,<style is:global> body { } </style>,<style is:global> .card { } </style>,Medium,,astro 7.1.6,active,2026-08-13
17,Styling,Integrate Tailwind 4 through Vite,The Astro CLI configures Tailwind 4 with the official Vite plugin,Use astro add tailwind or configure @tailwindcss/vite,Add the deprecated @astrojs/tailwind integration,npx astro add tailwind,@astrojs/tailwind,Low,https://docs.astro.build/en/guides/styling/#tailwind,astro 7.1.6,active,2026-08-13
18,Styling,Use CSS variables for theming,Define tokens in :root,CSS custom properties for themes,Hardcoded colors everywhere,:root { --primary: #3b82f6; },color: #3b82f6; everywhere,Medium,,astro 7.1.6,active,2026-08-13
19,Data,Fetch in frontmatter,Data fetching in component frontmatter,Top-level await in frontmatter,useEffect for initial data,const data = await fetch(url),client-side fetch on mount,High,https://docs.astro.build/en/guides/data-fetching/,astro 7.1.6,active,2026-08-13
20,Data,Use Astro.glob for local files,Import multiple local files,Astro.glob for markdown/data files,Manual imports for each file,const posts = await Astro.glob('./posts/*.md'),import post1; import post2;,Medium,,astro 7.1.6,active,2026-08-13
21,Data,Prefer content collections over glob,Type-safe collections for structured content,getCollection() for blog/docs,Astro.glob for structured content,await getCollection('blog'),await Astro.glob('./blog/*.md'),High,https://docs.astro.build/en/guides/content-collections/,astro 7.1.6,active,2026-08-13
22,Data,Use environment variables correctly,Import.meta.env for env vars,PUBLIC_ prefix for client vars,Expose secrets to client,import.meta.env.PUBLIC_API_URL,import.meta.env.SECRET in client,High,https://docs.astro.build/en/guides/environment-variables/,astro 7.1.6,active,2026-08-13
23,Performance,Preload critical assets,Use link preload for important resources,Preload fonts above-fold images,No preload hints,"<link rel=""preload"" href=""font.woff2"" as=""font"">",No preload for critical assets,Medium,,astro 7.1.6,active,2026-08-13
24,Performance,Optimize images with astro:assets,Built-in image optimization,<Image /> component for optimization,<img> for local images,import { Image } from 'astro:assets';,"<img src=""./image.jpg"">",High,https://docs.astro.build/en/guides/images/,astro 7.1.6,active,2026-08-13
25,Performance,Use picture for responsive images,Multiple formats and sizes,<Picture /> for art direction,Single image size for all screens,<Picture /> with multiple sources,<Image /> with single size,Medium,,astro 7.1.6,active,2026-08-13
26,Performance,Lazy load below-fold content,Defer loading non-critical content,loading=lazy for images client:visible for components,Load everything immediately,"<img loading=""lazy"">",No lazy loading,Medium,,astro 7.1.6,active,2026-08-13
27,Performance,Minimize client directives,Each directive adds JS bundle,Audit client: usage regularly,Sprinkle client:load everywhere,Only interactive components hydrated,Every component with client:load,High,https://docs.astro.build/en/reference/directives-reference/#client-directives,astro 7.1.6,active,2026-08-13
28,ViewTransitions,Use ClientRouter for client-side transitions,Enable Astro client-side routing and transition fallbacks with the current component,<ClientRouter /> in the shared head,Use removed <ViewTransitions />,import { ClientRouter } from 'astro:transitions';,<ViewTransitions />,Medium,https://docs.astro.build/en/guides/view-transitions/,astro 7.1.6,active,2026-08-13
29,ViewTransitions,Use transition:name,Named elements for morphing,transition:name for persistent elements,Unnamed transitions,"<header transition:name=""header"">",<header> without name,Low,,astro 7.1.6,active,2026-08-13
30,ViewTransitions,Handle transition:persist,Keep state across navigations,transition:persist for media players,Re-initialize on every navigation,"<video transition:persist id=""player"">",Video restarts on navigation,Medium,,astro 7.1.6,active,2026-08-13
31,ViewTransitions,Add fallback for no-JS,Graceful degradation,Content works without JS,Require ClientRouter for basic navigation,Static content accessible,Broken without client-side routing JS,High,https://docs.astro.build/en/guides/view-transitions/,astro 7.1.6,active,2026-08-13
32,SEO,Use a shared head component,Centralize title canonical and metadata without assuming a built-in SEO component,Reusable project Head component or explicit head tags,No metadata or an undocumented built-in SEO API,"<Head title={title} description={description} />","<SEO title={title} /> // package not installed",High,https://docs.astro.build/en/basics/astro-components/,astro 7.1.6,active,2026-08-13
33,SEO,Generate sitemap,Automatic sitemap generation,@astrojs/sitemap integration,Manual sitemap maintenance,npx astro add sitemap,Hand-written sitemap.xml,Medium,https://docs.astro.build/en/guides/integrations-guide/sitemap/,astro 7.1.6,active,2026-08-13
34,SEO,Add RSS feed for content,RSS for blogs and content sites,@astrojs/rss for feed generation,No RSS feed,rss() helper in pages/rss.xml.js,No feed for blog,Low,https://docs.astro.build/en/guides/rss/,astro 7.1.6,active,2026-08-13
35,SEO,Use canonical URLs,Prevent duplicate content issues,Astro.url for canonical generation,No canonical tags,"<link rel=""canonical"" href={Astro.url}>",No canonical tags,Medium,,astro 7.1.6,active,2026-08-13
36,Integrations,Use official integrations,Astro's integration system,npx astro add for integrations,Manual configuration,npx astro add react,Manual React setup,Medium,https://docs.astro.build/en/guides/integrations-guide/,astro 7.1.6,active,2026-08-13
37,Integrations,Configure integrations in astro.config,Centralized configuration,Supported integrations in the integrations array,Scattered configuration,"integrations: [react(), sitemap()]",Multiple config files,Low,,astro 7.1.6,active,2026-08-13
38,Integrations,Use adapter for deployment,Platform-specific adapters,Correct adapter for host,Wrong or no adapter,@astrojs/vercel for Vercel,No adapter for SSR,High,https://docs.astro.build/en/guides/deploy/,astro 7.1.6,active,2026-08-13
39,TypeScript,Enable TypeScript,Type safety for Astro projects,tsconfig.json with astro types,No TypeScript,Astro TypeScript template,JavaScript only,Medium,https://docs.astro.build/en/guides/typescript/,astro 7.1.6,active,2026-08-13
40,TypeScript,Type component props,Define prop interfaces,Props interface in frontmatter,Untyped props,interface Props { title: string },No props typing,Medium,,astro 7.1.6,active,2026-08-13
41,TypeScript,Use strict mode,Catch errors early,strict: true in tsconfig,Loose TypeScript config,strictest template,base template,Low,,astro 7.1.6,active,2026-08-13
42,Markdown,Use MDX for components,Components in markdown content,@astrojs/mdx for interactive docs,Plain markdown with workarounds,<Component /> in .mdx,HTML in .md files,Medium,https://docs.astro.build/en/guides/integrations-guide/mdx/,astro 7.1.6,active,2026-08-13
43,Markdown,Configure markdown plugins,Extend markdown capabilities,remarkPlugins rehypePlugins in config,Manual HTML for features,remarkPlugins: [remarkToc],Manual TOC in every post,Low,,astro 7.1.6,active,2026-08-13
44,Markdown,Use frontmatter for metadata,Structured post metadata,Frontmatter with typed schema,Inline metadata,title date in frontmatter,# Title as first line,Medium,,astro 7.1.6,active,2026-08-13
45,API,Use API routes for endpoints,Server endpoints in pages/api,pages/api/[endpoint].ts for APIs,External API for simple endpoints,pages/api/posts.json.ts,Separate Express server,Medium,https://docs.astro.build/en/guides/endpoints/,astro 7.1.6,active,2026-08-13
46,API,Return proper responses,Use Response object,new Response() with headers,Plain objects,return new Response(JSON.stringify(data)),return data,Medium,,astro 7.1.6,active,2026-08-13
47,API,Handle methods correctly,Export named method handlers,export GET POST handlers,Single default export,export const GET = async () => {},export default async () => {},Low,,astro 7.1.6,active,2026-08-13
48,Security,Sanitize user content,Prevent XSS in dynamic content,set:html only for trusted or sanitized content,set:html with user input,<Fragment set:html={sanitized} />,<div set:html={userInput} />,High,https://docs.astro.build/en/reference/directives-reference/#sethtml,astro 7.1.6,active,2026-08-13
49,Security,Use HTTPS in production,Deploy behind a host or proxy that terminates TLS,HTTPS for all production sites,HTTP in production,https://example.com,http://example.com,High,https://docs.astro.build/en/guides/deploy/,astro 7.1.6,active,2026-08-13
50,Security,Validate API input,Check and sanitize all input,Schema validation for endpoint input,Trust all input,const body = schema.parse(data),const body = await request.json(),High,https://docs.astro.build/en/guides/endpoints/,astro 7.1.6,active,2026-08-13
51,Build,Mix prerendered and on-demand routes,Static output supports selected server-rendered routes when an adapter is configured,Keep static output and set prerender false per dynamic route,Use removed output: 'hybrid',export const prerender = false,output: 'hybrid',Medium,https://docs.astro.build/en/guides/on-demand-rendering/,astro 7.1.6,active,2026-08-13
52,Build,Analyze bundle size,Monitor JS bundle impact,Build output shows bundle sizes,Ignore bundle growth,Check astro build output,No size monitoring,Medium,,astro 7.1.6,active,2026-08-13
53,Build,Configure built-in prefetch,Preload likely next pages with Astro's built-in prefetch configuration,Set prefetch true or use data-astro-prefetch,Install the removed prefetch integration,prefetch: true,npx astro add prefetch,Low,https://docs.astro.build/en/guides/prefetch/,astro 7.1.6,active,2026-08-13