Cline

# Security Best Practices Standards for Parcel This document outlines the security best practices for developing applications with Parcel. Adhering to these standards will help mitigate common vulnerabilities and ensure a more secure application. These standards are designed to be used as a guide for developers and as context for AI coding assistants. ## 1. Input Validation and Sanitization ### 1.1. Why Input Validation Matters Input validation is critical for preventing various attacks, including Cross-Site Scripting (XSS), SQL Injection, and Command Injection. By validating and sanitizing all inputs, you ensure that only expected data is processed by your application. ### 1.2. General Principles * **Do This:** Validate all user inputs, including form fields, URL parameters, and API requests. * **Do This:** Use strict validation rules that define the allowed data types, formats, and lengths. * **Do This:** Sanitize inputs to remove or escape potentially harmful characters. * **Don't Do This:** Rely solely on client-side validation, as it can be bypassed. Always validate inputs on the server-side. * **Don't Do This:** Trust data from external sources without validation. ### 1.3. Implementing Input Validation in Parcel Parcel typically serves static assets and bundles JavaScript. Input validation generally occurs within application code (e.g., React, Vue, Svelte) that Parcel bundles. **Example: Validating Form Input in a React Component** """jsx import React, { useState } from 'react'; import DOMPurify from 'dompurify'; function MyFormComponent() { const [userInput, setUserInput] = useState(''); const [validatedInput, setValidatedInput] = useState(''); const handleChange = (event) => { setUserInput(event.target.value); }; const handleSubmit = (event) => { event.preventDefault(); // 1. Validation if (userInput.length > 100) { alert('Input too long!'); return; } const isValid = /^[a-zA-Z0-9\s]*$/.test(userInput); // Only allow alphanumeric and space if (!isValid) { alert('Invalid characters!'); return; } // 2. Sanitization using DOMPurify (for demonstration if rendering HTML) const sanitizedInput = DOMPurify.sanitize(userInput); setValidatedInput(sanitizedInput); console.log('Processed input:', sanitizedInput); // In a real application: you would send "sanitizedInput" to your backend API. }; return ( <form onSubmit={handleSubmit}> <label> Enter text: <input type="text" value={userInput} onChange={handleChange} /> </label> <button type="submit">Submit</button> {validatedInput && <p>You entered: {validatedInput}</p>} </form> ); } export default MyFormComponent; """ **Explanation:** 1. **Validation:** The example validates the input length and allowed characters. More complex validations (e.g., email format, date ranges) can be added. 2. **Sanitization:** "DOMPurify" is used to sanitize the input in case HTML is rendered. This is crucial to prevent XSS attacks. **Note:** When sending data via APIs, validate the data *again* on your backend. Never trust client-side validation alone. ### 1.4. Common Anti-Patterns * **Inadequate Length Checks:** Failing to limit the length of input fields can lead to buffer overflows or denial-of-service attacks. * **Insufficient Pattern Matching:** Using weak regular expressions for validation can allow malicious input to pass through. * **Ignoring Error Handling:** Not handling validation errors gracefully can provide attackers with information about your validation logic. ## 2. Cross-Site Scripting (XSS) Prevention ### 2.1. Understanding XSS XSS attacks occur when malicious scripts are injected into web pages viewed by other users. Parcel, being a bundler, processes and serves the JavaScript that ultimately executes in the user's browser, making XSS prevention crucial. ### 2.2. Strategies for XSS Prevention * **Do This:** Use Content Security Policy (CSP) to control the resources that the browser is allowed to load. * **Do This:** Employ output encoding to escape special characters when rendering user-supplied data. * **Do This:** Sanitize HTML inputs with libraries like "DOMPurify" before rendering them. * **Don't Do This:** Directly insert user input into HTML without encoding or sanitization. * **Don't Do This:** Disable CSP or reduce security settings without a very good reason. ### 2.3. Implementing CSP in Parcel CSP can be configured through HTTP headers or meta tags. Configuring it via HTTP headers is recommended for enhanced security. Parcel doesn't directly handle HTTP headers (that's your web server's job), but it is important you configure your webserver to send a strong CSP header. **Example: CSP Header (Example - adjust for your specific needs):** """ Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' https://example.com; style-src 'self' https://example.com; img-src 'self' data:; font-src 'self'; """ **Explanation:** * "default-src" "'self'": Specifies that resources should only be loaded from the same origin by default. * "script-src" "'self' 'unsafe-inline' https://example.com": Allows scripts from the same origin, inline scripts (use sparingly, try to avoid "unsafe-inline" if possible), and scripts from "https://example.com". Using a nonce is better than unsafe-inline, if possible. * "style-src" "'self' https://example.com": Allows styles from the same origin and "https://example.com". * "img-src" "'self' data:": Allows images from the same origin and data URIs. * "font-src" "'self'": Allows fonts from the same origin. **Modern Approach: CSP Nonces** A nonce ("number used once") is a cryptographically random token generated for each request. You can add the nonce to your script tags, so only scripts with the correct nonce will be executed. **Example: Integrating Nonces with a Backend:** Let's assume you have a backend that can generate a nonce, and you're using a templating engine to generate your HTML. 1. **Generate a Nonce on the Server:** * In your backend (e.g., Node.js with Express), generate a cryptographically secure random string: """javascript const crypto = require('crypto'); app.get('/', (req, res) => { const nonce = crypto.randomBytes(16).toString('hex'); res.render('index', { nonce }); }); """ 2. **Pass the Nonce to Your Template:** * Pass the nonce to your HTML template. 3. **Use the Nonce in Your HTML:** """html <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>CSP Example</title> <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'nonce-{{nonce}}'; style-src 'self'"> </head> <body> <h1>Hello, world!</h1> <script nonce="{{nonce}}" src="/dist/index.js"></script> </body> </html> """ 4. **Configure Parcel to Not Remove Nonce Attribute** Parcel and other bundlers might remove attributes they consider non-standard. You may need to configure parcel to keep the "nonce" attribute on script tags using the "html-minifier-terser" if you are using HTML minification. Check your configuration for your specific version of Parcel. **Important:** Ensure your server invalidates the nonce after each request to prevent replay attacks. ### 2.4. Avoiding "unsafe-inline" While the examples show "'unsafe-inline'", it's generally discouraged. Inline scripts and styles are more vulnerable to XSS attacks. Whenever possible: * Move JavaScript code into separate files. * Use CSS classes instead of inline styles. * Consider using a templating engine that automatically escapes variables for HTML context. ### 2.5 Sanitizing output with DOMPurify Often you will need to display user input. In these cases it is CRITICAL to sanitize the input before displaying it to prevent XSS attacks. """jsx import React from 'react'; import DOMPurify from 'dompurify'; function DisplayUserInput({ userInput }) { const sanitizedHTML = { __html: DOMPurify.sanitize(userInput) }; return <div dangerouslySetInnerHTML={sanitizedHTML} />; } export default DisplayUserInput; """ **Explanation:** * "DOMPurify.sanitize(userInput)": This makes sure that the output is safe. * "dangerouslySetInnerHTML": Use this with CAUTION. Only use after you are certain the input has been properly sanitized. ## 3. Dependency Management ### 3.1. Why Dependency Security Matters Modern JavaScript projects rely heavily on third-party libraries. Vulnerabilities in these dependencies can expose your application to security risks. ### 3.2. Best Practices for Dependency Management * **Do This:** Use a package manager like "npm" or "yarn" to manage dependencies. * **Do This:** Regularly update dependencies to patch known vulnerabilities. * **Do This:** Use a dependency scanning tool to identify vulnerabilities in your dependencies. * **Do This:** Review the security policies of the dependencies you use. * **Don't Do This:** Use outdated or unmaintained dependencies. * **Don't Do This:** Ignore security alerts from dependency scanning tools. ### 3.3. Dependency Scanning with "npm audit" "npm" provides a built-in command, "npm audit", to scan your project's dependencies for vulnerabilities. **Example: Running "npm audit"** """bash npm audit """ This command analyzes your "package-lock.json" or "yarn.lock" file and reports any known vulnerabilities. **Example Output:** """ === npm audit security report === found 5 vulnerabilities (3 moderate, 2 high) run "npm audit fix" to fix some of them, or commit changes to npm-shrinkwrap.json to install only safe updates ... """ ### 3.4. Using "npm audit fix" "npm audit fix" attempts to automatically update vulnerable dependencies to secure versions. **Example: Running "npm audit fix"** """bash npm audit fix """ **Important Considerations:** * "npm audit fix" might introduce breaking changes. Test your application thoroughly after running this command. * Some vulnerabilities cannot be automatically fixed. In these cases, you may need to manually update or replace the vulnerable dependency. ### 3.5. Using Snyk Snyk is a popular tool that can be integrated into CI/CD pipelines to automatically identify and fix vulnerabilties. ### 3.6. Pinning Dependencies and Using Lockfiles * **Do This:** Always use a lockfile (package-lock.json or yarn.lock). This ensures that everyone on your team (and production environments) uses the exact same versions of dependencies. * **Do This:** Consider pinning dependencies to specific patch versions to prevent unexpected issues from minor or major updates. However, be careful to update regularly to keep secure. Use semantic versioning ranges ("^" or "~") to allow updates while minimizing risk. ## 4. Secure Configuration ### 4.1. The Importance of Secure Configuration Configuration settings can significantly impact the security of your application. Storing sensitive data securely and configuring your application properly is vital. ### 4.2. Best Practices for Secure Configuration * **Do This:** Use environment variables to store sensitive information, such as API keys and database credentials. * **Do This:** Avoid hardcoding sensitive data in your source code. * **Do This:** Use a configuration management tool to manage environment-specific settings. * **Do This:** Restrict access to configuration files and environment variables. * **Don't Do This:** Commit sensitive data to version control. * **Don't Do This:** Expose sensitive configuration settings to the client-side code. ### 4.3. Using Environment Variables with Parcel Parcel can use environment variables defined in a ".env" file or system environment variables. Parcel automatically injects these variables into the bundled code at build time. **Example: Creating a ".env" file** """ API_KEY=YOUR_API_KEY DATABASE_URL=YOUR_DATABASE_URL """ **Example: Accessing Environment Variables in JavaScript** """javascript const apiKey = process.env.API_KEY; const databaseUrl = process.env.DATABASE_URL; console.log('API Key:', apiKey); console.log('Database URL:', databaseUrl); """ **Explanation:** * Parcel automatically replaces "process.env.API_KEY" and "process.env.DATABASE_URL" with the actual values from the ".env" file or system environment variables at build time. * **Important:** Environment variables are embedded in your bundled output. *Never* store secrets intended only for backend services in environment variables used in Parcel. They will be exposed to anyone who can view the JavaScript in the browser. ### 4.4. ".env" File Management * **Do This:** Add your ".env" file to your ".gitignore" file to prevent committing sensitive data to version control. * **Do This:** Use a tool like "dotenv" to load environment variables into "process.env" during development. **Example: Using "dotenv"** 1. Install "dotenv": """bash npm install dotenv """ 2. Require and configure "dotenv" at the top of your main application file: """javascript require('dotenv').config(); const apiKey = process.env.API_KEY; console.log('API Key:', apiKey); """ ## 5. Secure Data Handling ### 5.1. Sensitive Data Storage * **Do This:** Avoid storing sensitive data on the client-side whenever possible. If you must store it, encrypt it and use secure storage mechanisms (e.g., the browser's built-in Crypto API or secure cookies with appropriate flags). Note that even encrypted data is vulnerable if the encryption key is exposed. * **Do This:** Never store passwords or API keys directly in client-side storage. * **Don't Do This:** Rely on "localStorage" or "sessionStorage" for sensitive data, as they are easily accessible to JavaScript code. ### 5.2. Data Transmission * **Do This:** Always use HTTPS to encrypt data in transit between the client and the server. * **Do This:** Use strong TLS configurations and keep your SSL/TLS certificates up to date. ### 5.3. Secure Cookies * **Do This:** Set the "Secure" attribute on cookies to ensure they are only transmitted over HTTPS. * **Do This:** Set the "HttpOnly" attribute to prevent client-side scripts from accessing cookies. * **Do This:** Set the "SameSite" attribute to "Strict" or "Lax" to protect against Cross-Site Request Forgery (CSRF) attacks. **Example: Setting Secure Cookie Attributes on the Server (Example uses Node.js with Express):** """javascript app.get('/set-cookie', (req, res) => { res.cookie('myCookie', 'cookieValue', { secure: true, // Only send over HTTPS httpOnly: true, // Prevent client-side access sameSite: 'strict', // Protect against CSRF }); res.send('Cookie set!'); }); """ ## 6. Regular Security Audits and Testing ### 6.1. Why Audits and Testing Matter Regular security audits and testing are crucial for identifying and addressing vulnerabilities in your application. ### 6.2. Strategies for Audits and Testing * **Do This:** Perform regular security audits of your code and infrastructure. * **Do This:** Conduct penetration testing to simulate real-world attacks. * **Do This:** Use automated security scanning tools to identify common vulnerabilities. * **Do This:** Stay up-to-date with the latest security threats and best practices. ### 6.3. Types of Security Testing * **Static Analysis Security Testing (SAST):** Analyzing source code for potential vulnerabilities without executing the code. Examples include ESLint with security plugins. * **Dynamic Analysis Security Testing (DAST):** Testing the application in runtime to identify vulnerabilities. * **Penetration Testing:** Simulating real-world attacks to identify vulnerabilities. * **Dependency Scanning:** Identifying vulnerabilities in third-party dependencies. ## 7. Error Handling and Logging ### 7.1. Secure Error Handling * **Do This:** Implement proper error handling to prevent sensitive information from being exposed in error messages. * **Do This:** Log errors and exceptions to a secure location for debugging purposes. Do *not* log sensitive user data. * **Don't Do This:** Display detailed error messages to users in production, as they can reveal information about your application's internals. ### 7.2. Secure Logging * **Do This:** Log important events, such as authentication attempts, access control decisions, and data modifications. * **Do This:** Protect log files from unauthorized access. * **Do This:** Use structured logging formats to facilitate analysis. However, make SURE no sensitive data is logged. * **Don't Do This:** Store sensitive data in log files. ## 8. Subresource Integrity (SRI) ### 8.1. Why SRI Matters Subresource Integrity (SRI) allows browsers to verify that files fetched from CDNs or other third-party sources haven't been tampered with. ### 8.2. Implementing SRI * **Do This:** Generate SRI hashes for all external resources. * **Do This:** Include the "integrity" attribute in your "<script>" and "<link>" tags. **Example:** """html <script src="https://example.com/script.js" integrity="sha384-EXAMPLE_HASH" crossorigin="anonymous" ></script> """ **Explanation:** * "integrity": Specifies the expected SHA-256, SHA-384, or SHA-512 hash of the resource. * "crossorigin="anonymous"": Indicates that the resource should be fetched without sending credentials. ## 9. Secure Code Review ### 9.1. Why Code Review Matters Code reviews are an essential part of the software development process. They help identify potential security vulnerabilities and ensure that code meets security standards. ### 9.2. Best Practices for Code Review * **Do This:** Conduct regular code reviews by experienced developers. * **Do This:** Focus on security aspects during code reviews. * **Do This:** Use code review tools to automate the review process. * **Do This:** Document code review findings and track their resolution. ## 10. Parcel Specific Considerations ### 10.1. Plugin Security If you are using or writing Parcel plugins, ensure these plugins come from reputable sources. Malicious plugins can inject code or modify your build process in harmful ways. Review plugin code when possible, and keep plugins updated. ### 10.2. Output Directory Security Ensure that your Parcel output directory (usually "dist") is properly secured on your server. Prevent unauthorized access to these files, as they contain your application code. Server configuration (e.g., Nginx, Apache) plays a critical role here. ### 10.3. Be Aware of Build Time Dependencies Parcel uses many dependencies at build time (e.g., Babel, Terser). Follow dependency management best practices to secure these as well, since vulnerabilities in these build-time tools could lead to compromised builds. This detailed guide provides a solid foundation for developing secure Parcel applications. Remember to stay updated with the latest security best practices and adapt these guidelines to your specific project needs. Always prioritize security as an integral part of your development process.

# Core Architecture Standards for Parcel This document outlines the core architecture standards for developing applications using Parcel. These standards promote maintainability, performance, security, and consistency across projects. They are tailored to the latest version of Parcel and emphasize modern best practices. ## 1. Project Structure and Organization The project structure should be clear, logical, and scalable. This helps development teams navigate the codebase, understand dependencies, and onboard new members quickly. ### 1.1. Standard Directory Layout * **Do This:** Adopt a consistent directory structure that separates source code, assets, and configuration files. """ my-parcel-project/ ├── src/ # Source code │ ├── components/ # Reusable components (e.g., React, Vue) │ ├── pages/ # Route-specific components or pages │ ├── assets/ # Static assets (images, fonts, etc.) │ ├── styles/ # Global styles │ ├── index.js # Main entry point │ └── app.js # Primary application logic ├── dist/ # Output directory (generated by Parcel) - should be in .gitignore ├── .parcelrc # Parcel configuration file ├── package.json # Project dependencies and scripts └── README.md # Project documentation """ * **Don't Do This:** Scatter files arbitrarily throughout the project. Avoid a flat structure for any directory (especially "/src"). * **Why:** Consistent structure simplifies navigation, dependency tracking, and build processes. It makes projects easier to understand and maintain over time. ### 1.2. Entry Point * **Do This:** Define a clear entry point for your application, typically named "index.js" or "app.js" inside the "src/" directory. This is where Parcel will begin its bundling process. Use a plain JavaScript or Typescript file as your main entry and import any frameworks or libraries in that file. """javascript // src/index.js import React from 'react'; import ReactDOM from 'react-dom/client'; import App from './app'; import './styles/global.css'; // Import global styles const root = ReactDOM.createRoot(document.getElementById('root')); root.render(<App />); """ * **Don't Do This:** Have multiple, ambiguous entry points or rely on implicit file loading order. Avoid placing UI framework initialization code inside HTML. * **Why:** A single, well-defined entry point provides clarity and simplifies the build process. ### 1.3. Component-Based Architecture * **Do This:** Organize your code into reusable components. Use components from frameworks like React, Vue, or Svelte if you use these technologies. Separate the markup, logic, and styling for each component. """javascript // src/components/Button.js import React from 'react'; import './Button.css'; function Button({ children, onClick }) { return ( <button className="button" onClick={onClick}> {children} </button> ); } export default Button; """ """css /* src/components/Button.css */ .button { background-color: #4CAF50; border: none; color: white; padding: 15px 32px; text-align: center; text-decoration: none; display: inline-block; font-size: 16px; cursor: pointer; } """ * **Don't Do This:** Write monolithic files that mix markup, logic, and styling. Avoid needlessly large components; prefer breaking down into smaller, composable parts. * **Why:** Component-based architecture promotes code reuse, maintainability, and testability. ### 1.4. Assets Directory * **Do This:** Store static assets (images, fonts, etc.) in a dedicated "assets/" directory (or subdirectories). Reference these assets using relative paths. """html <!-- src/components/Logo.js --> import React from 'react'; import logo from '../assets/images/logo.png'; // Import the logo function Logo() { return <img src={logo} alt="Logo" />; } export default Logo; """ * **Don't Do This:** Embed assets directly in code as base64 strings or store them in arbitrary locations. * **Why:** Organized assets simplify management and optimization. Parcel handles these assets efficiently, optimizing and versioning them. ## 2. Parcel Configuration (.parcelrc) Parcel's behavior can be customized with a ".parcelrc" file. Use this file to configure transforms, resolvers, and other aspects of the build process. The ".parcelrc" should be placed in the root of your project. ### 2.1. Transformers * **Do This:** Use transformers to process files with custom logic (e.g., transpiling TypeScript, processing CSS modules). Custom transformations should only be used when you must change how Parcel processes files. Prefer community plugins or built-in Parcel functionality first. """json // .parcelrc { "transformers": { "*.ts": ["@parcel/transformer-typescript-tsc"], "*.css": ["@parcel/transformer-css", "@parcel/transformer-postcss"] } } """ * **Don't Do This:** Neglect to configure transformers when using non-standard file types or language features. * **Why:** Transformers extend Parcel's functionality, allowing it to handle various file types and preprocessing steps. ### 2.2. Resolvers * **Do This:** Configure resolvers if you need custom module resolution logic (e.g., mapping module names to specific files). Custom resolvers are a very rare need, but can configure where Parcel looks to find files. """json // .parcelrc { "resolvers": ["@parcel/resolver-glob", "..."] } """ * **Don't Do This:** Rely on default resolvers if your project has unusual module resolution requirements. * **Why:** Resolvers control how Parcel finds modules, enabling advanced project structures and dependency management. ### 2.3. Extensions * **Do This:** Use the "extends" property to inherit configurations from shareable presets. This lets you reuse common configurations across projects. """json // .parcelrc { "extends": "@parcel/config-default" } """ * **Don't Do This:** Duplicate configuration across multiple projects. * **Why:** Extensions promote consistency and reduce boilerplate. ## 3. Module Bundling and Optimization Parcel excels at module bundling and optimization. Leverage its features to improve performance. ### 3.1. Dynamic Imports * **Do This:** Use dynamic imports ("import()") for code splitting and lazy loading components or modules only when needed. """javascript // src/app.js async function loadComponent() { const { default: Component } = await import('./components/MyComponent'); // Use Component } """ * **Don't Do This:** Load all code upfront unnecessarily, especially for large components or modules only used in specific scenarios. * **Why:** Dynamic imports reduce initial load time by deferring the loading of non-essential code. ### 3.2. Tree Shaking * **Do This:** Write modular code that allows Parcel to effectively tree-shake unused code. Ensure that imports are specific and avoid importing the entire library if only some parts are needed. """javascript // Instead of: import _ from 'lodash'; _.map(items, (item) => item.name); // Do This (if you only need map): import map from 'lodash/map'; map(items, (item) => item.name); """ * **Don't Do This:** Write code that prevents Parcel from identifying and removing dead code. Avoid importing entire libraries when only a few functions are needed. * **Why:** Tree shaking reduces bundle size by eliminating unused code. ### 3.3. Asset Optimization * **Do This:** Optimize images and other assets. While Parcel handles some optimization, use tools like ImageOptim or TinyPNG for further compression. Configure Parcel to handle different image sizes using "<img srcset="" sizes="" />" in HTML. """html <!-- index.html --> <img src="./src/assets/images/my-image.jpg" srcset="./src/assets/images/my-image@2x.jpg 2x" alt="My Image"> """ * **Don't Do This:** Include large, unoptimized assets that increase bundle size and load time. * **Why:** Optimized assets improve performance by reducing file sizes and load times. ### 3.4. Production Builds * **Do This:** Use the "parcel build" command for production builds and ensure your environment is set to production to trigger optimizations like minification and tree shaking. """bash parcel build src/index.html --dist-dir ./dist --no-source-maps """ * **Don't Do This:** Deploy development builds to production. Avoid including source maps in production. * **Why:** Production builds apply optimizations that significantly reduce bundle size and improve performance. Removing source maps protects code. ## 4. Code Style and Conventions Consistent code style improves readability and maintainability. ### 4.1. Linting and Formatting * **Do This:** Use ESLint and Prettier to enforce consistent code style and catch potential errors. """json // .eslintrc.js module.exports = { "extends": ["eslint:recommended", "plugin:react/recommended"], "parserOptions": { "ecmaVersion": 2023, "sourceType": "module", "ecmaFeatures": { "jsx": true } }, "env": { "browser": true, "es6": true, "node": true }, "rules": { "no-unused-vars": "warn", "react/prop-types": "off" } }; """ """json // .prettierrc.js module.exports = { semi: true, trailingComma: "es5", singleQuote: true, printWidth: 120, tabWidth: 2, }; """ * **Don't Do This:** Ignore linting and formatting errors. * **Why:** Consistent code style improves readability and reduces the likelihood of errors. Automated formatting reduces time spent on style issues during code reviews. ### 4.2. Naming Conventions * **Do This:** Use descriptive and consistent naming conventions for variables, functions, and components. Prefer camelCase for variables and function names, PascalCase for React components, and UPPER_SNAKE_CASE for constants. """javascript // Good const userProfile = { ... }; function calculateTotal(amount, taxRate) { ... } function UserProfileComponent() { ... } const MAX_USERS = 100; // Bad const a = { ... }; // Non-descriptive function calc(x, y) { ... } // Ambiguous """ * **Don't Do This:** Use short, cryptic, or inconsistent names. * **Why:** Clear naming improves code readability and understandability. ### 4.3. Commenting * **Do This:** Write clear and concise comments to explain complex logic or non-obvious code. Document component props and function parameters. """javascript /** * Calculates the total price including tax. * @param {number} amount - The base amount. * @param {number} taxRate - The tax rate (e.g., 0.05 for 5%). * @returns {number} The total price. */ function calculateTotal(amount, taxRate) { // Calculate the tax amount const tax = amount * taxRate; return amount + tax; } """ * **Don't Do This:** Over-comment obvious code or under-comment complex code. * **Why:** Comments improve code maintainability and help other developers understand the code. ## 5. Error Handling and Logging Robust error handling and logging are essential for debugging and maintaining applications. ### 5.1. Error Boundaries * **Do This:** Use error boundaries in React to catch JavaScript errors in component trees. """javascript // src/components/ErrorBoundary.js import React, { Component } from 'react'; class ErrorBoundary extends Component { constructor(props) { super(props); this.state = { hasError: false }; } static getDerivedStateFromError(error) { return { hasError: true }; } componentDidCatch(error, errorInfo) { console.error(error, errorInfo); // Log the error } render() { if (this.state.hasError) { return <h1>Something went wrong.</h1>; } return this.props.children; } } export default ErrorBoundary; """ """javascript // Usage in a component import ErrorBoundary from './ErrorBoundary'; function MyComponent() { return ( <ErrorBoundary> {/* Component that might throw an error */} </ErrorBoundary> ); } """ * **Don't Do This:** Allow errors to crash the entire application. * **Why:** Error boundaries prevent errors in one component from affecting the entire application. ### 5.2. Logging * **Do This:** Use a logging library (e.g., "console.log", "winston", "Logger") to log important events and errors. Include sufficient information for debugging. In production, use a centralized logging system. """javascript // Example with console.log try { // Some code that might throw an error } catch (error) { console.error('An error occurred:', error); } """ * **Don't Do This:** Over-log in production or log sensitive information. Remove debugging logs before deploying to production. * **Why:** Logging provides valuable insights into application behavior and helps diagnose issues. ## 6. Security Best Practices Implement security best practices to protect your application from vulnerabilities. ### 6.1. Dependency Management * **Do This:** Regularly audit and update dependencies using "npm audit" or "yarn audit" to identify and fix vulnerabilities. Use tools like Snyk, or Dependabot integrated into version control, especially GitHub, that automatically open pull requests to keep dependencies up to date """bash npm audit """ * **Don't Do This:** Use outdated dependencies with known vulnerabilities. Ignore audit warnings. * **Why:** Vulnerable dependencies can expose your application to security risks. ### 6.2. Input Validation * **Do This:** Validate all user inputs to prevent injection attacks (e.g., XSS, SQL injection). Sanitize user inputs before displaying them. """javascript // Example (basic) function sanitizeInput(input) { return input.replace(/</g, '&lt;').replace(/>/g, '&gt;'); } const userInput = '<script>alert("XSS");</script>'; const sanitizedInput = sanitizeInput(userInput); // Use sanitizedInput safely """ * **Don't Do This:** Trust user inputs without validation. * **Why:** Input validation prevents malicious users from injecting harmful code into your application. ### 6.3. Environment Variables * **Do This:** Store sensitive information (e.g., API keys, database passwords) in environment variables. Use tools like "dotenv" or "cross-env" to manage environment variables. Never commit such vars to source control.. Use a ".env.example" or ".env.sample" file to document which vars are needed. """javascript // Accessing environment variables const apiKey = process.env.API_KEY; """ * **Don't Do This:** Hardcode sensitive information in your code or configuration files. * **Why:** Environment variables prevent sensitive information from being exposed in code repositories. ## 7. Testing Implement comprehensive testing strategies to ensure the quality and reliability of your application. ### 7.1. Unit Tests * **Do This:** Write unit tests for individual components and functions to verify their correctness. Use testing frameworks like Jest or Mocha. """javascript // Example with Jest test('adds 1 + 2 to equal 3', () => { expect(1 + 2).toBe(3); }); """ * **Don't Do This:** Neglect to write unit tests for critical components and functions. * **Why:** Unit tests ensure that individual parts of the code function correctly. ### 7.2. Integration Tests * **Do This:** Write integration tests to verify the interaction between different components or modules. Use frameworks like Cypress or Puppeteer for end-to-end integration testing. * **Don't Do This:** Rely solely on unit tests without verifying the integration of different parts of the application. * **Why:** Integration tests ensure that different parts of the code work together correctly. ### 7.3. Code Coverage * **Do This:** Aim for high code coverage to ensure that most of your code is tested. Use code coverage tools to measure the percentage of code covered by tests. * **Don't Do This:** Equate high code coverage with high-quality tests. Focus on testing critical functionality and edge cases. * **Why:** Code coverage provides a metric for measuring the extent to which your code is tested. By adhering to these core architectural standards, development teams can build robust, maintainable, and scalable Parcel applications. This consistent approach ensures code quality, reduces technical debt, and accelerates development cycles.

# Component Design Standards for Parcel This document outlines the coding standards for component design within Parcel projects. It focuses on creating reusable, maintainable, and performant components using modern JavaScript (ES Modules) and front-end frameworks (e.g., React, Vue, Svelte) commonly used with Parcel. These standards leverage Parcel's capabilities for zero-configuration bundling, hot module replacement (HMR), and automatic code splitting. ## 1. Component Architecture and Organization ### 1.1. Directory Structure **Standard:** Organize components into a clear and well-defined directory structure. Use a "components" directory at the root (or feature directory) and group related components within subdirectories. **Do This:** """ src/ ├── components/ │ ├── Button/ │ │ ├── Button.jsx │ │ ├── Button.module.css │ │ └── index.js │ ├── Input/ │ │ ├── Input.jsx │ │ ├── Input.module.css │ │ └── index.js │ └── Card/ │ ├── Card.jsx │ ├── Card.module.css │ └── index.js ├── App.jsx └── index.js """ **Don't Do This:** """ src/ ├── components/ │ ├── Button.jsx │ ├── Input.jsx │ └── Card.jsx ├── App.jsx └── index.js """ **Why:** A structured directory promotes maintainability and scalability. Grouping related components makes it easier to locate, understand, and modify code. Using an "index.js" file within each component directory facilitates cleaner imports (see 1.2). ### 1.2. Component Entry Points (index.js) **Standard:** Use "index.js" files within component directories to export the component and any related utilities. **Do This:** """javascript // src/components/Button/index.js export { default as Button } from './Button'; """ **Don't Do This:** Directly importing the component file: """javascript import Button from './components/Button/Button'; // Avoid this """ **Why:** Using "index.js" provides a single entry point for each component, simplifying imports and allowing for future expansion without breaking existing code. It decouples the internal file structure from the API used by other modules. Parcel automatically resolves these imports. ### 1.3. Types of Components **Standard:** Distinguish between presentation (dumb), container (smart), and utility components. * **Presentation Components:** Focus solely on rendering UI. Receive data via props. No side effects. * **Container Components:** Handle data fetching, state management, and pass data to presentation components. Contain logic and orchestrate the user experience. * **Utility Components/Hooks:** Reusable logic or UI elements that can be used across multiple components (e.g., custom hooks, formatters). **Example (React):** """jsx // Presentation Component (src/components/Button/Button.jsx) import styles from './Button.module.css'; function Button({ children, onClick, ...props }) { return ( <button className={styles.button} onClick={onClick} {...props}> {children} </button> ); } export default Button; // Container Component (src/containers/UserList.jsx) import React, { useState, useEffect } from 'react'; import { Button } from '../components/Button'; //Correct import import UserCard from '../components/Card'; function UserList() { const [users, setUsers] = useState([]); useEffect(() => { async function fetchData() { const response = await fetch('https://jsonplaceholder.typicode.com/users'); const data = await response.json(); setUsers(data); } fetchData(); }, []); return ( <div> {users.map(user => ( <UserCard key={user.id} name={user.name} email={user.email} /> ))} <Button onClick={() => alert('Clicked!')}>Fetch More</Button> </div> ); } export default UserList; //src/components/Card/Card.jsx import styles from './Card.module.css'; function Card({ name, email }) { return ( <div className={styles.card}> <h3>{name}</h3> <p>{email}</p> </div> ); } export default Card; """ **Why:** This separation of concerns improves testability, reusability, and maintainability. Presentation components are easier to reason about and test because they have no side effects. ## 2. Component Implementation ### 2.1. Functional Components and Hooks (React) **Standard:** Prefer functional components with hooks over class components in React. For Vue, utilize composition API with "setup()". For Svelte, leverage the built-in reactivity effectively. **Do This (React):** """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; """ **Don't Do This (React - legacy):** """jsx import React from 'react'; class Counter extends React.Component { constructor(props) { super(props); this.state = { count: 0 }; } render() { return ( <div> <p>Count: {this.state.count}</p> <button onClick={() => this.setState({ count: this.state.count + 1 })}> Increment </button> </div> ); } } export default Counter; """ **Why:** Functional components are more concise, easier to test, and encourage better code organization. Hooks provide a powerful way to manage state and side effects within functional components. ### 2.2. Styling **Standard:** Use CSS Modules for component-level styling. Alternatively, consider CSS-in-JS solutions, Styled Components, or Emotion, but be mindful of increased bundle size and runtime overhead if using purely client-side solutions. For shared styling concerns, use a global styles file or preprocessor (Sass, Less). **Do This (CSS Modules):** """jsx // Button.jsx import styles from './Button.module.css'; function Button({ children, onClick }) { return ( <button className={styles.button} onClick={onClick}> {children} </button> ); } export default Button; """ """css /* Button.module.css */ .button { background-color: #4CAF50; border: none; color: white; padding: 15px 32px; text-align: center; text-decoration: none; display: inline-block; font-size: 16px; cursor: pointer; } .button:hover { background-color: #3e8e41; } """ **Why:** CSS Modules provide automatic scoping of CSS rules, preventing naming conflicts and ensuring styles are only applied to the intended component. Parcel automatically handles CSS Modules with zero configuration. Alternative CSS-in-JS solutions offer flexibility, but may impact performance if used excessively. ### 2.3. Prop Types **Standard:** Define prop types for all components, especially for larger projects or team collaboration (using PropTypes library or TypeScript). **Do This (React PropTypes):** """jsx import React from 'react'; import PropTypes from 'prop-types'; function Greeting({ name }) { return <p>Hello, {name}!</p>; } Greeting.propTypes = { name: PropTypes.string.isRequired, }; export default Greeting; """ **Do This (TypeScript):** """tsx interface GreetingProps { name: string; } function Greeting({ name }: GreetingProps) { return <p>Hello, {name}!</p>; } export default Greeting; """ **Why:** Defining prop types helps catch errors early, improves code readability, and provides documentation for component usage. TypeScript offers more compile-time safety, while PropTypes provides runtime validation. ### 2.4. State Management **Standard:** Choose an appropriate state management solution based on the complexity of the application. For simple component-level state, use React's "useState" or Vue's "reactive". For more complex applications, consider Context API, Redux, Zustand, or Vuex. **Do This (React Context API):** """jsx // Create a context (src/context/ThemeContext.js) import React, { createContext, useState } from 'react'; export const ThemeContext = createContext(); export function ThemeProvider({ children }) { const [theme, setTheme] = useState('light'); const toggleTheme = () => { setTheme(theme === 'light' ? 'dark' : 'light'); }; return ( <ThemeContext.Provider value={{ theme, toggleTheme }}> {children} </ThemeContext.Provider> ); } // Use the context in components import React, { useContext } from 'react'; import { ThemeContext } from './ThemeContext'; function ThemedButton() { const { theme, toggleTheme } = useContext(ThemeContext); return ( <button onClick={toggleTheme}> Switch to {theme === 'light' ? 'dark' : 'light'} theme </button> ); } export default ThemedButton; """ **Why:** Proper state management simplifies data flow, improves debugging, and promotes code reusability. Choosing the right solution depends on the scope and complexity of state within the application. ### 2.5. Event Handling **Standard:** Handle events consistently and avoid inline event handlers. Prefer binding event handlers in the constructor (for class components - avoid using them if you can) or using arrow functions or the "useCallback" hook. **Do This (React - useCallback):** """jsx import React, { useCallback } from 'react'; function MyComponent({ onClick }) { const handleClick = useCallback(() => { onClick('Hello from MyComponent!'); }, [onClick]); return <button onClick={handleClick}>Click Me</button>; } export default MyComponent; """ **Don't Do This (Inline Event Handler):** """jsx function MyComponent({ onClick }) { return <button onClick={() => onClick('Hello from MyComponent!')}>Click Me</button>; } export default MyComponent; """ **Why:** Binding event handlers correctly prevents unnecessary re-renders and improves performance. "useCallback" memoizes the event handler function, ensuring it only changes when its dependencies change. Inline event handlers create new functions on every render, causing re-renders for child components. ### 2.6. Component Composition **Standard:** Utilize component composition over inheritance. "Favor composition over inheritance." Use props.children to pass elements into components, and render props or hooks to share logic. **Do This (React - props.children):** """jsx // Layout component function Layout({ children }) { return ( <div className="layout"> <header>Header</header> <main>{children}</main> <footer>Footer</footer> </div> ); } // Usage <Layout> <h1>Content</h1> <p>Some text here.</p> </Layout> """ **Why:** Composition promotes reusability and flexibility. It makes components easier to reason about and test, as each component has a single responsibility. Inheritance can lead to complex and tightly coupled hierarchies. ### 2.7. Asynchronous Operations **Standard:** Handle asynchronous operations (API calls, data fetching) carefully. Use "async/await" syntax within components or custom hooks. Show loading states and handle errors gracefully. **Do This (React):** """jsx import React, { useState, useEffect } from 'react'; function DataFetcher({ url }) { const [data, setData] = useState(null); const [loading, setLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { async function fetchData() { try { const response = await fetch(url); if (!response.ok) { throw new Error("HTTP error! status: ${response.status}"); } const json = await response.json(); setData(json); } catch (e) { setError(e); } finally { setLoading(false); } } fetchData(); }, [url]); if (loading) return <p>Loading...</p>; if (error) return <p>Error: {error.message}</p>; if (!data) return <p>No data to display.</p>; return ( <ul> {data.map(item => ( <li key={item.id}>{item.name}</li> ))} </ul> ); } export default DataFetcher; """ **Why:** Proper error handling and loading states provide a better user experience. "async/await" makes asynchronous code easier to read and write. Parcel automatically handles polyfilling "async/await" syntax for older browsers. ### 2.8. Accessibility (a11y) **Standard:** Build accessible components by following WAI-ARIA guidelines. Use semantic HTML elements, provide alternative text for images, ensure keyboard navigation, and use ARIA attributes appropriately. **Do This:** """jsx <img src="logo.png" alt="Company Logo" /> <button aria-label="Close dialog">Close</button> """ **Why:** Accessibility ensures that websites and applications are usable by people with disabilities. Following accessibility guidelines is essential for inclusive design. Use tools like axe DevTools to check for accessibility issues. ## 3. Parcel-Specific Considerations ### 3.1. Automatic Code Splitting **Standard:** Leverage Parcel's automatic code splitting for improved performance. Parcel automatically splits the code into separate bundles based on the import graph. **Example:** If a component is only used on a specific route, Parcel will create a separate bundle for that route. **Why:** Code splitting reduces the initial load time of the application by only loading the code that is needed for the current page or component. ### 3.2. Dynamic Imports **Standard:** Use dynamic imports for lazy-loading components or modules that are not immediately needed. **Do This:** """jsx import React, { useState, useEffect } from 'react'; function MyComponent() { const [Component, setComponent] = useState(null); useEffect(() => { import('./LazyComponent') .then(module => setComponent(() => module.default)) .catch(err => console.error(err)); }, []); if (!Component) { return <p>Loading...</p>; } return <Component />; } export default MyComponent; //LazyComponent.js function LazyComponent(){ return ( <div> This is a lazy loaded Component </div> ) } export default LazyComponent; """ **Why:** Dynamic imports allow for on-demand loading of code, further reducing the initial load time. Parcel automatically handles dynamic imports and creates separate bundles for the imported modules. ### 3.3. Hot Module Replacement (HMR) **Standard:** Take advantage of Parcel's HMR to improve the development experience. HMR allows you to update code without reloading the entire page. **Why:** HMR significantly speeds up the development workflow by preserving the application state while updating code changes. ## 4. Best Practices and Anti-Patterns ### 4.1. Anti-Pattern: Over-Engineering **Avoid:** Creating overly complex components for simple tasks. Keep components focused and easy to understand. **Why:** Over-engineering leads to unnecessary complexity, making code harder to maintain and debug. ### 4.2. Best Practice: Reusability **Strive for:** Creating reusable components that can be used across multiple parts of the application. Use props to configure components and avoid hardcoding values. **Why:** Reusable components reduce code duplication, improve maintainability, and promote consistency across the application. ### 4.3. Anti-Pattern: Deeply Nested Components **Avoid:** Creating deeply nested component hierarchies, as this can lead to performance issues and make it difficult to reason about data flow. **Why:** Deeply nested components can cause unnecessary re-renders and increase the complexity of the application. Consider using context or state management solutions to simplify data flow. ### 4.4. Best Practice: Testing **Implement:** Unit tests and integration tests for all components. Use testing libraries like Jest, Mocha, or Testing Library (React Testing Library). **Why:** Testing ensures the quality and reliability of components. It helps catch errors early and makes it easier to refactor code. ### 4.5. Anti-Pattern: Mutating Props **Avoid:** Mutating props directly within components. Props should be treated as read-only. **Why:** Mutating props can lead to unexpected side effects and make it difficult to reason about data flow. By adhering to these component design standards, you can build maintainable, reusable, and performant applications with Parcel. They also improve the reliability and consistency of the code.

# State Management Standards for Parcel This document outlines the coding standards for managing application state in Parcel projects. It aims to provide best practices for data flow, reactivity, and overall state management within the Parcel ecosystem, promoting maintainability, performance, and a consistent development experience. It is designed to work with the latest version of Parcel. ## 1. Introduction to State Management in Parcel Projects Parcel, as a bundler, doesn't inherently dictate a specific state management solution. It's unopinionated about the frameworks and libraries you choose to use for managing state. Therefore, the choice of state management library or pattern largely depends on the complexity and scale of your application. These guidelines focus on principles that apply irrespective of the specific library you select when building your Parcel application. ### Understanding Parcel's Role Parcel's primary responsibility is bundling and transforming your code, optimizing it for the browser. This means Parcel is concerned with *how* your code is packaged, not *what* your code does. However, the *what* (the application logic, including state management) significantly impacts the *how*. Using a well-structured state management approach provides clearer dependencies for Parcel to optimize and ensures efficient code splitting. ### Key Considerations * **Complexity:** Simple applications may only require basic component state or context. More complex ones might benefit from dedicated state management libraries. * **Maintainability:** Code should be easy to understand, debug and modify. * **Performance:** Reduce unnecessary re-renders and optimize data flow. * **Scalability:** Design your state management system to scale with the growth of your application. * **Bundle Size:** Be mindful of the impact of large state management libraries on your final bundle size. Parcel's code splitting can help mitigate this, but conscious library selection is important. ## 2. Core Principles of State Management Regardless of the chosen library or pattern, these core principles should guide state management practices in Parcel projects. ### 2.1 Unidirectional Data Flow * **Do This:** Implement a unidirectional data flow pattern where data changes propagate in a single direction. This makes it easier to trace state changes and debug issues. * **Don't Do This:** Avoid two-way data binding or direct manipulation of state outside of the intended channels. * **Why:** Predictability and easier debugging. Unidirectional data flow reduces the likelihood of unintended side effects and makes it easier to reason about the state of the application at any given time. * **Example (React + Redux):** """javascript // Action const increment = () => ({ type: 'INCREMENT' }); // Reducer const counterReducer = (state = 0, action) => { switch (action.type) { case 'INCREMENT': return state + 1; default: return state; } }; // Store import { createStore } from 'redux'; const store = createStore(counterReducer); // Component import React from 'react'; import { connect } from 'react-redux'; const Counter = ({ counter, increment }) => ( <div> <p>Counter: {counter}</p> <button onClick={increment}>Increment</button> </div> ); const mapStateToProps = (state) => ({ counter: state }); const mapDispatchToProps = { increment }; export default connect(mapStateToProps, mapDispatchToProps)(Counter); """ ### 2.2 Immutability * **Do This:** Treat state as immutable. When state needs to be updated, create a new copy with the desired changes instead of modifying the existing state directly. * **Don't Do This:** Directly mutate state variables. Relying on mutation makes tracking changes difficult. * **Why:** Immutability simplifies change detection and allows for efficient updates in UI frameworks like React. It also improves predictability. * **Example (Using spread operator for immutability):** """javascript // Updating an object immutability const initialState = { name: 'Alice', age: 30, }; const updatedState = { ...initialState, age: 31 }; // Creates a new object console.log(initialState.age); // 30 console.log(updatedState.age); // 31 """ ### 2.3 Single Source of Truth * **Do This:** Designate a single source of truth for each piece of application state. Avoid duplicating data across multiple components or stores. * **Don't Do This:** Store the same data in different places, leading to potential inconsistencies. * **Why:** Eliminates data inconsistencies and simplifies updates. * **Example (Centralized store with React Context):** """javascript // StateContext.jsx import React, { createContext, useState, useContext } from 'react'; const StateContext = createContext(); export const StateProvider = ({ children }) => { const [count, setCount] = useState(0); const increment = () => { setCount(count + 1); }; return ( <StateContext.Provider value={{ count, increment }}> {children} </StateContext.Provider> ); }; export const useStateContext = () => useContext(StateContext); // Usage in a component: // MyComponent.jsx import React from 'react'; import { useStateContext } from './StateContext'; const MyComponent = () => { const { count, increment } = useStateContext(); return ( <div> <p>Count: {count}</p> <button onClick={increment}>Increment</button> </div> ); }; export default MyComponent; """ """javascript // index.js (entry point) import React from 'react'; import ReactDOM from 'react-dom/client'; import App from './App'; import { StateProvider } from './StateContext'; const root = ReactDOM.createRoot(document.getElementById('root')); root.render( <React.StrictMode> <StateProvider> <App /> </StateProvider> </React.StrictMode> ); """ ### 2.4 Separation of Concerns * **Do This:** Separate state management logic from UI components. Avoid embedding state management directly within components. * **Don't Do This:** Mixing state updates and UI logic within the same component. * **Why:** Improves code organization, testability, and reusability. This often means extracting state logic into custom hooks, reducers, or service layers. * **Example (Custom React Hook):** """javascript // useCounter.js (Custom Hook) import { useState } from 'react'; const useCounter = (initialValue = 0) => { const [count, setCount] = useState(initialValue); const increment = () => { setCount(count + 1); }; const decrement = () => { setCount(count - 1); }; return { count, increment, decrement }; }; export default useCounter; // CounterComponent.jsx import React from 'react'; import useCounter from './useCounter'; const CounterComponent = () => { const { count, increment, decrement } = useCounter(); return ( <div> <p>Count: {count}</p> <button onClick={increment}>Increment</button> <button onClick={decrement}>Decrement</button> </div> ); }; export default CounterComponent; """ ### 2.5 Minimizing Global State * **Do This:** Only store data in global state that is truly needed globally. Use component-local state or context for data specific to a particular component or subtree. * **Don't Do This:** Store every piece of data in a global store. * **Why:** Reduces unnecessary re-renders, minimizes dependencies, and improves performance. Global state increases application complexity and can lead to performance bottlenecks if not managed carefully. ## 3. State Management Approaches in Parcel Since Parcel is unopinionated, you're free to choose from a variety of approaches. Here are some common ones, along with considerations for their use with Parcel. ### 3.1 Component State (useState) * **Description:** The simplest approach, using the "useState" hook in React to manage state within individual components. * **When to Use:** For simple components with limited state requirements. It works well for isolated UI elements. * **Parcel Considerations:** No specific Parcel-related considerations. Parcel will bundle and optimize the code as usual. """javascript import React, { useState } from 'react'; const MyComponent = () => { const [count, setCount] = useState(0); return ( <div> <p>Count: {count}</p> <button onClick={() => setCount(count + 1)}>Increment</button> </div> ); }; export default MyComponent; """ ### 3.2 Context API * **Description:** React's built-in mechanism for sharing state across a component tree without prop drilling. * **When to Use:** When state needs to be accessed by multiple components within a specific part of the application. Good for themes, user authentication, or other application-wide settings. * **Parcel Considerations:** Again, no specific Parcel concerns. Parcel optimizes the React code transparently. """javascript // ThemeContext.jsx import React, { createContext, useState, useContext } from 'react'; const ThemeContext = createContext(); export const ThemeProvider = ({ children }) => { const [theme, setTheme] = useState('light'); const toggleTheme = () => { setTheme(theme === 'light' ? 'dark' : 'light'); }; return ( <ThemeContext.Provider value={{ theme, toggleTheme }}> {children} </ThemeContext.Provider> ); }; export const useTheme = () => useContext(ThemeContext); // Usage in component import React from 'react'; import { useTheme } from './ThemeContext'; const MyComponent = () => { const { theme, toggleTheme } = useTheme(); return ( <div style={{ backgroundColor: theme === 'light' ? 'white' : 'black', color: theme === 'light' ? 'black' : 'white' }}> <p>Current Theme: {theme}</p> <button onClick={toggleTheme}>Toggle Theme</button> </div> ); }; export default MyComponent; """ ### 3.3 Redux/Redux Toolkit * **Description:** A predictable state container for JavaScript apps. Centralizes application state and enforces a unidirectional data flow. * **When to Use:** For complex applications where state is shared across many components, and predictable state management is crucial. Redux Toolkit simplifies Redux setup and usage. * **Parcel Considerations:** Parcel can efficiently bundle Redux code and optimize it for production. It's important to configure Parcel correctly for tree shaking to remove unused Redux code. """javascript // store.js (Redux Toolkit) import { configureStore, createSlice } from '@reduxjs/toolkit'; const counterSlice = createSlice({ name: 'counter', initialState: { value: 0, }, reducers: { increment: (state) => { state.value += 1; }, decrement: (state) => { state.value -= 1; }, }, }); export const { increment, decrement } = counterSlice.actions; export const store = configureStore({ reducer: { counter: counterSlice.reducer, }, }); // Component example import React from 'react'; import { useSelector, useDispatch } from 'react-redux'; import { increment, decrement } from './store'; const Counter = () => { const count = useSelector((state) => state.counter.value); const dispatch = useDispatch(); return ( <div> <p>Count: {count}</p> <button onClick={() => dispatch(increment())}>Increment</button> <button onClick={() => dispatch(decrement())}>Decrement</button> </div> ); }; export default Counter; """ ### 3.4 Zustand * **Description:** A small, fast and scalable bearbones state-management solution using simplified flux principles. * **When to Use:** For mid-sized applications or parts of larger apps when Redux feels like overkill, but component state and Context feel limiting. * **Parcel Considerations:** Parcel will handle Zustand without issue. Keeping your store definitions small and well-modularized allows Parcel to optimize bundles appropriately. """javascript // store.js (Zustand) import { create } from 'zustand' const useStore = create((set) => ({ count: 0, increment: () => set((state) => ({ count: state.count + 1 })), decrement: () => set((state) => ({ count: state.count - 1 })), })) export default useStore; // Component example import React from 'react'; import useStore from './store'; const Counter = () => { const { count, increment, decrement } = useStore(); return ( <div> <p>Count: {count}</p> <button onClick={increment}>Increment</button> <button onClick={decrement}>Decrement</button> </div> ); }; export default Counter; """ ### 3.5 Jotai * **Description:** Primitive and flexible state management for React based on an atomic model. * **When to Use:** When you need fine-grained control over state updates and want to avoid re-renders in unrelated components. Works very well with concurrent React. * **Parcel Considerations:** Plays nicely with Parcel. Focus on keeping your atoms small and well-defined. """javascript // atoms.js (Jotai) import { atom } from 'jotai' export const countAtom = atom(0) // Component example import React from 'react'; import { useAtom } from 'jotai' import { countAtom } from './atoms' const Counter = () => { const [count, setCount] = useAtom(countAtom) return ( <div> <p>Count: {count}</p> <button onClick={() => setCount(count + 1)}>Increment</button> </div> ); }; export default Counter; """ ### 3.6 Recoil * **Description:** A state management library for React from Facebook, designed specifically for concurrent mode. Similar in some ways to Jotai, but with different tradeoffs. * **When to Use:** For complex applications using concurrent React, where predictable and efficient state updates are paramount. * **Parcel Considerations:** Requires proper configuration but integrates smoothly. Parcel optimizes the rendering. """javascript // atoms.js (Recoil) import { atom } from 'recoil'; export const countState = atom({ key: 'countState', // unique ID (globally unique) default: 0, // default value (aka initial value) }); // Component example import React from 'react'; import { useRecoilState } from 'recoil'; import { countState } from './atoms'; function Counter() { const [count, setCount] = useRecoilState(countState); return ( <div> <p>Count: {count}</p> <button onClick={() => setCount(count + 1)}>Increment</button> </div> ); } export default Counter; """ ## 4. Best Practices for Performance Efficient state management is crucial for optimal application performance. ### 4.1 Memoization * **Do This:** Use memoization to prevent unnecessary re-renders of components. React's "React.memo", "useMemo", and "useCallback" are essential tools. Redux's "reselect" library is also valuable. * **Don't Do This:** Neglect memoization, leading to frequent re-renders even when data hasn't changed. * **Why:** Improves performance by skipping re-renders when component props or state haven't changed. * **Example (React.memo):** """javascript import React from 'react'; const MyComponent = React.memo(({ data }) => { console.log('MyComponent rendered'); // Only renders when data prop changes return ( <p>Data: {data}</p> ); }); export default MyComponent; """ ### 4.2 Code Splitting * **Do This:** Utilize Parcel's built-in code splitting capabilities to break down your application into smaller chunks. Lazy-load components that are not immediately needed. * **Don't Do This:** Include all code in a single large bundle. * **Why:** Reduces initial load time and improves perceived performance. * **Example (Dynamic Import):** """javascript import React, { Suspense, lazy } from 'react'; const MyComponent = lazy(() => import('./MyComponent')); const App = () => ( <Suspense fallback={<div>Loading...</div>}> <MyComponent /> </Suspense> ); export default App; """ ### 4.3 Batch Updates * **Do This:** Batch state updates whenever possible to avoid triggering multiple re-renders. * **Don't Do This:** Performing multiple state updates in a short period without batching. * **Why:** Reduces the number of re-renders and improves performance. * **Example (Using "ReactDOM.unstable_batchedUpdates"):** """javascript import React from 'react'; import ReactDOM from 'react-dom/client'; const myFunc = () => { ReactDOM.unstable_batchedUpdates(() => { // Multiple state updates here setCount(count + 1); setValue(newValue); }); } """ ### 4.4 Selector Functions * **Do This:** Use selector functions to derive data from the store. Avoid performing complex calculations directly within components. * **Don't Do This:** Repeating complex calculations in multiple components. * **Why:** Improves performance by memoizing the results of calculations and preventing unnecessary re-renders. * **Example (Reselect with Redux):** """javascript import { createSelector } from 'reselect'; const getItems = (state) => state.items; const getFilter = (state) => state.filter; const getFilteredItems = createSelector( [getItems, getFilter], (items, filter) => items.filter(item => item.includes(filter)) ); """ ## 5. Common Anti-Patterns Avoid these common mistakes in your Parcel projects. ### 5.1 Prop Drilling * **Description:** Passing data through multiple layers of components that don't need it. * **Solution:** Use Context API, Redux, or a similar state management library to provide data directly to the components that need it. ### 5.2 Mutating State Directly * **Description:** Modifying state directly instead of creating a new copy. * **Solution:** Always create a new copy of the state when updating it using the spread operator or immutable data structures. ### 5.3 Over-reliance on Global State * **Description:** Storing too much data in global state, leading to unnecessary re-renders and increased complexity. * **Solution:** Use component-local state or context for data that is specific to a particular component or subtree. ### 5.4 Ignoring Performance * **Description:** Neglecting memoization, code splitting, and other performance optimization techniques. * **Solution:** Regularly profile your application to identify performance bottlenecks and implement appropriate optimizations. ## 6. Security Considerations ### 6.1 Sensitive Data * **Do This:** Avoid storing sensitive data (e.g., API keys, passwords) in client-side state. If necessary, encrypt it and store it securely. * **Don't Do This:** Storing sensitive information directly in the browser's local storage or in global state. * **Why:** Protecting user data and preventing security breaches. ### 6.2 Input Validation * **Do This:** Validate all user inputs before updating state to prevent malicious data from corrupting your application. * **Don't Do This:** Directly updating state with unfiltered user input. * **Why:** Preventing Cross-Site Scripting (XSS) attacks and other security vulnerabilities. ## 7. Conclusion By adhering to these standards, developers can build maintainable, performant, and secure Parcel applications with robust state management. Remember to choose the right state management approach based on the complexity of your application, and always prioritize unidirectional data flow, immutability, and separation of concerns. Continuously evaluate and refine your state management strategies as your application evolves.

# Testing Methodologies Standards for Parcel This document outlines the testing methodologies standards for Parcel projects. It provides guidelines for writing effective unit, integration, and end-to-end tests, ensuring maintainability, performance, and security. These standards are designed to be used by developers and as context for AI coding assistants. ## 1. General Testing Principles ### 1.1. Test Pyramid **Understanding the Test Pyramid:** The test pyramid is a conceptual model that guides the distribution of tests. It advocates for having a large base of unit tests, a smaller layer of integration tests, and a very thin layer of end-to-end tests. **Do This:** * **Write Many Unit Tests:** These should be the foundation of your testing strategy. * **Write Some Integration Tests:** Focus on how different parts of your application work together. * **Write Few End-to-End Tests:** These are more brittle and time-consuming to maintain, so limit their scope to critical user flows. **Don't Do This:** * **Rely Heavily on End-to-End Tests:** This leads to slow test suites and fragile tests. * **Neglect Unit Tests:** Without a solid base of unit tests, you'll miss many bugs early in the development process. **Why This Matters:** A balanced test pyramid provides comprehensive coverage while minimizing maintenance overhead and maximizing the speed of your test suite. ### 1.2. Test-Driven Development (TDD) **TDD Overview:** TDD is a software development process where you write a failing test before you write any production code. Then, you write the minimum amount of code to make the test pass, and finally, you refactor. **Do This:** * **Write Tests First:** Before implementing any new functionality, write a test that defines the expected behavior. * **Follow the Red-Green-Refactor Cycle:** Make the test fail (Red), make it pass (Green), then refactor (Refactor). * **Keep Tests Small and Focused:** Each test should verify one specific aspect of your code. **Don't Do This:** * **Write Production Code Before Tests:** This often leads to biased testing and incomplete coverage. * **Skip the Refactor Step:** Refactoring ensures that your code is clean, maintainable, and efficient. **Why This Matters:** TDD promotes better design, reduces bugs, and improves code quality. ### 1.3. Code Coverage **Coverage Metrics:** Code coverage measures the percentage of your codebase that is executed when running your tests. Common metrics include line coverage, branch coverage, and function coverage. **Do This:** * **Aim for High Coverage:** Strive for code coverage above 80% for critical modules. * **Use Coverage Tools:** Tools like Istanbul (nyc) can help you measure coverage. * **Review Coverage Reports:** Use coverage reports to identify gaps in your testing strategy. **Don't Do This:** * **Chase 100% Coverage Blindly:** High coverage doesn't guarantee bug-free code. Focus on testing critical logic and edge cases. * **Ignore Low Coverage Areas:** Low coverage often indicates potential bugs or untested features. **Why This Matters:** Code coverage metrics help you identify areas of your code that need more testing, reducing the risk of undetected bugs. ## 2. Unit Testing Standards ### 2.1. Scope and Focus **Unit Test Definition:** Unit tests verify the behavior of individual units of code (e.g., functions, classes, modules) in isolation. **Do This:** * **Isolate Units:** Use mocks, stubs, and spies to isolate the unit under test from its dependencies. * **Test Public API:** Focus on testing the public interface of your units. * **Test Edge Cases:** Always include tests for edge cases, boundary conditions, and error handling. **Don't Do This:** * **Test Implementation Details:** Avoid testing private methods or internal logic that may change during refactoring. * **Write Integration Tests as Unit Tests:** Unit tests should be fast and focused. **Why This Matters:** Proper unit testing ensures that each component of your application works correctly in isolation, making it easier to identify and fix bugs. ### 2.2. Tools and Libraries **Recommended Libraries:** Jest, Mocha, Chai, and Sinon are popular JavaScript testing libraries. Jest is often preferred for Parcel projects due to its ease of setup and built-in features. **Do This:** * **Use Jest:** Configure Jest in your Parcel project for unit testing. It provides a good balance of features and ease of use. * **Use Mocking Libraries:** Employ libraries like "jest.mock" or "sinon" for mocking dependencies. **Code Example (Jest):** """javascript // my-module.js export function add(a, b) { return a + b; } export function processData(data) { // some complex data processing return data.map(item => add(item, 10)); } """ """javascript // my-module.test.js import { add, processData } from './my-module'; jest.mock('./my-module', () => { const originalModule = jest.requireActual('./my-module'); return { ...originalModule, add: jest.fn((a, b) => originalModule.add(a, b) + 1), // Mock implementation }; }); describe('my-module', () => { it('should add two numbers correctly', () => { expect(add(2, 3)).toBe(5); }); it('should process data correctly', () => { const data = [1, 2, 3]; const result = processData(data); expect(result).toEqual([11, 12, 13]); }); it('should call the mocked add function', () => { processData([0]); expect(add).toHaveBeenCalled(); }); }); """ **Don't Do This:** * **Rely on Global State:** Avoid modifying global state in your tests, as it can lead to unpredictable results. * **Write Flaky Tests:** Ensure that your tests are deterministic and always produce the same result for the same input. **Why This Matters:** Choosing the right tools and following best practices ensures that your unit tests are reliable, maintainable, and effective. ### 2.3. Mocking Strategies **Types of Mocks:** Mocks are objects that simulate the behavior of real dependencies. Stubs, spies, and fakes are different types of mocks. * **Stubs:** Provide predefined responses to method calls. * **Spies:** Record method calls and arguments. * **Mocks:** Combine the features of stubs and spies. **Do This:** * **Use Mocks Wisely:** Mock dependencies when necessary to isolate the unit under test. * **Verify Interactions:** Use spies to verify that your unit interacts with its dependencies as expected. * **Mock External Services:** Mock external APIs and services to avoid relying on external resources during testing. **Code Example (Jest Mocks):** """javascript // api-service.js export async function fetchData(url) { const response = await fetch(url); return response.json(); } """ """javascript // api-service.test.js import { fetchData } from './api-service'; jest.mock('./api-service', () => ({ fetchData: jest.fn(() => Promise.resolve({ data: 'mocked data' })), })); describe('api-service', () => { it('should fetch data correctly', async () => { const data = await fetchData('https://example.com/api'); expect(data).toEqual({ data: 'mocked data' }); expect(fetchData).toHaveBeenCalledWith('https://example.com/api'); }); }); """ **Don't Do This:** * **Over-Mock:** Avoid mocking everything, as it can make your tests meaningless. * **Mock Too Early:** Defer mocking until you encounter actual dependencies that are difficult to test. **Why This Matters:** Effective mocking allows you to test your code in isolation, ensuring that it behaves correctly regardless of the state of its dependencies. ### 2.4. Asynchronous Code Testing **Handling Promises and Async/Await:** Testing asynchronous code requires special techniques to ensure that your tests wait for the asynchronous operations to complete. **Do This:** * **Use "async/await" in Tests:** Use "async/await" to handle promises in your tests. * **Use "resolves" and "rejects" Matchers:** Jest provides "resolves" and "rejects" matchers to test promises. * **Use "done" Callback:** If you're using Mocha or other libraries, use the "done" callback to signal the completion of an asynchronous test. **Code Example (Jest Async/Await):** """javascript // async-function.js export async function fetchData(url) { const response = await fetch(url); return response.json(); } """ """javascript // async-function.test.js import { fetchData } from './async-function'; describe('async-function', () => { it('should fetch data correctly', async () => { const data = await fetchData('https://example.com/api'); await expect(data).resolves.toEqual({ data: 'some data' }); }); it('should handle errors correctly', async () => { jest.spyOn(global, 'fetch').mockImplementation(() => Promise.reject('API error')); await expect(fetchData('https://example.com/api')).rejects.toEqual('API error'); }); }); """ **Don't Do This:** * **Forget to Await Promises:** If you don't "await" promises in your tests, the tests may complete before the asynchronous operations finish. * **Use "setTimeout" for Synchronization:** Avoid using "setTimeout" to wait for asynchronous operations, as it can lead to unreliable tests. **Why This Matters:** Proper handling of asynchronous code ensures that your tests accurately verify the behavior of asynchronous operations. ## 3. Integration Testing Standards ### 3.1. Scope and Purpose **Integration Test Definition:** Integration tests verify the interactions between different components or modules of your application. **Do This:** * **Test Component Interactions:** Focus on testing how different parts of your application work together. * **Use Real Dependencies When Possible:** Avoid mocking unless necessary. * **Test Data Flows:** Verify that data flows correctly between components. **Don't Do This:** * **Test Individual Units:** Integration tests should not focus on testing individual units in isolation. * **Duplicate Unit Tests:** Avoid duplicating the same tests in both unit and integration tests. **Why This Matters:** Integration tests ensure that your application's components work together correctly, catching integration-related bugs early. ### 3.2. Testing Parcel Bundles **Considerations for Parcel:** Parcel's bundling process impacts integration testing. Ensure tests run against the bundled output or mock the bundle behavior effectively. **Do This:** * **Test against build output:** Run integration tests against the production-ready output of Parcel (usually in the "dist" folder). This confirms that Parcel is correctly bundling assets and code. * **Mock module resolution:** In some cases, for performance or isolation, simulate Parcel's module resolution using Jest's module mocking capabilities. **Code Example (Integration Test with Parcel build):** """javascript //integration.test.js const {myAppFunction} = require('./dist/main.js'); // Assuming output is in dist/main.js describe('Integration Tests', () => { it('should execute the application flow', () => { const result = myAppFunction("test input"); expect(result).toBe('expected output'); }); }); """ **Configuration:** * Add a test script to "package.json" that runs "parcel build" followed by your integration tests. **Don't Do This:** * Assume the development environment perfectly mirrors the bundled production environment. **Why this matters:** Bundling changes code, assets, and dependency resolution. Testing against the final output is critical, especially for complex applications. ### 3.3. Database Testing **Connecting to Databases:** Integration tests often involve connecting to real or test databases. **Do This:** * **Use Test Databases:** Always use separate test databases to avoid polluting your production data. * **Seed Databases:** Seed your test databases with known data before running tests. * **Clean Up After Tests:** Clean up your test databases after running tests to ensure a clean environment. **Code Example (Integration Test with Database):** """javascript // db-integration.test.js import { connectToDatabase, queryDatabase } from './db-utils'; describe('Database Integration Tests', () => { let db; beforeAll(async () => { db = await connectToDatabase('testdb'); await queryDatabase(db, 'CREATE TABLE IF NOT EXISTS users (id INT, name VARCHAR(255))'); await queryDatabase(db, 'INSERT INTO users (id, name) VALUES (1, \'John Doe\')'); }); afterAll(async () => { await queryDatabase(db, 'DROP TABLE users'); db.close(); }); it('should query data correctly', async () => { const result = await queryDatabase(db, 'SELECT * FROM users WHERE id = 1'); expect(result).toEqual([{ id: 1, name: 'John Doe' }]); }); }); """ **Don't Do This:** * **Use Production Databases:** Never run integration tests against your production databases. * **Leave Dirty Data:** Always clean up your test databases after running tests. **Why This Matters:** Proper database testing ensures that your application can interact with databases correctly and reliably. ## 4. End-to-End (E2E) Testing Standards ### 4.1. Scope and Focus **E2E Test Definition:** End-to-end tests verify the entire application flow, from the user interface to the backend services. **Do This:** * **Test Critical User Flows:** Focus on testing the most important user scenarios. * **Simulate User Interactions:** Use tools like Cypress or Puppeteer to simulate user interactions with your application. * **Verify UI Elements:** Verify that UI elements are displayed correctly and behave as expected. **Don't Do This:** * **Test Every Detail:** E2E tests are time-consuming to write and maintain, so focus on critical flows. * **Duplicate Unit or Integration Tests:** Avoid duplicating tests that can be covered by unit or integration tests. **Why This Matters:** E2E tests ensure that your application works correctly from the user's perspective, providing confidence in the overall system. ### 4.2. Tools and Frameworks **Recommended Frameworks:** Cypress, Puppeteer, and Playwright are popular E2E testing frameworks. **Do This:** * **Use Cypress:** Cypress is recommeded. It provides a great developer experience and powerful features for E2E testing. * **Use Page Objects:** Implement the page object pattern to organize your E2E tests. * **Write Reusable Commands:** Create reusable Cypress commands for common interactions. **Code Example (Cypress):** """javascript // cypress/integration/example.spec.js describe('My First E2E Test', () => { it('Visits the app root url', () => { cy.visit('/'); cy.contains('h1', 'Welcome to My App'); }); it('Navigates to the about page', () => { cy.visit('/'); cy.contains('a', 'About').click(); cy.url().should('include', '/about'); cy.contains('h1', 'About Page'); }); }); """ **Don't Do This:** * **Write Brittle Tests:** Avoid writing tests that are easily broken by minor UI changes. * **Ignore Performance:** Monitor the performance of your E2E tests and optimize them as needed. **Why This Matters:** Choosing the right tools and following best practices makes your E2E tests more reliable and maintainable. ### 4.3. Test Environment **Configuring the Test Environment:** E2E tests require a dedicated test environment that simulates a real production environment. **Do This:** * **Use a Separate Environment:** Set up a separate environment for running E2E tests. * **Seed the Environment :** Seed the test environment with realistic data. * **Clean Up After Each Test:** Clean up the test environment after each test to ensure a clean state. **Don't Do This:** * **Run Tests in Production:** Never run E2E tests in your production environment. * **Use Shared Environments:** Avoid sharing test environments between different teams or projects. **Why This Matters:** A properly configured test environment ensures that your E2E tests accurately reflect the behavior of your application in a production-like setting. ### 4.4. Accessibility Testing **Integrating Accessibility Checks:** Ensure your application is accessible to users with disabilities. **Do This:** * **Integrate axe-core:** Incorporate axe-core (or similar) into your E2E tests to automatically check for accessibility issues. * **Run Accessibility Checks:** Include accessibility checks in your E2E tests to identify and fix accessibility issues. * **Follow WCAG Guidelines:** Ensure that your application follows the Web Content Accessibility Guidelines (WCAG). **Code Example (Cypress with "cypress-axe"):** """javascript // cypress/integration/accessibility.spec.js import 'cypress-axe'; describe('Accessibility Tests', () => { it('Checks accessibility of the home page', () => { cy.visit('/'); cy.injectAxe(); cy.checkA11y(); // Runs axe-core and fails the test if there are any violations }); }); """ **Don't Do This:** * **Ignore Accessibility:** Accessibility should be a core consideration, not an afterthought. * **Rely Solely on Automated Checks:** Automated checks are valuable but can't replace manual testing with assistive technologies. **Why This Matters:** Accessibility testing ensures your application is usable by everyone, improving inclusivity and meeting legal requirements. ## 5. Performance Testing Standards ### 5.1. Benchmarking **Purpose:** To identify performance bottlenecks and validate that changes don't degrade performance. **Do This:** * **Automated Benchmarks:** Create automated benchmarks to measure the performance of critical code sections. * **Record Baseline:** Establish a baseline performance metric for your applications entry points. * **Track performance over time:** Track key performance indicators (KPIs) over time using monitoring tools and integrate the key signals into the CI/CD **Example Implementation (using "perf_hooks"):** """javascript // benchmark.js const { performance, PerformanceObserver } = require('perf_hooks'); function myFunction(n) { let result = 0; for (let i = 1; i <= n; i++) { result += i; } return result; } const obs = new PerformanceObserver((items) => { console.log(items.getEntries()[0].duration); performance.clearMarks(); }); obs.observe({ entryTypes: ['measure'] }); performance.mark('start'); myFunction(100000); performance.mark('end'); performance.measure('myFunction', 'start', 'end'); """ **Don't Do This:** * **Optimize too early:** focus on core functionality before performance * **Ignore benchmarks over time**: It's important to periodically reevaluate benchmarks to avoid performance degradation. ### 5.2. Using Parcel's Performance Features: **Purpose:** Optimize bundle size and load times. **Do This:** * **Enable Production Mode:** Ensure "NODE_ENV=production" when building for production. Parcel performs optimizations like minification and tree shaking. * **Analyze Bundle Size Report:** Use Parcel's bundle analyzer features (via plugins) to identify large dependencies and opportunities for optimization (dynamic imports). * **Implement lazy loading** Use dynamic imports to load modules on demand **Code Example (Dynamic Import):** """javascript //index.js async function loadModule() { const module = await import('./my-module'); module.init(); } """ **Don't Do This:** * **Ship unminified code:** Always use Parcel in production mode. * **Over-bundle**: Prevent "bundle bloat" By following these guidelines, you can create a robust and reliable testing strategy for your Parcel projects, ensuring the quality and stability of your application.