[
{
"No": "1",
"Category": "Architecture",
"Guideline": "Use Islands Architecture",
"Description": "Astro's partial hydration only loads JS for interactive components",
"Do": "Interactive components with client directives",
"Don't": "Hydrate entire page like traditional SPA",
"Code Good": "<Counter client:load />",
"Code Bad": "Everything as client component",
"Severity": "High",
"Docs URL": "https://docs.astro.build/en/concepts/islands/"
},
{
"No": "2",
"Category": "Architecture",
"Guideline": "Default to zero JS",
"Description": "Astro ships zero JS by default - add only when needed",
"Do": "Static components without client directive",
"Don't": "Add client:load to everything",
"Code Good": "<Header /> (static)",
"Code Bad": "<Header client:load /> (unnecessary)",
"Severity": "High",
"Docs URL": "https://docs.astro.build/en/basics/astro-components/"
},
{
"No": "3",
"Category": "Architecture",
"Guideline": "Choose right client directive",
"Description": "Different directives for different hydration timing",
"Do": "client:visible for below-fold client:idle for non-critical",
"Don't": "client:load for everything",
"Code Good": "<Comments client:visible />",
"Code Bad": "<Comments client:load />",
"Severity": "Medium",
"Docs URL": "https://docs.astro.build/en/reference/directives-reference/#client-directives"
},
{
"No": "4",
"Category": "Architecture",
"Guideline": "Use content collections",
"Description": "Type-safe content management for blogs docs",
"Do": "Content collections for structured content",
"Don't": "Loose markdown files without schema",
"Code Good": "const posts = await getCollection('blog')",
"Code Bad": "import.meta.glob('./posts/*.md')",
"Severity": "High",
"Docs URL": "https://docs.astro.build/en/guides/content-collections/"
},
{
"No": "5",
"Category": "Architecture",
"Guideline": "Define collection schemas",
"Description": "Zod schemas for content validation",
"Do": "Schema with required fields and types",
"Don't": "No schema validation",
"Code Good": "defineCollection({ schema: z.object({...}) })",
"Code Bad": "defineCollection({})",
"Severity": "High",
"Docs URL": "https://docs.astro.build/en/guides/content-collections/#defining-a-collection-schema"
},
{
"No": "6",
"Category": "Routing",
"Guideline": "Use file-based routing",
"Description": "Create routes by adding .astro files in pages/",
"Do": "pages/ directory for routes",
"Don't": "Manual route configuration",
"Code Good": "src/pages/about.astro",
"Code Bad": "Custom router setup",
"Severity": "Medium",
"Docs URL": "https://docs.astro.build/en/basics/astro-pages/"
},
{
"No": "7",
"Category": "Routing",
"Guideline": "Dynamic routes with brackets",
"Description": "Use [param] for dynamic routes",
"Do": "Bracket notation for params",
"Don't": "Query strings for dynamic content",
"Code Good": "pages/blog/[slug].astro",
"Code Bad": "pages/blog.astro?slug=x",
"Severity": "Medium",
"Docs URL": "https://docs.astro.build/en/guides/routing/#dynamic-routes"
},
{
"No": "8",
"Category": "Routing",
"Guideline": "Use getStaticPaths for SSG",
"Description": "Generate static pages at build time",
"Do": "getStaticPaths for known dynamic routes",
"Don't": "Fetch at runtime for static content",
"Code Good": "export async function getStaticPaths() { return [...] }",
"Code Bad": "No getStaticPaths with dynamic route",
"Severity": "High",
"Docs URL": "https://docs.astro.build/en/reference/api-reference/#getstaticpaths"
},
{
"No": "9",
"Category": "Routing",
"Guideline": "Enable SSR when needed",
"Description": "Server-side rendering for dynamic content",
"Do": "output: 'server' or 'hybrid' for dynamic",
"Don't": "SSR for purely static sites",
"Code Good": "export const prerender = false;",
"Code Bad": "SSR for static blog",
"Severity": "Medium",
"Docs URL": "https://docs.astro.build/en/guides/server-side-rendering/"
},
{
"No": "10",
"Category": "Components",
"Guideline": "Keep .astro for static",
"Description": "Use .astro components for static content",
"Do": "Astro components for layout structure",
"Don't": "React/Vue for static markup",
"Code Good": "<Layout><slot /></Layout>",
"Code Bad": "<ReactLayout>{children}</ReactLayout>",
"Severity": "High",
"Docs URL": ""
},
{
"No": "11",
"Category": "Components",
"Guideline": "Use framework components for interactivity",
"Description": "React Vue Svelte for complex interactivity",
"Do": "Framework component with client directive",
"Don't": "Astro component with inline scripts",
"Code Good": "<ReactCounter client:load />",
"Code Bad": "<script> in .astro for complex state",
"Severity": "Medium",
"Docs URL": "https://docs.astro.build/en/guides/framework-components/"
},
{
"No": "12",
"Category": "Components",
"Guideline": "Pass data via props",
"Description": "Astro components receive props in frontmatter",
"Do": "Astro.props for component data",
"Don't": "Global state for simple data",
"Code Good": "const { title } = Astro.props;",
"Code Bad": "Import global store",
"Severity": "Low",
"Docs URL": "https://docs.astro.build/en/basics/astro-components/#component-props"
},
{
"No": "13",
"Category": "Components",
"Guideline": "Use slots for composition",
"Description": "Named and default slots for flexible layouts",
"Do": "<slot /> for child content",
"Don't": "Props for HTML content",
"Code Good": "<slot name=\"header\" />",
"Code Bad": "<Component header={<div>...</div>} />",
"Severity": "Medium",
"Docs URL": "https://docs.astro.build/en/basics/astro-components/#slots"
},
{
"No": "14",
"Category": "Components",
"Guideline": "Colocate component styles",
"Description": "Scoped styles in component file",
"Do": "<style> in same .astro file",
"Don't": "Separate CSS files for component styles",
"Code Good": "<style> .card { } </style>",
"Code Bad": "import './Card.css'",
"Severity": "Low",
"Docs URL": ""
},
{
"No": "15",
"Category": "Styling",
"Guideline": "Use scoped styles by default",
"Description": "Astro scopes styles to component automatically",
"Do": "<style> for component-specific styles",
"Don't": "Global styles for everything",
"Code Good": "<style> h1 { } </style> (scoped)",
"Code Bad": "<style is:global> for everything",
"Severity": "Medium",
"Docs URL": "https://docs.astro.build/en/guides/styling/#scoped-styles"
},
{
"No": "16",
"Category": "Styling",
"Guideline": "Use is:global sparingly",
"Description": "Global styles only when truly needed",
"Do": "is:global for base styles or overrides",
"Don't": "is:global for component styles",
"Code Good": "<style is:global> body { } </style>",
"Code Bad": "<style is:global> .card { } </style>",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "17",
"Category": "Styling",
"Guideline": "Integrate Tailwind properly",
"Description": "Use @astrojs/tailwind integration",
"Do": "Official Tailwind integration",
"Don't": "Manual Tailwind setup",
"Code Good": "npx astro add tailwind",
"Code Bad": "Manual PostCSS config",
"Severity": "Low",
"Docs URL": "https://docs.astro.build/en/guides/integrations-guide/tailwind/"
},
{
"No": "18",
"Category": "Styling",
"Guideline": "Use CSS variables for theming",
"Description": "Define tokens in :root",
"Do": "CSS custom properties for themes",
"Don't": "Hardcoded colors everywhere",
"Code Good": ":root { --primary: #3b82f6; }",
"Code Bad": "color: #3b82f6; everywhere",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "19",
"Category": "Data",
"Guideline": "Fetch in frontmatter",
"Description": "Data fetching in component frontmatter",
"Do": "Top-level await in frontmatter",
"Don't": "useEffect for initial data",
"Code Good": "const data = await fetch(url)",
"Code Bad": "client-side fetch on mount",
"Severity": "High",
"Docs URL": "https://docs.astro.build/en/guides/data-fetching/"
},
{
"No": "20",
"Category": "Data",
"Guideline": "Use Astro.glob for local files",
"Description": "Import multiple local files",
"Do": "Astro.glob for markdown/data files",
"Don't": "Manual imports for each file",
"Code Good": "const posts = await Astro.glob('./posts/*.md')",
"Code Bad": "import post1; import post2;",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "21",
"Category": "Data",
"Guideline": "Prefer content collections over glob",
"Description": "Type-safe collections for structured content",
"Do": "getCollection() for blog/docs",
"Don't": "Astro.glob for structured content",
"Code Good": "await getCollection('blog')",
"Code Bad": "await Astro.glob('./blog/*.md')",
"Severity": "High",
"Docs URL": ""
},
{
"No": "22",
"Category": "Data",
"Guideline": "Use environment variables correctly",
"Description": "Import.meta.env for env vars",
"Do": "PUBLIC_ prefix for client vars",
"Don't": "Expose secrets to client",
"Code Good": "import.meta.env.PUBLIC_API_URL",
"Code Bad": "import.meta.env.SECRET in client",
"Severity": "High",
"Docs URL": "https://docs.astro.build/en/guides/environment-variables/"
}
]
