Cline

# Component Design Standards for Astro This document outlines the component design standards for Astro projects. These standards promote maintainability, reusability, performance, and a consistent development experience across teams. It leverages the latest Astro features and best practices. ## 1. Component Architecture ### 1.1 Modularity and Reusability **Standard:** Components should be designed as independent, reusable units of functionality. **Do This:** * Create components with a single, well-defined responsibility. * Favor composition over inheritance. Use Astro's component slot and props functionalities to allow customization. * Store reusable components in a dedicated directory (e.g., "src/components"). **Don't Do This:** * Create monolithic components that handle multiple unrelated tasks. * Duplicate code across components. Extract common logic into shared components or utility functions. **Why:** Modular components are easier to understand, test, and maintain. Reusable components reduce code duplication and development time. **Example:** """astro // src/components/Button.astro --- interface Props { variant?: 'primary' | 'secondary'; size?: 'small' | 'medium' | 'large'; text: string; onClick?: () => void; } const { variant = 'primary', size = 'medium', text, onClick } = Astro.props; const buttonClasses = { primary: 'bg-blue-500 hover:bg-blue-700 text-white', secondary: 'bg-gray-200 hover:bg-gray-300 text-gray-800 border border-gray-400', }; const sizeClasses = { small: 'px-2 py-1 text-sm', medium: 'px-4 py-2 text-base', large: 'px-6 py-3 text-lg', }; const selectedVariantClasses = buttonClasses[variant]; const selectedSizeClasses = sizeClasses[size]; --- <button class:list={[selectedVariantClasses, selectedSizeClasses, 'font-bold rounded']}> {text} </button> """ """astro // src/pages/index.astro --- import Button from '../components/Button.astro'; --- <Button variant="primary" size="medium" text="Click me!" onClick={() => alert('Clicked!')} /> <Button variant="secondary" size="small" text="Cancel" /> """ ### 1.2 Component Grouping **Standard:** Group related components into directories based on feature or domain. **Do This:** * Create directories for specific features or sections of the application (e.g., "src/components/blog", "src/components/ui"). * Include an "index.js" or "index.ts" file in each directory to export all components from that directory. **Don't Do This:** * Dump all components into a single "src/components" directory without any organization. * Create deeply nested directory structures that are difficult to navigate. **Why:** Logical component grouping improves code organization, maintainability, and discoverability. **Example:** """ src/components/ ├── blog/ │ ├── ArticleCard.astro │ ├── ArticleList.astro │ └── index.ts // Exports ArticleCard and ArticleList ├── ui/ │ ├── Button.astro │ ├── Input.astro │ └── index.ts // Exports Button and Input └── index.ts // Exports all components blog and ui """ """typescript // src/components/blog/index.ts export { default as ArticleCard } from './ArticleCard.astro'; export { default as ArticleList } from './ArticleList.astro'; """ """typescript // src/components/index.ts export * from './blog'; export * from './ui'; """ ### 1.3 Data Fetching Responsibilities **Standard:** Limit component data fetching responsibilities. **Do This:** * Fetch data in layouts or pages and pass the data as props to components. This decouples components from specific data sources. * Use [Astro.glob](https://docs.astro.build/en/reference/api-reference/#astroglob) or the [Content Collections API](https://docs.astro.build/en/guides/content-collections/) for data fetching within "src/pages" and "src/layouts". * When absolutely necessary to fetch data within a component, isolate the data fetching logic into a separate helper function or custom hook. **Don't Do This:** * Perform complex data transformations or business logic within components. * Fetch the same data multiple times in different components. **Why:** Decoupling data fetching improves component reusability and testability. Centralized data fetching also improves performance by minimizing redundant requests. **Example:** """astro // src/pages/blog.astro --- import ArticleCard from '../components/ArticleCard.astro'; import { getCollection } from 'astro:content'; const articles = await getCollection('blog'); --- <main> <h1>Blog</h1> <ul> {articles.map((article) => ( <li> <ArticleCard article={article} /> </li> ))} </ul> </main> """ """astro // src/components/ArticleCard.astro --- interface Props { article: { slug: string; data: { title: string; description: string; }; }; } const { article } = Astro.props; --- <a href={"/blog/${article.slug}"}> <h2>{article.data.title}</h2> <p>{article.data.description}</p> </a> """ ## 2. Component Implementation Details ### 2.1 Prop Types **Standard:** Define explicit prop types for all components using TypeScript. **Do This:** * Create an "interface" named "Props" to define the types of all props. * Enforce required props using TypeScript's type system. * Provide default prop values for optional props where appropriate. * Leverage [Astro.props](https://docs.astro.build/en/reference/api-reference/#astroprops) for type safety **Don't Do This:** * Skip prop type definitions. * Use "any" or "unknown" for prop types. * Define default prop values using JavaScript's "||" operator, which can lead to unexpected behavior with falsy values. **Why:** Explicit prop types improve code readability, prevent runtime errors, and improve the developer experience. **Example:** """astro // src/components/Alert.astro --- interface Props { type: 'success' | 'warning' | 'error' | 'info'; message: string; closable?: boolean; } const { type, message, closable = false } = Astro.props; const alertClasses = { success: 'bg-green-100 border-green-400 text-green-700', warning: 'bg-yellow-100 border-yellow-400 text-yellow-700', error: 'bg-red-100 border-red-400 text-red-700', info: 'bg-blue-100 border-blue-400 text-blue-700', }; const selectedClasses = alertClasses[type]; --- <div class:list={[selectedClasses, 'border rounded p-4 mb-4 flex items-center justify-between']}> <span>{message}</span> {closable && ( <button aria-label="Close"> <svg class="w-4 h-4 fill-current" viewBox="0 0 20 20"><path d="M14.348 14.849a1.2 1.2 0 0 1-1.697 0L10 11.819l-2.651 3.029a1.2 1.2 0 1 1-1.697-1.697l2.758-3.15-2.759-3.152a1.2 1.2 0 1 1 1.697-1.697L10 8.183l2.651-3.031a1.2 1.2 0 1 1 1.697 1.697l-2.758 3.152 2.758 3.15a1.2 1.2 0 0 1 0 1.698z"/></svg> </button> )} </div> """ ### 2.2 Component Styling **Standard:** Use a consistent styling approach across all components. **Do This:** * Favor component-scoped styles using Astro's built-in CSS support. * Use a CSS preprocessor (e.g., Sass, Less) for complex styling requirements. * Use a utility-first CSS framework (e.g., Tailwind CSS) for consistent styling and rapid development. Install Tailwind using "astro add tailwind". * For dynamic styling, use the ":global()" selector sparingly and only when necessary for interacting with third-party libraries or CSS frameworks. * Consider using CSS variables for theming. **Don't Do This:** * Use inline styles directly in the HTML templates. * Use global styles that can conflict with other components. * Mix different styling approaches within the same project. **Why:** Consistent styling improves code maintainability, reduces visual inconsistencies, and streamlines the development process. **Example (Tailwind CSS):** """astro // src/components/Card.astro --- interface Props { title: string; description: string; } const { title, description } = Astro.props; --- <div class="bg-white rounded-lg shadow-md p-4"> <h2 class="text-xl font-bold mb-2">{title}</h2> <p class="text-gray-700">{description}</p> </div> """ ### 2.3 Component State **Standard:** Minimize component state and use it judiciously. **Do This:** * Prefer stateless functional components whenever possible. * When state is necessary, use Astro's client-side directives ("client:load", "client:idle", "client:visible", "client:media") combined with a front-end framework like Solid, React or Vue to manage component state. * Consider using a global state management library (e.g., Context API with React, Zustand or Jotai) for complex application state. **Don't Do This:** * Store unnecessary data in component state. * Mutate component state directly without using the appropriate setter functions or framework mechanisms. * Overuse global state management for simple component-specific state. **Why:** Minimizing component state improves performance and reduces complexity. Using appropriate state management techniques improves data consistency and prevents unexpected side effects. **Example (SolidJS with Astro):** """astro --- // src/components/Counter.astro --- <Counter client:visible /> <script> import { render } from 'solid-js/web'; import { createSignal } from 'solid-js'; function Counter() { const [count, setCount] = createSignal(0); return ( <div> <p>Count: {count()}</p> <button onClick={() => setCount(count() + 1)}>Increment</button> </div> ); } render(Counter, document.querySelector('counter')) </script> """ ### 2.4 Naming Conventions **Standard:** Follow consistent naming conventions for components and props. **Do This:** * Use PascalCase for component filenames (e.g., "MyComponent.astro"). * Use camelCase for prop names (e.g., "myProp", "onClick"). * Use descriptive and concise names that clearly indicate the component's purpose. * Use plural names for components that display a list of items (e.g., "ArticleList"). **Don't Do This:** * Use inconsistent naming conventions across the project. * Use abbreviations or acronyms that are not widely understood. * Use generic names that do not accurately reflect the component's functionality. **Why:** Consistent naming improves code readability and makes it easier to understand the purpose of components and props. ## 3. Performance Optimization ### 3.1 Component Hydration **Standard:** Use Astro's partial hydration features judiciously to optimize performance. **Do This:** * Use the "client:" directives ("client:load", "client:idle", "client:visible", "client:media") to control when components are hydrated. * Start with "client:idle" or "client:visible" for most interactive components to defer hydration until the browser is idle or the component is visible in the viewport. * Use "client:load" only for components that are critical to the initial user experience. * Consider using "<astro-island>" for even more granular control over hydration. **Don't Do This:** * Hydrate all components on page load, which can negatively impact performance. * Use "client:only" unless you are absolutely sure that the component will only ever be rendered on the client-side. **Why:** Partial hydration significantly improves page load performance by only hydrating the components that need to be interactive. **Example:** """astro // src/components/InteractiveComponent.astro --- // This component will be hydrated when it becomes visible in the viewport. --- <div client:visible> {/* Interactive content here */} </div> """ ### 3.2 Image Optimization **Standard:** Optimize images for performance using Astro's built-in image optimization features or a third-party library. **Do This:** * Use the "<Image />" component from "@astrojs/image" to automatically optimize images. * Specify the "width" and "height" props for all images to prevent layout shifts. * Use the "format" prop to convert images to modern formats like WebP or AVIF. * Use the "quality" prop to control the level of compression. * Consider using a CDN (Content Delivery Network) to serve images from a location closer to the user. **Don't Do This:** * Use large, unoptimized images directly in the HTML templates. * Skip specifying the "width" and "height" props for images. * Serve images from the same server as the application, which can negatively impact performance. **Why:** Image optimization reduces image file sizes, improves page load times, and enhances the user experience. **Example:** """astro // src/components/HeroImage.astro --- import { Image } from '@astrojs/image/components'; import heroImage from '../assets/hero.jpg'; --- <Image src={heroImage} alt="Hero Image" width={1200} height={600} format="webp" quality={80} /> """ ### 3.3 Lazy Loading **Standard:** Use lazy loading for images and other resources that are not immediately visible in the viewport. **Do This:** * Use the "loading="lazy"" attribute for images to defer loading until they are near the viewport. * Consider using a third-party library or custom implementation for lazy loading other types of resources, such as iframes or videos. **Don't Do This:** * Lazy load resources that are above the fold or critical to the initial user experience. **Why:** Lazy loading improves page load performance by deferring the loading of non-critical resources until they are needed. **Example:** """astro <img src="/path/to/image.jpg" alt="Description of image" loading="lazy"> """ ## 4. Security Considerations ### 4.1 Input Sanitization **Standard:** Sanitize user inputs in components to prevent cross-site scripting (XSS) attacks. **Do This:** * Use a sanitization library (e.g., DOMPurify) to sanitize user inputs before rendering them in the HTML templates. * Escape HTML entities in user inputs using Astro's built-in templating engine features. **Don't Do This:** * Render user inputs directly in the HTML templates without any sanitization or escaping. **Why:** Input sanitization prevents malicious code from being injected into the application, which can compromise user data and security. **Example:** """astro // Example using DOMPurify --- import DOMPurify from 'dompurify'; interface Props { userInput: string; } const { userInput } = Astro.props; // Sanitize the user input const sanitizedInput = DOMPurify.sanitize(userInput); --- <p set:html={sanitizedInput}></p> """ ### 4.2 Avoid Exposing Sensitive Data **Standard:** Avoid exposing sensitive data in client-side components. **Do This:** * Store sensitive data on the server-side. * Use environment variables to store API keys and other sensitive configuration values. Utilize the "import.meta.env" to access environment variables for the build **Don't Do This:** * Include API keys or other sensitive data directly in client-side components. * Expose sensitive data in the HTML source code. **Why:** Protecting sensitive data prevents unauthorized access and protects user privacy. **Example:** """astro --- // Access the API key from an environment variable const apiKey = import.meta.env.PUBLIC_API_KEY; --- // Use the API key to fetch data from the server """ ## 5. Testing ### 5.1 Unit Testing **Standard:** Write unit tests for individual components to ensure they function correctly. **Do This:** * Use a testing framework (e.g., Jest, Mocha) to write unit tests. * Test the component's props, state, and rendering behavior. * Use mocking to isolate components from external dependencies. **Don't Do This:** * Skip unit tests for complex components. * Write unit tests that are tightly coupled to the component's implementation details. **Why:** Unit tests improve code quality, prevent regressions, and make it easier to refactor code. ### 5.2 Component Integration tests **Standard:** Write integration tests to ensure components interact correctly in a larger system. **Do This:** * Use testing libraries (e.g., Playwright, Cypress) for end-to-end tests to verify that components render and function correctly in the browser. * Verify that data is passed to components in an intended manor. **Don't Do This:** * Neglect to test component collaboration. * Write only unit tests, and don't test real life rendering behavior. **Why:** Unit and Integration testing are essential for ensuring that components work in intended ways. ## 6. Documentation ### 6.1 Component Documentation **Standard:** Document component usage and functionality clearly. **Do This:** * Include a JSDoc-style comment block at the top of each component file that describes the component's purpose, props, and usage. * Use a documentation generator (e.g., Storybook) to create a living style guide for the component library. **Don't Do This:** * Skip documenting component usage and functionality * Make hard to maintain documentation. Keep documentation with the components themselves. **Why:** Documentation improves code understandability, facilitates collaboration, and makes it easier to maintain the component library. **Example:** """astro /** * A reusable button component. * * @param {string} text - The text to display on the button. * @param {'primary' | 'secondary'} variant - The button variant (optional, defaults to 'primary'). * @param {() => void} onClick - The function to call when the button is clicked (optional). */ interface Props { text: string; variant?: 'primary' | 'secondary'; onClick?: () => void; } """ These coding standards are a living document and should be updated as new versions of Astro are released and new best practices emerge. By following these standards, development teams can build high-quality, maintainable, and performant Astro applications.

# Performance Optimization Standards for Astro This document outlines the coding standards and best practices for performance optimization within Astro projects. Following these guidelines will lead to faster, more responsive, and resource-efficient web applications. These standards are tailored to the latest Astro features and ecosystem. ## 1. Architectural Considerations Choosing the correct architecture and approach upfront is critical for performance. ### 1.1. Islands Architecture **Standard:** Leverage Astro's Islands Architecture to minimize JavaScript execution on the client. Each interactive component (island) should be isolated and loaded only when needed. **Why:** Islands Architecture reduces the amount of JavaScript that needs to be downloaded, parsed, and executed by the browser, leading to faster initial load times and improved Time to Interactive (TTI). **Do This:** * Identify genuinely interactive components that require client-side JavaScript. * Render static content as HTML without client-side hydration. * Use Astro's "client:" directives ("client:load", "client:visible", "client:idle", "client:only") to control when islands are loaded. **Don't Do This:** * Hydrate entire pages or large sections of static content with client-side JavaScript. * Load all JavaScript upfront, regardless of whether it's needed. * Use "client:load" for components that are initially below-the-fold. It will improve the initial paint, but delay the Time to Interactive. **Example:** """astro --- // MyComponent.astro --- <div class="my-component"> <p>This is a static paragraph.</p> <MyInteractiveComponent client:visible /> </div> """ """jsx // MyInteractiveComponent.jsx (or .tsx) import React, { useState } from 'react'; const MyInteractiveComponent = () => { const [count, setCount] = useState(0); return ( <div> <p>Count: {count}</p> <button onClick={() => setCount(count + 1)}>Increment</button> </div> ); }; export default MyInteractiveComponent; """ **Anti-Pattern:** Hydrating the entire "MyComponent" Astro page just to make the button interactive, even though the paragraph is entirely static content. ### 1.2. Static Site Generation (SSG) **Standard:** Pre-render as much content as possible during build time (Static Site Generation). **Why:** SSG delivers static HTML files to the browser, eliminating server-side rendering overhead and resulting in faster page loads. **Do This:** * Fetch data and generate HTML pages during the build process for content that doesn't require real-time updates. * Use Astro's built-in support for Markdown and MDX to create content-rich static sites. **Don't Do This:** * Use Server-Side Rendering (SSR) unnecessarily for content that can be pre-rendered. * Make unoptimised network requests at runtime. **Example:** """astro --- // src/pages/blog/[slug].astro import { getEntryBySlug } from 'astro:content'; export async function getStaticPaths() { const blogEntries = await getCollection('blog'); return blogEntries.map(entry => ({ params: { slug: entry.slug }, props: { entry }, })); } const { entry } = Astro.props; const { Content } = await entry.render(); --- <Layout title={entry.data.title}> <h1>{entry.data.title}</h1> <Content /> </Layout> """ ### 1.3. Content Delivery Network (CDN) **Standard:** Utilize a CDN to serve static assets (images, CSS, JavaScript) from geographically distributed servers. **Why:** CDNs reduce latency by serving content from a server closer to the user's location. **Do This:** * Integrate Astro with a CDN provider like Cloudflare, Netlify CDN, or AWS CloudFront. * Configure your CDN to cache static assets effectively. **Don't Do This:** * Serve static assets directly from your origin server without caching. **Example:** While Astro doesn't directly configure your CDN; it provides a build output that's easily deployed to a CDN. Configure your deployment platform (Netlify, Vercel, Cloudflare Pages, etc.) to leverage its CDN capabilities. For example, on Netlify: 1. Deploy your Astro site to Netlify. 2. Netlify automatically uses its global CDN to serve your static assets. 3. Configure Cache-Control headers within Netlify's settings or within the "netlify.toml" file for detailed cache management. ### 1.4 Routing Strategy **Standard:** Adopt an optimised routing strategy. **Why:** An efficient routing approach ensures swift navigation and content delivery. **Do This:** * Employ dynamic routing for pages with changeable content. * Implement prefetching for anticipated navigation paths. * Strategically utilize client-side routing to achieve seamless transitions. **Don't Do This:** * Overcomplicate routing with excessive redirects. * Rely on solely server-side routing for every internal link. **Example:** """astro // src/pages/products/[id].astro export async function getStaticPaths() { const products = await fetchProductsFromDatabase(); return products.map(product => ({ params: { id: product.id }, })); } const { id } = Astro.params; const product = await fetchProductDetails(id); """ ## 2. Component Optimization Efficient components are critical to overall performance. ### 2.1. Minimize Client-Side JavaScript **Standard:** Reduce the amount of client-side JavaScript. **Why:** Too much JavaScript can significantly slow down page load times and degrade user experience, especially on mobile devices. **Do This:** * Use Astro components for the majority of your UI, which render to HTML by default. * Defer or lazy-load JavaScript only when necessary for interactivity. * Replace large libraries, with smaller, more efficient alternatives. **Don't Do This:** * Import entire JavaScript libraries when only a small portion is needed. * Rely on Client-Side-Rendering (CSR) when SSG or SSR is appropriate. * Use jQuery. **Example:** """astro --- // Bad: Importing the entire Lodash library // import _ from 'lodash'; // Good: Importing only the functions you need import debounce from 'lodash-es/debounce'; const debouncedFunction = debounce(() => { console.log('Debounced function called'); }, 300); --- <input type="text" on:input={debouncedFunction} /> """ ### 2.2. Efficient Data Fetching **Standard:** Optimize data fetching to minimize network requests and reduce data transfer. **Why:** Slow or inefficient data fetching can be a major performance bottleneck. **Do This:** * Use GraphQL or similar technologies to fetch only the data you need. * Implement caching strategies to avoid redundant requests. * Use Astro's "getStaticPaths" to pre-render pages at build time. * Utilize "Astro.fetchContent()" and similar mechanisms to hydrate components directly from Markdown or MDX. **Don't Do This:** * Make multiple unnecessary requests for the same data. * Fetch large amounts of data that are not needed on the page. **Example:** """astro --- // src/pages/blog.astro import { getCollection } from 'astro:content'; export async function getStaticProps() { const posts = await getCollection('blog'); return { props: { posts: posts.sort((a, b) => b.data.pubDate.getTime() - a.data.pubDate.getTime()), }, }; } const { posts } = Astro.props; --- <ul> {posts.map((post) => ( <li> <a href={"/blog/${post.slug}"}>{post.data.title}</a> </li> ))} </ul> """ ### 2.3. Image Optimization **Standard:** Optimize images to reduce file size without sacrificing quality. **Why:** Large images can significantly slow down page load times. **Do This:** * Use optimized image formats like WebP or AVIF. * Resize images to the appropriate dimensions for their display size. * Use responsive images with the "<picture>" element or "srcset" attribute to serve different image sizes based on screen size. * Lazy load images using the "loading="lazy"" attribute. * Use Astro's built-in image optimization features or integrate with image optimization services. **Don't Do This:** * Use unnecessarily large images. * Serve images in unoptimized formats like BMP or TIFF. * Load all images immediately, even those that are below-the-fold. **Example:** """astro --- // Using Astro's built-in image optimization with the <Image /> component. Requires installing @astrojs/image. import { Image } from '@astrojs/image/components'; import myImage from '../assets/my-image.jpg'; --- <Image src={myImage} alt="My Image" width={600} height={400} format="webp" loading="lazy" /> """ ### 2.4 Component Reusability and Memoization **Standard:** Design components to be reusable and implement memoization techniques to prevent re-renders. **Why:** Reusable components reduce code duplication and improve maintainability. Memoization prevents unnecessary re-renders of components, improving performance. **Do This:** * Create reusable components with well-defined props. * Use "React.memo" or similar memoization techniques to prevent re-renders of pure components. * Use the "useMemo" and "useCallback" hooks in React to memoize expensive calculations and function references. **Don't Do This:** * Create tightly coupled components that are difficult to reuse. * Rely on global state excessively. * Re-render components unnecessarily when their props have not changed. **Example:** """jsx // React Component Memoization import React, { memo } from 'react'; const MyComponent = ({ data }) => { console.log('MyComponent rendered'); return ( <div> {data.map(item => ( <p key={item.id}>{item.name}</p> ))} </div> ); }; export default memo(MyComponent); """ """jsx // React useMemo and useCallback import React, { useState, useMemo, useCallback } from 'react'; function MyComponent({ items }) { const [count, setCount] = useState(0); const expensiveCalculation = useMemo(() => { console.log('Performing expensive calculation'); return items.reduce((sum, item) => sum + item.value, 0); }, [items]); const increment = useCallback(() => { setCount(c => c + 1); }, []); return ( <div> <p>Count: {count}</p> <button onClick={increment}>Increment</button> <p>Expensive Calculation: {expensiveCalculation}</p> </div> ); } export default MyComponent; """ ## 3. Code Optimization Writing efficient code is essential in Astro projects. ### 3.1. Minimize DOM Manipulation **Standard:** Reduce direct DOM manipulation. **Why:** Direct DOM manipulations are resource-intensive. Minimize or batch them for increased performance. **Do This:** * Use Virtual DOM concepts such as those offered by Preact. Memoize components so that they are only re-rendered when required. * Batch updates where needed to prevent layout thrashing. **Don't Do This:** * Directly manage DOM elements where it can be avoided. **Example:** Instead of making individual changes, group them into a single update. While this isn't direct DOM manipulation (best practice!), the principle applies to how components render, and demonstrates the benefit of batching. """js // Update multiple styles at once element.style.cssText = " color: blue; font-size: 16px; font-weight: bold; "; """ ### 3.2. Efficient JavaScript **Standard:** Use efficient JavaScript code. **Why:** Inefficient JavaScript code can lead to performance bottlenecks. **Do This:** * Avoid memory leaks by properly cleaning up event listeners and timers. * Use efficient algorithms and data structures. * Profile your code to identify and optimize performance bottlenecks. * Use the "const" keyword for variables to indicate they will not be reassigned. * Use template literals instead of string concatenation for better readability and performance. * Use arrow functions for concise and efficient function expressions. * Use array methods liek "map", "filter", and "reduce" instead of imperative loops where appropriate. **Don't Do This:** * Write inefficient or unnecessarily complex code. * Use global variables excessively. * Ignore performance warnings from your IDE or linter. **Example:** """javascript // Efficiently calculate the sum of an array of numbers const numbers = [1, 2, 3, 4, 5]; const sum = numbers.reduce((acc, num) => acc + num, 0); console.log(sum); // Output: 15 """ ### 3.3. CSS Optimization **Standard:** Optimize CSS code for performance. **Why:** Inefficient CSS can impact rendering speed and performance. **Do This:** * Minify and compress CSS files. * Remove unused CSS rules. * Use CSS Modules or similar techniques to scope CSS rules and avoid conflicts. * Avoid overly complex CSS selectors. * Use CSS variables for reusable values. * Use "transform"property instead of "top", "right", "bottom", and "left" for animations. **Don't Do This:** * Write overly specific or nested CSS selectors. * Include large, unused CSS files. * Use inline styles excessively. **Example:** """css /* Minified CSS */ body{font-family:sans-serif;margin:0}h1{color:#333} """ ### 3.4 Font Optimization **Standard:** Optimize web fonts for performance. **Why:** Web fonts can significantly impact page load times if not properly optimized. **Do This:** * Use web font formats like WOFF2. * Load fonts asynchronously using "font-display: swap;". * Use font subsets to include only the characters needed on your site. * Host fonts locally to avoid third-party dependencies. **Don't Do This:** * Use too many custom fonts. * Load fonts synchronously, blocking rendering. * Use very large font files. **Example:** """css /* Load font asynchronously */ @font-face { font-family: 'MyFont'; src: url('/fonts/MyFont.woff2') format('woff2'); font-display: swap; } body { font-family: 'MyFont', sans-serif; } """ ## 4. Tooling and Automation Leverage tools and automation to enforce these standards. ### 4.1. Linting and Formatting **Standard:** Use linters and formatters to enforce code style and best practices. **Why:** Linters and formatters help maintain code consistency and identify potential issues early on. **Do This:** * Configure ESLint with recommended Astro and React rules. * Use Prettier to automatically format code. * Integrate linters and formatters into your development workflow using Git hooks or CI/CD pipelines. **Don't Do This:** * Ignore warnings and errors from linters. * Manually format code without using a formatter. **Example:** ".eslintrc.cjs" configuration """javascript module.exports = { env: { browser: true, es2020: true, node: true }, extends: [ 'eslint:recommended', 'plugin:@typescript-eslint/recommended', 'plugin:react/recommended', 'plugin:react/jsx-runtime', 'plugin:react-hooks/recommended', ], parser: '@typescript-eslint/parser', parserOptions: { ecmaVersion: 'latest', sourceType: 'module' }, plugins: ['react-refresh'], rules: { 'react-refresh/only-export-components': 'warn', '@typescript-eslint/no-unused-vars': 'warn', // Or "error" in stricter settings 'no-unused-vars': 'warn', 'no-console': 'warn', // Or "error" for production }, settings: { react: { version: 'detect', // Automatically detect the React version }, }, }; """ ### 4.2. Performance Monitoring **Standard:** Implement performance monitoring to track and improve performance over time. **Why:** Performance monitoring helps identify performance regressions and areas for improvement. **Do This:** * Use tools like Google PageSpeed Insights, WebPageTest, or Lighthouse to measure website performance. * Monitor real-user performance using tools like Google Analytics or New Relic. * Set up performance budgets to track and prevent performance regressions. **Don't Do This:** * Ignore performance metrics. * Rely solely on manual testing for performance evaluation. ### 4.3. Automated Testing **Standard:** Use automated tests to prevent performance regressions and ensure code quality. **Why:** Automated tests help catch performance issues early on and ensure that code changes do not negatively impact performance. **Do This:** * Write unit tests, integration tests, and end-to-end tests. * Use performance testing tools to measure the performance of your code. * Integrate tests into your CI/CD pipeline. **Don't Do This:** * Skip writing tests. * Rely solely on manual testing. ## 5. Security Considerations While this document primarily focuses on performance, security and performance are intertwined. ### 5.1. Secure Data Handling **Standard:** Always handle user data securely. **Why:** Securing user data protects privacy and prevents data breaches. **Do This:** * Sanitize and validate all user input to prevent cross-site scripting (XSS) attacks. * Use parameterized queries or ORMs to prevent SQL injection attacks. * Hash passwords using strong hashing algorithms like bcrypt or Argon2. * Use HTTPS to encrypt data in transit. **Don't Do This:** * Store sensitive data in plain text. * Trust user input without validation. ### 5.2 Dependency Management **Standard:** Regularly update dependencies to patch security vulnerabilities. **Why:** Outdated dependencies can contain security vulnerabilities that can be exploited by attackers. **Do This:** * Use a dependency management tool like npm or yarn to manage your project's dependencies. * Regularly update dependencies to the latest versions. * Use a tool like Snyk or Dependabot to automatically identify and fix security vulnerabilities in your dependencies. **Don't Do This:** * Use outdated dependencies. * Ignore security alerts from your dependency management tool. ## Conclusion By adhering to these performance optimization standards, Astro developers can create web applications that are fast, responsive, and resource-efficient. Continuously monitoring and improving performance is essential for delivering a great user experience. This document serves as a comprehensive guide that can be adopted by professional development teams as they build and maintain Astro projects. Continuously review and update these standards as the Astro ecosystem evolves.

# State Management Standards for Astro This document outlines coding standards for state management in Astro projects. These standards aim to promote maintainability, performance, and predictability of data flow throughout your Astro application. They are based on the current best practices for state management within Astro's architecture and ecosystem. ## 1. General Principles of State Management in Astro ### 1.1. Understanding Astro's Architecture and its Impact on State Astro is designed as a "content-focused" web framework. This means its primary goal is to deliver fast, static websites with islands of interactivity, rather than being a Single Page Application (SPA). This philosophy heavily influences how state management should be approached. * **Standard:** Favor build-time data fetching and static rendering wherever possible. * **Why:** Reduces client-side JavaScript, resulting in faster page loads and improved SEO. * **Do This:** Use "getStaticPaths()" and "Astro.glob()" to fetch data during the build process for routes and content. * **Don't Do This:** Fetch data dynamically on the client-side if it can be determined at build time. """astro // src/pages/blog/[slug].astro export async function getStaticPaths() { const posts = await Astro.glob('./posts/*.md'); return posts.map(post => ({ params: { slug: post.frontmatter.slug }, props: { post }, })); } const { post } = Astro.props; """ * **Standard:** Isolate interactive components ("islands") and manage their state independently. * **Why:** Astro's partial hydration model means that only the necessary components become interactive, limiting the scope of client-side state complexity. * **Do This:** Define clear boundaries for interactive components and use appropriate state management mechanisms within each island rather than trying to create one global state. * **Don't Do This:** Over-hydrate components unnecessarily or create a monolithic state object encompassing the entire application, undermining Astro's performance benefits. ### 1.2. Choosing the right State Management approach * **Standard:** Prefer component-local state for simple interactivity. * **Why:** Simplifies development, reduces dependencies, and aligns with Astro's component-centric architecture. * **Do This:** Utilize "useState" from React or similar hooks in your interactive components for basic UI updates and data handling when using a UI framework like React. * **Don't Do This:** Introduce a complex state management library when component-local state is sufficient. """jsx // src/components/Counter.jsx import React, { useState } from 'react'; function Counter() { const [count, setCount] = useState(0); return ( <div> <p>Count: {count}</p> <button onClick={() => setCount(count + 1)}>Increment</button> </div> ); } export default Counter; """ * **Standard:** Use Context API (React or Vue) for sharing state within a component subtree. * **Why:** Provides a simple way to avoid prop drilling and share data between related components without external dependencies. * **Do This:** Create a Context provider higher up in the component tree and consume the context within child components that need access to the shared state. * **Don't Do This:** Use Context for global application state if more advanced features like state persistence, complex updates, or computed values are needed. """jsx // src/context/ThemeContext.jsx import React, { createContext, useState, useContext } from 'react'; const ThemeContext = createContext(); export function ThemeProvider({ children }) { const [theme, setTheme] = useState('light'); const toggleTheme = () => { setTheme(prevTheme => (prevTheme === 'light' ? 'dark' : 'light')); }; return ( <ThemeContext.Provider value={{ theme, toggleTheme }}> {children} </ThemeContext.Provider> ); } export function useTheme() { return useContext(ThemeContext); } // src/components/ThemeToggle.jsx import React from 'react'; import { useTheme } from '../context/ThemeContext'; function ThemeToggle() { const { theme, toggleTheme } = useTheme(); return ( <button onClick={toggleTheme}> Toggle Theme (Current: {theme}) </button> ); } export default ThemeToggle; """ """astro // src/layouts/Layout.astro --- import { ThemeProvider } from '../context/ThemeContext.jsx'; --- <html lang="en"> <head>...</head> <body> <ThemeProvider> <slot /> </ThemeProvider> </body> </html> """ * **Standard:** Opt for a state management library (e.g., Zustand, Jotai, Recoil, Redux) only when dealing with complex application state, cross-component dependencies, or advanced data manipulation needs. * **Why:** Introduces additional complexity and overhead, so it should be justified by the specific requirements of the project. Consider the bundle size implications. * **Do This:** Carefully evaluate the pros and cons of different libraries and choose one that best suits the scale and complexity of your application. For simpler stores consider Zustand or Jotai. React Context + useReducer can be an alternative to Redux for many projects. * **Don't Do This:** Blindly adopt a state management library without considering whether simpler alternatives would suffice. ### 1.3. Data Fetching and API Interactions * **Standard:** Utilize Astro's "Astro.fetch()" for server-side data fetching. * **Why:** Integrates seamlessly with Astro's build process and offers performance optimizations. "Astro.fetch()" is a wrapper around the standard "fetch()" API, and can be used both at build time, and in API endpoints. * **Do This:** Fetch necessary data during the "getStaticPaths()" or within API routes. * **Don't Do This:** Rely solely on client-side fetching for data that could be fetched server-side. """astro // src/pages/posts.astro export async function getStaticPaths() { const response = await Astro.fetch('https://api.example.com/posts'); const posts = await response.json(); return posts.map(post => ({ params: { id: post.id }, props: { post }, })); } const { post } = Astro.props; """ * **Standard**: For client-side API calls, use "fetch" API with proper error handling and loading states. * **Why:** Provides a standard way to interact with APIs while maintaining a smooth user experience. * **Do This:** Display loading indicators while fetching data and handle potential errors gracefully. * **Example:** """jsx // src/components/UserList.jsx import React, { useState, useEffect } from 'react'; function UserList() { const [users, setUsers] = useState([]); const [loading, setLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { const fetchData = async () => { try { const response = await fetch('/api/users'); // Fetch from an Astro API endpoint. if (!response.ok) { throw new Error("HTTP error! Status: ${response.status}"); } const data = await response.json(); setUsers(data); } catch (e) { setError(e); } finally { setLoading(false); } }; fetchData(); }, []); if (loading) return <p>Loading users...</p>; if (error) return <p>Error: {error.message}</p>; return ( <ul> {users.map(user => ( <li key={user.id}>{user.name}</li> ))} </ul> ); } export default UserList; // src/pages/api/users.js export async function get() { try { const users = [{id: 1, name: "Alice"}, {id: 2, name: "Bob"}]; // Replace with actual data fetching from a database or external API. return new Response( JSON.stringify(users), { status: 200, headers: { "Content-Type": "application/json" } } ); } catch (error) { console.error(error); return new Response( JSON.stringify({ message: 'Failed to fetch users' }), { status: 500, headers: { "Content-Type": "application/json" } } ); } } """ ## 2. Specific State Management Patterns ### 2.1. Component-Local State with Hooks * **Standard:** Use "useState", "useReducer", "useContext" (from React or Vue) for managing state within individual components. * **Why:** Enables simple reactivity and isolates component logic. * **Do This:** Initialize state with appropriate default values and provide clear update functions. """jsx // src/components/Toggle.jsx import React, { useState } from 'react'; function Toggle() { const [isOn, setIsOn] = useState(false); const toggle = () => { setIsOn(!isOn); }; return ( <div> <button onClick={toggle}> {isOn ? 'Turn Off' : 'Turn On'} </button> <p>Status: {isOn ? 'ON' : 'OFF'}</p> </div> ); } export default Toggle; """ * **Standard:** Avoid deeply nested or complex state objects for local component state. * **Why:** Simplifies updates and reduces the risk of unintended side effects. * **Do This:** Break down complex state into multiple, smaller state variables. ### 2.2. Context API for Shared State * **Standard:** Create custom hooks to consume context values. * **Why:** Improves code readability and avoids repetitive "useContext" calls. It also encapsulates the context usage for cleaner code. * **Do This:** Create a "use[ContextName]" hook that returns the context value or specific properties. """jsx // src/context/AuthContext.jsx import React, { createContext, useState, useContext } from 'react'; const AuthContext = createContext(); export function AuthProvider({ children }) { const [user, setUser] = useState(null); const login = (userData) => { setUser(userData); }; const logout = () => { setUser(null); }; return ( <AuthContext.Provider value={{ user, login, logout }}> {children} </AuthContext.Provider> ); } export function useAuth() { return useContext(AuthContext); } // src/components/Profile.jsx import React from 'react'; import { useAuth } from '../context/AuthContext'; function Profile() { const { user, logout } = useAuth(); if (!user) { return <p>Please log in.</p>; } return ( <div> <p>Welcome, {user.name}!</p> <button onClick={logout}>Logout</button> </div> ); } export default Profile; """ * **Standard:** Limit the scope of Context providers to the components that need access to the shared state. * **Why:** Avoids unnecessary re-renders and maintains performance. Wrap only the components that need the context. * **Don't Do This:** Wrap the entire application in a single Context provider if only a small part of the app interacts with shared state. ### 2.3. External State Management Libraries (Zustand, Jotai, Recoil, Redux) * **Standard:** Use a state management library only when the complexity of the application warrants it. * **Why:** Introduces additional dependencies and complexity. * **Do This:** Carefully consider the trade-offs between simplicity and flexibility. * **Standard:** Follow the recommended patterns and best practices of the chosen library. * **Why:** Ensures maintainability and avoids common pitfalls * **Standard:** Consider using lightweight state management libraries like Zustand or Jotai for simple global state. * **Why:** They offer a simpler API and smaller bundle size compared to Redux. #### 2.3.1 Zustand Example """jsx // store.js (Zustand) import create from 'zustand'; const useStore = create(set => ({ bears: 0, increasePopulation: () => set(state => ({ bears: state.bears + 1 })), removeAllBears: () => set({ bears: 0 }), })); export default useStore; // src/components/BearCounter.jsx import React from 'react'; import useStore from '../store'; function BearCounter() { const bears = useStore(state => state.bears); return <h1>{bears} bears around here!</h1>; } export default BearCounter; // src/components/Controls.jsx import React from 'react'; import useStore from '../store'; function Controls() { const increasePopulation = useStore(state => state.increasePopulation); const removeAllBears = useStore(state => state.removeAllBears); return ( <> <button onClick={increasePopulation}>one up</button> <button onClick={removeAllBears}>remove all</button> </> ); } export default Controls """ ## 3. Anti-Patterns and Common Mistakes * **Anti-Pattern:** Over-reliance on global state for everything. * **Why:** Makes the application harder to reason about, test, and maintain. Can also hurt performance due to excessive re-renders. * **Do This:** Prefer component-local state or context when appropriate. Restrict global state to data that truly needs to be accessed across the entire application. * **Anti-Pattern:** Mutating state directly. * **Why:** Can lead to unexpected side effects and inconsistencies. * **Do This:** Always update state immutably using spread syntax or appropriate update functions provided by the state management library. """jsx // Incorrect: const myState = { items: [1, 2, 3] }; myState.items.push(4); // Direct mutation! // Correct: const myState = { items: [1, 2, 3] }; const newState = { ...myState, items: [...myState.items, 4] }; // Immutable update """ * **Anti-Pattern:** Unnecessary re-renders due to state updates. * **Why:** Hurts performance. * **Do This:** Use "useMemo" and "useCallback" hooks (or equivalent techniques for other UI frameworks) to prevent unnecessary re-renders of components that depend on unchanged state values. Also carefully consider the granularity of your state updates. * **Mistake:** Forgetting to handle loading and error states when fetching data. * **Why:** Degrades user experience. * **Do This:** Display loading indicators and handle potential errors gracefully. * **Mistake** Using client:load or client:visible directives unnecessarily in favor of server-side rendering. * **Why:** Defeats the purpose of Astro by hydrating the components client-side unnecessarily and potentially hurting performance. * **Do This:** Only use these directives when specific client-side interactions or functionality are required and cannot be achieved server-side. ## 4. Security Considerations * **Standard:** Sanitize data received from external sources before storing it in state. * **Why:** Prevents XSS (Cross-Site Scripting) vulnerabilities. * **Do This:** Use appropriate sanitization libraries or techniques recommended by your JavaScript framework (e.g., DOMPurify, "escape-html"). * **Standard:** Avoid storing sensitive information (e.g., API keys, passwords) in client-side state. * **Why:** Exposes sensitive data to potential attackers. * **Do This:** Store sensitive information securely on the server and access it through API endpoints that require authentication. ## 5. Testing State Management * **Standard:** Write unit tests for state update logic, especially when using complex state management libraries. * **Why:** Ensures the correctness and predictability of state transitions. * **Do This:** Use testing frameworks like Jest or Mocha with libraries like React Testing Library to test your state management logic in isolation. * **Standard:** Test component interactions that trigger state updates. * **Why:** Verifies that the UI correctly interacts with and reflects changes in the application state. * **Do This:** Use integration tests or end-to-end tests to simulate user interactions and verify the resulting state changes. ## 6. Tooling and Automation * **Standard:** Utilize linters and code formatters (e.g., ESLint, Prettier) to enforce consistent coding style and best practices related to state management. * **Why:** Automates code quality checks and reduces the risk of errors. * **Do This:** Configure your linter and formatter with rules that enforce immutability, proper error handling, and other state management best practices. * **Standard:** Use TypeScript to add static typing to your state management code. * **Why:** Helps catch type-related errors early in the development process and improves code maintainability. * **Do This:** Define clear type definitions for your state objects and actions.

# Testing Methodologies Standards for Astro This document provides coding standards for testing methodologies in Astro projects, emphasizing unit, integration, and end-to-end (E2E) testing strategies tailored for the Astro framework. It outlines best practices to ensure robust, maintainable, and reliable Astro applications. ## 1. General Testing Principles ### 1.1. Importance of Testing **Do This:** Prioritize writing tests for all components, utilities, and integrations. **Don't Do This:** Neglect writing tests or postpone them until the end of the development cycle. **Why:** Testing ensures code correctness, facilitates easier refactoring, reduces bugs in production, and improves overall code quality. Investing in testing saves time and resources in the long run by preventing costly fixes and downtime. ### 1.2. Test-Driven Development (TDD) **Do This:** Consider adopting TDD where appropriate, writing tests before implementing the actual code. **Don't Do This:** Avoid TDD principles altogether, especially for complex features or critical functionalities. **Why:** TDD helps to clarify requirements, promote cleaner code design, and ensure comprehensive test coverage from the outset. ### 1.3. Testing Pyramid **Do This:** Strive for a well-balanced testing pyramid: * A large base of unit tests. * A substantial layer of integration tests. * A smaller layer of end-to-end tests. **Don't Do This:** Over-rely on E2E tests at the expense of unit and integration tests. **Why:** Unit tests are fast and isolate problems effectively. Integration tests verify interactions between components. E2E tests, while valuable, are slower and more brittle. A balanced pyramid optimizes testing efficiency and coverage. ### 1.4. Code Coverage **Do This:** Aim for high code coverage (e.g., 80% or higher), but focus more on testing critical paths and functionality effectively. **Don't Do This:** Blindly chase 100% code coverage without considering the quality and relevance of the tests. **Why:** Code coverage metrics provide insights into which parts of the code are tested. High coverage reduces the risk of undetected bugs, but meaningful tests are more important than just achieving a specific percentage. ## 2. Unit Testing ### 2.1. Purpose **Do This:** Use unit tests to verify the functionality of individual components, functions, or modules in isolation. **Don't Do This:** Write unit tests that depend on external resources or other components; use mocks or stubs instead. **Why:** Unit tests should be fast, reliable, and focus on the smallest testable units of code. ### 2.2. Tools **Do This:** Utilize modern testing frameworks such as Jest or Vitest. **Don't Do This:** Use outdated or unmaintained testing libraries. **Why:** Modern testing frameworks offer features like mocking, spying, code coverage, and parallel test execution, improving test efficiency and developer experience. Vitest is particularly well-suited for Astro projects as it's built on Vite, like Astro itself. ### 2.3. Example: Testing an Astro Component """astro --- // src/components/MyComponent.astro export interface Props { title: string; } const { title } = Astro.props; --- <h1>{title}</h1> """ """javascript // src/components/MyComponent.test.js (using Vitest) import { render, screen } from '@testing-library/astro'; import MyComponent from './MyComponent.astro'; import { describe, it, expect } from 'vitest'; describe('MyComponent', () => { it('should render the title correctly', async () => { const { container } = await render(MyComponent, { title: 'Hello, Astro!' }); expect(screen.getByText('Hello, Astro!')).toBeInTheDocument(); }); it('should have the correct HTML structure', async () => { const {container} = await render(MyComponent, {title: 'Testing!'}); expect(container.querySelector('h1')).toBeInTheDocument(); expect(container.querySelector('h1')?.textContent).toBe('Testing!'); }); }); """ **Explanation:** * **"@testing-library/astro"**: Used for rendering and querying Astro components. * **"render"**: Renders the component with the provided props. * **"screen"**: Provides methods for querying the rendered output. * **"expect"**: Used for making assertions. * We verify that the component renders the title prop correctly and that the HTML structure is as expected. ### 2.4. Example: Testing a Utility Function """javascript // src/utils/formatDate.js export function formatDate(dateString) { const date = new Date(dateString); const options = { year: 'numeric', month: 'long', day: 'numeric' }; return date.toLocaleDateString(undefined, options); } """ """javascript // src/utils/formatDate.test.js (using Vitest) import { formatDate } from './formatDate'; import { describe, it, expect } from 'vitest'; describe('formatDate', () => { it('should format the date correctly', () => { const dateString = '2024-01-01'; const formattedDate = formatDate(dateString); expect(formattedDate).toBe('January 1, 2024'); }); it('should handle invalid dates gracefully', () => { const dateString = 'invalid-date'; const formattedDate = formatDate(dateString); expect(formattedDate).toBe('Invalid Date'); // Or handle as appropriate }); }); """ **Explanation:** * We test that the utility function formats a valid date string correctly. * We also test how the function handles an invalid date, ensuring it doesn't throw an error and returns an appropriate value. ### 2.5. Mocks and Stubs **Do This:** Use mocks and stubs to isolate the component or function being tested from its dependencies. **Don't Do This:** Directly import and use real dependencies in unit tests. **Why:** Mocks and stubs allow you to control the behavior of dependencies, making tests more predictable and preventing external factors from affecting the test results. """javascript // Example using Jest mocks // src/components/ExternalAPIComponent.js async function fetchData() { const response = await fetch('https://api.example.com/data'); return response.json(); } export default function ExternalAPIComponent() { const data = await fetchData(); return <div>{data.value}</div>; } """ """javascript // src/components/ExternalAPIComponent.test.js import ExternalAPIComponent from './ExternalAPIComponent.js'; import { describe, it, expect, vi } from 'vitest'; import { render, screen, waitFor } from '@testing-library/astro'; global.fetch = vi.fn(() => Promise.resolve({ json: () => Promise.resolve({ value: 'Mocked Data' }), }) ); describe('ExternalAPIComponent', () => { it('should render data from the external API', async () => { const { container } = await render(ExternalAPIComponent); await waitFor(() => { expect(screen.getByText('Mocked Data')).toBeInTheDocument(); }); }); }); """ **Explanation:** * We mock the "global.fetch" function to return a predefined response. * This ensures that the test doesn't rely on the actual external API being available and stable. * The test verifies that the component renders the mocked data correctly. ## 3. Integration Testing ### 3.1. Purpose **Do This:** Use integration tests to verify that different parts of the application work together correctly. **Don't Do This:** Treat integration tests as unit tests or E2E tests. Integration tests should focus on the interactions between components or modules. **Why:** Integration tests catch issues that unit tests might miss, such as incorrect data flow or misconfigured dependencies. ### 3.2. Tools **Do This:** Use the same testing framework as unit tests (e.g., Jest or Vitest) or specialized integration testing tools like Playwright or Cypress. **Don't Do This:** Avoid using tools that are difficult to set up or maintain. **Why:** Using consistent tools simplifies the testing process and reduces the learning curve. ### 3.3. Example: Testing Component Interaction """astro // src/components/ParentComponent.astro import ChildComponent from './ChildComponent.astro'; export interface Props { data: string; } const { data } = Astro.props; --- <div> <ChildComponent message={data} /> </div> """ """astro // src/components/ChildComponent.astro export interface Props { message: string; } const { message } = Astro.props; --- <p>{message}</p> """ """javascript // src/components/ParentComponent.test.js (using Vitest) import { render, screen } from '@testing-library/astro'; import ParentComponent from './ParentComponent.astro'; import { describe, it, expect } from 'vitest'; describe('ParentComponent', () => { it('should render the ChildComponent with the correct message', async () => { const { container } = await render(ParentComponent, { data: 'Hello from Parent!' }); expect(screen.getByText('Hello from Parent!')).toBeInTheDocument(); }); }); """ **Explanation:** * We test that the "ParentComponent" correctly passes the "data" prop to the "ChildComponent". * The test verifies that the "ChildComponent" renders the message as expected. ### 3.4. Mocking External Services in Integration Tests **Do This:** Mock external dependencies in integration tests where possible to avoid relying on live services. **Don't Do This:** Skip mocking essential services, as inconsistent external behavior can make your tests unreliable. """javascript // Example mocking an API call in an integration test // src/services/apiService.js export async function fetchDataFromAPI() { const response = await fetch('/api/data'); return await response.json(); } """ """javascript // src/components/DataComponent.astro import { fetchDataFromAPI } from '../services/apiService'; async function getData() { return await fetchDataFromAPI(); } const data = await getData(); --- <div>{data?.message}</div> """ """javascript // src/components/DataComponent.test.js import { render, screen, waitFor} from '@testing-library/astro'; import DataComponent from './DataComponent.astro'; import { fetchDataFromAPI } from '../services/apiService'; import { describe, it, expect, vi } from 'vitest'; vi.mock('../services/apiService', () => ({ fetchDataFromAPI: vi.fn(() => Promise.resolve({ message: 'Mocked API data' })) })); describe('DataComponent', () => { it('should render data from the API service', async () => { const { container } = await render(DataComponent); await waitFor(() => { expect(screen.getByText('Mocked API data')).toBeInTheDocument(); }); expect(fetchDataFromAPI).toHaveBeenCalled(); }); }); """ **Explanation:** * We mock the "fetchDataFromAPI" function using "vi.mock". * This prevents the integration test from making actual API calls. * We then assert that the mocked method has been called, implying the DataComponent is using it. ## 4. End-to-End (E2E) Testing ### 4.1. Purpose **Do This:** Use E2E tests to verify that the entire application works correctly from the user's perspective. **Don't Do This:** Rely solely on E2E tests; they are slower and more brittle than unit and integration tests. **Why:** E2E tests simulate real user interactions and catch integration issues that other testing types might miss. ### 4.2. Tools **Do This:** Choose E2E testing tools like Playwright or Cypress. **Don't Do This:** Use tools that are difficult to set up, configure, or maintain. **Why:** Playwright and Cypress offer features like automatic waiting, cross-browser testing, and detailed error reporting, improving developer productivity. Playwright is particularly well-suited for Astro due to its modern architecture and excellent TypeScript support. ### 4.3. Example: Testing a Navigation Flow """javascript // playwright.config.js (Playwright configuration file) import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ testDir: './tests', fullyParallel: true, reporter: 'html', use: { baseURL: 'http://localhost:3000', // Replace with your development server URL trace: 'on-first-retry', }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] }, }, ], webServer: { command: 'npm run dev', // Replace with your development server command port: 3000, reuseExistingServer: !process.env.CI, }, }); """ """javascript // tests/navigation.spec.js (Playwright test file) import { test, expect } from '@playwright/test'; test('navigation to the about page', async ({ page }) => { await page.goto('/'); await page.getByRole('link', { name: 'About' }).click(); await expect(page).toHaveURL('/about'); await expect(page.getByRole('heading', { name: 'About Us' })).toBeVisible(); }); test('check title', async ({ page }) => { await page.goto('https://example.com/'); // Expect a title "to contain" a substring. await expect(page).toHaveTitle(/Example Domain/); }); """ **Explanation:** * We use Playwright to navigate to the homepage ("/") and then click on the "About" link. * We assert that the page URL changes to "/about" and that the "About Us" heading is visible. This verifies the basic navigation flow. ### 4.4. Writing Reliable E2E Tests **Do This:** Write E2E tests that are resilient to minor UI changes and timing issues. **Don't Do This:** Write brittle tests that are prone to failure due to small UI adjustments or network latency. **Why:** Robust E2E tests are crucial for maintaining a stable and reliable application. Avoid using fixed timeouts, and instead favor locating elements by their role/label. ### 4.5. Environment Variables **Do This**: Store environment-specific configuration values such as base URLs in ".env" files and use environment variables to configure your tests. **Don't Do This**: Hardcode URLs or API keys directly in your tests. **Why**: Using environment variables ensures that your tests can be run in different environments (e.g., development, staging, production) without requiring code changes. ## 5. Accessibility Testing. ### 5.1 Importance of Accessibility **Do This:** Implement accessibility checks in your tests to ensure your application is usable by everyone. **Don't Do This:** Neglect accessibility testing, as it can exclude users and lead to legal issues. **Why:** Accessible applications provide a better user experience for everyone, including users with disabilities. ### 5.2 Tools **Do This**: Use accessibility testing tools like axe-core along with testing frameworks. **Don't Do This**: Depend solely on manual checks without automated testing. **Why**: Automated accessibility testing can catch common accessibility issues early in the development process. ### 5.3 Example Accessibility test """javascript // tests/e2e/accessibility.spec.js import { test, expect } from '@playwright/test'; import AxeBuilder from '@axe-core/playwright'; test.describe('Accessibility', () => { test('homepage should not have any automatically detectable accessibility issues', async ({ page }) => { await page.goto('/'); const axeBuilder = new AxeBuilder({ page }); const accessibilityScanResults = await axeBuilder.analyze(); expect(accessibilityScanResults.violations).toEqual([]); }); }); """ ## 6. Performance Testing ### 6.1 Importance of Performance Testing **Do This:** Measure the performance of your Astro application using appropriate tools and techniques. **Don't Do This:** Ignore performance testing, as slow applications can lead to poor user experience and loss of business. **Why:** Performance testing helps identify bottlenecks and areas for optimization in your application. ### 6.2 Tools **Do This:** Use performance testing tools like Lighthouse, WebPageTest, or browser developer tools. **Don't Do This:** Rely solely on manual observations without quantitative metrics. **Why:** These tools provide detailed insights into various performance metrics, such as load time, rendering time, and resource utilization. ## 7. Common Anti-Patterns to Avoid ### 7.1. Flaky Tests **Don't Do This:** Accept flaky tests (tests that pass sometimes and fail sometimes). **Do This:** Investigate and fix flaky tests; they undermine confidence in the test suite. **Why:** Flaky tests often indicate underlying issues in the code or test setup. ### 7.2. Over-mocking **Don't Do This:** Mock everything in sight. **Do This:** Mock only the dependencies that are necessary to isolate the unit under test. **Why:** Over-mocking can lead to tests that don't accurately reflect the behavior of the real system. ### 7.3. Ignoring Test Coverage **Don't Do This:** Ignore code coverage metrics. **Do This:** Use code coverage reports to identify areas of the code that are not adequately tested. **Why:** Code coverage helps to ensure that all parts of the code are covered by tests. ### 7.4. Hardcoded Values **Don't Do This:** Hardcode values in tests. **Do This:** Use test data generators or fixtures to create realistic and maintainable test data. **Why:** Hardcoded values make tests brittle and difficult to maintain. By adhering to these coding standards, you can ensure that your Astro projects are well-tested, maintainable, and reliable. Remember to continuously review and update these standards as the Astro framework and testing tools evolve.

# Deployment and DevOps Standards for Astro This document outlines coding standards and best practices for Deployment and DevOps of Astro projects. Following these guidelines ensures maintainable, performant, and secure deployments. These standards are tailored for the latest version of Astro, emphasizing modern approaches and patterns. ## 1. Build Process and Optimization ### 1.1. Standard: Optimized Production Builds **Statement:** Always optimize your Astro project for production by utilizing built-in Astro features and appropriate configuration. **Why:** Optimization reduces the overall size of your deployed application, leading to faster loading times and improved user experience. **Do This:** * Use "astro build" to create production-ready assets. * Configure image optimization using Astro's built-in image tools. * Enable minification and tree-shaking in your build configuration. * Leverage environment variables to conditionally compile code. **Don't Do This:** * Deploy development builds to production. * Include unnecessary files in your deployment package. * Skip image optimization. * Hardcode sensitive information in the codebase; always use environment variables. **Code Example: "astro.config.mjs"** """javascript import { defineConfig } from 'astro/config'; import image from '@astrojs/image'; import vercel from '@astrojs/vercel/serverless'; // or other adapter // https://astro.build/config export default defineConfig({ output: 'server', adapter: vercel(), // or other adapter integrations: [image()], vite: { build: { minify: 'esbuild', // Enable minification rollupOptions: { output: { chunkFileNames: 'assets/chunks/[hash].js', // Optimize chunk names assetFileNames: 'assets/[hash][extname]' // Optimize asset names } } } }, image: { service: 'sharp', // or 'squoosh' //Other possible options here } }); """ **Anti-Pattern:** Disabling minification during production builds. This increases the size of the deployed assets, impacting load times. ### 1.2. Standard: Asset Optimization **Statement:** Optimize all assets (images, fonts, CSS, JavaScript) for the web. **Why:** Optimized assets reduce bandwidth consumption, improve page load times, and enhance user experience. **Do This:** * Use optimized image formats (WebP, AVIF) wherever possible. * Compress images without significant loss of quality. * Minify CSS and JavaScript files. * Use font formats like WOFF2. * Implement lazy loading for non-critical images. **Don't Do This:** * Deploy large, unoptimized images. * Use unminified CSS or JavaScript in production. * Ignore font optimization best practices. **Code Example: Image component with optimization:** """astro --- import { Image } from '@astrojs/image/components'; import optimizedImage from '../assets/my-image.jpg'; // Import your image. --- <Image src={optimizedImage} alt="Optimized Image" width={600} height={400} format="webp" quality={80} /> """ **Anti-Pattern:** Using PNG or JPEG images without compression significantly increases page load times. WebP/AVIF provides superior compression and image quality. ### 1.3. Standard: Code Splitting **Statement:** Implement code splitting to load only the necessary JavaScript for each page or component. **Why:** Code splitting reduces the initial load time and improves the responsiveness of your application. **Do This:** * Leverage dynamic imports for components that are not immediately needed. * Utilize Astro's built-in support for code splitting with "<script>" tags. * Analyze bundle sizes using tools like "rollup-plugin-visualizer" to identify areas for optimization. **Don't Do This:** * Load all JavaScript in a single bundle. * Include unused code in your production bundles. **Code Example: Dynamic Imports** """astro --- let showModal = false; --- <button onclick={() => showModal = true}>Show Modal</button> {showModal && ( <Fragment> <astro-island client:visible hoist> <Modal /> </astro-island> </Fragment> )} <style> astro-island { display: contents; } </style> """ **Anti-Pattern:** Loading large libraries or components on every page, even when they are only used on a specific route. ### 1.4. Standard: Preloading **Statement:** Preload critical assets needed for the initial rendering of the page. **Why:** Preloading ensures assets are available earlier, improving perceived performance. **Do This:** * Use the "<link rel="preload">" tag to preload critical resources. * Prioritize resources needed for the first screenful of content. * Consider preloading fonts to avoid font flashes. **Don't Do This:** * Overuse preloading, as it can negatively impact performance. * Preload non-critical resources. **Code Example: Preloading Fonts** """html <head> <!-- Preload a font --> <link rel="preload" href="/fonts/my-font.woff2" as="font" type="font/woff2" crossorigin> </head> """ **Anti-Pattern:** Failing to preload critical fonts, resulting in layout shifts and a poor user experience. ## 2. CI/CD Pipelines ### 2.1. Standard: Automated Builds and Deployments **Statement:** Implement a CI/CD pipeline to automate the build, testing, and deployment processes. **Why:** Automation reduces errors, increases deployment frequency, and ensures consistency. **Do This:** * Use a CI/CD platform like GitHub Actions, GitLab CI, or CircleCI. * Automate linting, testing, and building steps. * Trigger deployments automatically on code pushes to specific branches. * Implement rollback mechanisms in case of failed deployments. **Don't Do This:** * Manually build and deploy your application. * Skip testing in your CI/CD pipeline. * Lack a rollback strategy. **Code Example: GitHub Actions (".github/workflows/deploy.yml") showing an example of using the deploy task** """yaml name: Deploy to Production on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: 20 - name: Install dependencies run: npm ci - name: Build Astro run: npm run build - name: Deploy to Vercel/Netlify/Cloudflare Pages, etc. run: npx astro deploy env: VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }} NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} """ **Anti-Pattern:** Deploying code without automated testing, leading to potential bugs in production. ### 2.2. Standard: Staging Environments **Statement:** Use staging environments to test changes before deploying to production. **Why:** Staging environments allow you to identify and fix issues in a realistic environment before they impact users. **Do This:** * Create a replica of your production environment for staging. * Deploy code to staging before production. * Test thoroughly in staging. **Don't Do This:** * Deploy directly to production without testing in staging. * Use different configurations for staging and production environments. **Implementation:** * Configure your CI/CD pipeline to deploy to staging on pushes to a "develop" or "staging" branch, and to production on pushes to "main". **Anti-Pattern:** Bypassing the staging environment, risking production instability. ### 2.3. Standard: Infrastructure as Code (IaC) **Statement:** Manage your infrastructure using code, such as Terraform or CloudFormation. **Why:** IaC allows you to version control your infrastructure, automate provisioning, and ensure consistency across environments. **Do This:** * Define your infrastructure in code. * Use a tool like Terraform to manage resources. * Automate the creation and update of infrastructure. **Don't Do This:** * Manually provision infrastructure. * Store infrastructure configurations locally. **Example (conceptual):** While a complete Terraform example is extensive, a brief snippet shows the principle: """terraform resource "aws_s3_bucket" "astro_bucket" { bucket = "my-astro-site-bucket" acl = "private" website { index_document = "index.html" error_document = "404.html" } } """ **Anti-Pattern:** Manually configuring cloud resources through a web console, making it difficult to track changes and reproduce environments. ### 2.4. Standard: Monitoring and Logging **Statement:** Implement comprehensive monitoring and logging to detect and diagnose issues. **Why:** Monitoring and logging provide visibility into the performance and health of your application, enabling you to quickly identify and resolve issues. **Do This:** * Use a logging library to record application events. * Implement error tracking with tools like Sentry or Bugsnag. * Monitor key metrics such as response time, error rates, and resource utilization. * Set up alerts for critical events. **Don't Do This:** * Ignore logging and monitoring. * Log sensitive information. * Fail to set up alerts for critical events. **Code Example: Basic logging with "console.log" (in an Astro component or API endpoint)** """javascript console.log('Request received for /api/data'); try { // some code that might error } catch (error) { console.error('Error fetching data:', error); } """ **Anti-Pattern:** Lack of error tracking, making it difficult to identify and resolve issues quickly. Using only "console.log" in production without a robust monitoring system. ## 3. Production Considerations ### 3.1. Standard: Caching Strategies **Statement:** Implement caching strategies to improve performance and reduce server load. **Why:** Caching reduces the need to repeatedly fetch data or generate content, improving response times and reducing server load. **Do This:** * Use browser caching for static assets. * Implement server-side caching using tools like Redis or Memcached. * Use a Content Delivery Network (CDN) to cache and distribute assets globally. **Don't Do This:** * Cache sensitive data improperly. * Set excessively long cache durations. * Fail to invalidate caches when content changes. **Code Example: Setting Cache Headers (example using middleware)** """javascript // src/middleware.js import { defineMiddleware } from 'astro/middleware'; export const onRequest = defineMiddleware((context, next) => { const response = await next(); // Set cache control headers for 1 hour. Adjust as needed. response.headers.set('Cache-Control', 'public, max-age=3600'); return response; }); """ **Anti-Pattern:** Aggressively caching dynamic content, leading to stale data being served to users. ### 3.2. Standard: Security Best Practices **Statement:** Implement security best practices to protect your application and data. **Why:** Security measures prevent vulnerabilities, protect user data, and maintain the integrity of your application. **Do This:** * Use HTTPS for all traffic. * Sanitize user input to prevent injection attacks. * Protect against Cross-Site Scripting (XSS) attacks. * Implement authentication and authorization mechanisms. * Keep dependencies up to date with security patches. * Regularly review and update security practices. **Don't Do This:** * Store sensitive data in plain text. * Expose sensitive information in client-side code. * Ignore security vulnerabilities. **Code Example: Using environment variables for API keys.** """javascript const apiKey = import.meta.env.API_KEY; if (!apiKey) { console.error('API key is missing from environment variables.'); } """ **Anti-Pattern:** Exposing API keys or other secrets in client-side JavaScript or Git repositories. ### 3.3. Standard: Performance Monitoring **Statement:** Continuously monitor the performance of your application in production. **Why:** Monitoring allows you to identify and address performance bottlenecks, ensuring a smooth user experience. **Do This:** * Use performance monitoring tools like Google PageSpeed Insights, WebPageTest, or Lighthouse. * Monitor key metrics such as page load time, Time to First Byte (TTFB), and Largest Contentful Paint (LCP). * Set up alerts for performance regressions. **Don't Do This:** * Ignore performance metrics once the application is deployed. * Fail to optimize identified performance bottlenecks * Assume performence is always the same over time. **Implementation:** * Integrate performance monitoring tools into your CI/CD pipeline. * Regularly audit your application's performance. **Anti-Pattern:** Deploying code without monitoring its performance, leading to unnoticed performance degradations. ### 3.4. Standard: Scalability **Statement:** Design your application and infrastructure to scale to handle increased traffic and data. **Why:** Scalability ensures that your application can handle increased demand without performance degradation. **Do This:** * Use a scalable hosting platform. * Optimize database queries. * Implement caching to reduce database load. * Use load balancing to distribute traffic across multiple servers. **Don't Do This:** * Design for a fixed number of users. * Rely on a single server to handle all traffic. * Ignore database optimization. **Implementation (conceptual):** * Use a cloud provider like AWS, Google Cloud, or Azure that offers auto-scaling capabilities. * Distribute your application across multiple servers behind a load balancer. **Anti-Pattern:** Designing an application that cannot scale, leading to performance issues during peak traffic periods. By adhering to these Deployment and DevOps standards, you can ensure that your Astro projects are maintainable, performant, secure, and scalable. These practices provide a solid foundation for building and deploying modern web applications.