# Code Style and Conventions Standards for Bootstrap
This document outlines the code style and conventions standards for Bootstrap development. Adhering to these standards ensures code consistency, readability, maintainability, and optimal performance, all of which are crucial for collaborative projects and long-term success. These guidelines are tailored for the latest versions of Bootstrap and modern web development practices.
## 1. General Formatting
### 1.1. Indentation
* **Do This:** Use 2 spaces for indentation. Avoid tabs.
* **Don't Do This:** Use tabs or inconsistent indentation.
**Why:** Consistent indentation enhances readability and minimizes merge conflicts. Two spaces provide a balanced level of indentation without excessive horizontal scrolling.
"""html
Content here
Content here
"""
### 1.2. Line Length
* **Do This:** Limit lines to a maximum of 120 characters.
* **Don't Do This:** Allow lines to exceed 120 characters.
**Why:** Shorter lines improve readability, especially on smaller screens. They also make it easier to compare changes in version control.
"""html
Click here to launch the demo modal
Click here to launch the demo modal with a very long text and some inline styles that should be avoided
"""
### 1.3. Whitespace
* **Do This:** Use whitespace strategically to enhance readability. Include a blank line between logical blocks of code.
* **Don't Do This:** Omit whitespace entirely or use it inconsistently.
**Why:** Whitespace visually separates distinct code sections, making the code easier to scan and understand.
"""html
Welcome
<p>Some content here.</p>
Welcome<p>Some content here.</p>
"""
### 1.4. File Encoding
* **Do This:** Use UTF-8 encoding for all files.
* **Don't Do This:** Use other encodings such as ASCII or ISO-8859-1.
**Why:** UTF-8 supports a wide range of characters, ensuring compatibility across different languages and systems.
## 2. Naming Conventions
### 2.1. Class Names
* **Do This:** Use descriptive and meaningful class names. Adhere to Bootstrap's naming conventions, extending only when necessary. Use hyphens ("-") to separate words within class names.
* **Don't Do This:** Use ambiguous or cryptic class names. Use camelCase or underscores in class names.
**Why:** Clear class names make it easier to understand the purpose and function of an HTML element. Following Bootstrap's conventions ensures consistency and avoids conflicts.
"""html
Submit
...
Submit
...
"""
### 2.2. ID Names
* **Do This:** Use descriptive and unique ID names. Use camelCase for ID names.
* **Don't Do This:** Use generic or duplicate ID names.
**Why:** Unique and descriptive IDs are essential for JavaScript interactions and DOM manipulation.
"""html
...
...
"""
### 2.3. Variable Names (CSS/JS)
* **CSS (SCSS) Do This:** Use lowercase with hyphens for CSS variables ("--my-variable-name").
* **CSS (SCSS) Don't Do This:** Use camelCase or underscores for CSS variables.
* **JS Do This:** Use camelCase for JavaScript variables ("myVariableName").
* **JS Don't Do This:** Use underscores or hyphens for JavaScript variables.
**Why:** Consistency in variable naming improves code clarity and maintainability. It makes it easier to distinguish between CSS and JavaScript variables.
"""scss
/* Correct: CSS variable names */
:root {
--primary-color: #007bff;
--font-size-base: 16px;
}
/* Incorrect: CSS variable names */
:root {
--primaryColor: #007bff;
--font_size_base: 16px;
}
"""
"""javascript
// Correct: JavaScript variable names
const myVariableName = "example";
// Incorrect: JavaScript variable names
const my_variable_name = "example";
"""
## 3. HTML Structure
### 3.1. Document Type Declaration
* **Do This:** Use the HTML5 doctype declaration: ""
* **Don't Do This:** Use older, less specific doctype declarations.
**Why:** The HTML5 doctype is the simplest and most compatible declaration for modern web development.
"""html
...
...
"""
### 3.2. Semantic HTML
* **Do This:** Use semantic HTML5 elements appropriately (e.g., "", "", "", "", "").
* **Don't Do This:** Rely solely on "" elements for all structural components.
**Why:** Semantic HTML improves accessibility, SEO, and code readability. It provides meaning and structure to your content.
"""html
...
Article Title
<p>Article content...</p>
<p>© 2023 My Company</p>
...
Article Title
<p>Article content...</p>
<p>© 2023 My Company</p>
"""
### 3.3. Accessibility (ARIA)
* **Do This:** Use ARIA attributes to enhance accessibility where semantic HTML is insufficient.
* **Don't Do This:** Overuse ARIA attributes or use them incorrectly.
**Why:** ARIA attributes provide additional information to assistive technologies, making your website more accessible to users with disabilities.
"""html
Close
Status message
Click me
"""
### 3.4. Consistent Structure
* **Do This:** Maintain a consistent directory structure for your project. e.g., "assets/css", "assets/js", "assets/img".
* **Don't Do This:** Scatter files randomly throughout the project.
**Why:** A well-organized directory structure makes it easier to locate and manage files, particularly in large projects.
## 4. CSS (SCSS) Style
### 4.1. SCSS Usage
* **Do This:** Leverage SCSS features like variables, mixins, and functions to write modular and reusable CSS.
* **Don't Do This:** Write plain CSS or overuse "@extend" (prefer mixins).
**Why:** SCSS enhances CSS with features that promote code reusability, maintainability, and organization. Mixins are generally preferred over "@extend" to avoid unexpected specificity issues.
"""scss
/* Correct: Using SCSS variables and mixins */
$primary-color: #007bff;
@mixin button-variant($background, $border, $color) {
background-color: $background;
border-color: $border;
color: $color;
}
.btn-primary {
@include button-variant($primary-color, $primary-color, #fff);
}
/* Incorrect: Writing plain CSS */
.btn-primary {
background-color: #007bff;
border-color: #007bff;
color: #fff;
}
"""
### 4.2. Selector Specificity
* **Do This:** Keep CSS selectors as simple and specific as possible. Avoid overly nested selectors.
* **Don't Do This:** Use "!important" excessively or create overly complex selectors.
**Why:** High specificity can make it difficult to override styles. Simple selectors improve performance and maintainability.
"""scss
/* Correct: Simple selector */
.card .card-title {
font-size: 1.2rem;
}
/* Incorrect: Overly specific selector */
body div.container div.card div.card-body h5.card-title {
font-size: 1.2rem;
}
"""
### 4.3. Bootstrap Overrides
* **Do This:** Override Bootstrap styles by creating custom classes or using SCSS variables.
* **Don't Do This:** Modify Bootstrap's core CSS files directly.
**Why:** Customizing Bootstrap through overrides ensures that your changes are maintainable and won't be lost during updates.
"""scss
/* Correct: Overriding Bootstrap styles */
$primary: #28a745; // Override Bootstrap's primary color
.btn-primary {
@include button-variant($primary, $primary, #fff);
}
/* Or with custom classes */
.custom-button {
@extend .btn;
@extend .btn-primary;
background-color: #28a745;
}
/* Use the custom class in your markup */
Green Button
"""
### 4.4. Media Queries
* **Do This:** Group media queries together, preferably at the end of the relevant component's CSS. Use Bootstrap's responsive breakpoints ("$grid-breakpoints") for consistency.
* **Don't Do This:** Scatter media queries throughout the CSS file.
**Why:** Organized media queries make it easier to manage responsive styles. Bootstrap's breakpoints provide a consistent and predictable responsive design.
"""scss
/* Correct: Grouped media queries using Bootstrap breakpoints */
.card {
margin-bottom: 1rem;
@include media-breakpoint-up(md) {
margin-bottom: 2rem;
}
}
/* Incorrect: Scattered media queries */
.card {
margin-bottom: 1rem;
}
@media (min-width: 768px) {
.card {
margin-bottom: 2rem;
}
}
"""
### 4.5. CSS Property Order
* **Do This:** Use a consistent order for CSS properties: positioning, box model, typography, visual.
* **Don't Do This:** Randomly order CSS properties.
**Why:** Consistent property order improves readability and makes it easier to find specific properties.
"""scss
/* Correct: Consistent CSS property order */
.card {
position: relative;
display: flex;
flex-direction: column;
min-width: 0;
word-wrap: break-word;
background-color: #fff;
background-clip: border-box;
border: 1px solid rgba(0, 0, 0, 0.125);
border-radius: 0.25rem;
}
/*Positioning*/
/*Box Model*/
/*Typography*/
/*Visual*/
"""
## 5. JavaScript Style
### 5.1. Vanilla JavaScript vs. jQuery (or other libraries)
* **Do This:** Prefer vanilla JavaScript for DOM manipulation and event handling where possible. Only use jQuery (or other libraries) if there's a compelling reason (e.g., complex animations, cross-browser compatibility for legacy browsers).
* **Don't Do This:** Rely on jQuery for simple tasks that can be easily accomplished with vanilla JavaScript.
**Why:** Vanilla JavaScript is faster and lighter than jQuery. Modern browsers provide excellent support for standard JavaScript APIs.
"""javascript
// Correct: Vanilla JavaScript
const button = document.querySelector('.my-button');
button.addEventListener('click', () => {
alert('Button clicked!');
});
// Incorrect : Overusing jQuery
$('.my-button').click(function() {
alert('Button clicked!');
});
"""
### 5.2. Modularity
* **Do This:** Break JavaScript code into reusable modules or functions.
* **Don't Do This:** Write monolithic blocks of code.
**Why:** Modular code is easier to maintain, test, and reuse.
"""javascript
// Correct: Modular JavaScript
function showAlert(message) {
alert(message);
}
function handleClick() {
showAlert('Button clicked!');
}
const button = document.querySelector('.my-button');
button.addEventListener('click', handleClick);
// Incorrect: Monolithic JavaScript
const button = document.querySelector('.my-button');
button.addEventListener('click', () => {
alert('Button clicked!');
});
"""
### 5.3. Comments
* **Do This:** Comment your code to explain complex logic, algorithms, or non-obvious behavior.
* **Don't Do This:** Over-comment or state the obvious.
**Why:** Comments help other developers (and your future self) understand the code. However, avoid redundant comments that simply repeat what the code already says.
"""javascript
// Correct: Explaining complex logic
/**
* Calculates the total price of items in the cart, including tax and shipping.
*
* @param {Array} cartItems - An array of cart item objects.
* @returns {number} The total price.
*/
function calculateTotalPrice(cartItems) {
// Calculate subtotal
let subtotal = cartItems.reduce((sum, item) => sum + item.price * item.quantity, 0);
// Add tax (8%)
const taxRate = 0.08;
const tax = subtotal * taxRate;
// Add shipping (flat rate)
const shippingCost = 10;
return subtotal + tax + shippingCost;
}
// Incorrect: Stating the obvious
let x = 5; // Assign 5 to x
"""
### 5.4. Error Handling
* **Do This:** Implement proper error handling using "try...catch" blocks, especially when dealing with asynchronous operations.
* **Don't Do This:** Ignore potential errors or fail silently.
**Why:** Robust error handling prevents unexpected crashes and provides informative error messages to the user.
"""javascript
// Correct: Error handling
try {
const data = JSON.parse(response);
// Process the data
} catch (error) {
console.error('Error parsing JSON:', error);
alert('An error occurred while processing the data.');
}
// Incorrect: Ignoring errors
const data = JSON.parse(response); // What if response is not valid JSON?
// Process the data (potential crash)
"""
### 5.5. Asynchronous Operations
* **Do This:** Use "async/await" syntax for asynchronous operations (e.g., AJAX calls, promises).
* **Don't Do This:** Rely solely on callbacks (especially for complex asynchronous workflows).
**Why:** "async/await" makes asynchronous code easier to read and reason about. It avoids "callback hell" and improves code maintainability.
"""javascript
// Correct: Using async/await
async function fetchData() {
try {
const response = await fetch('/api/data');
const data = await response.json();
return data;
} catch (error) {
console.error('Error fetching data:', error);
return null;
}
}
// Incorrect: Using callbacks
function fetchData(callback) {
fetch('/api/data')
.then(response => response.json())
.then(data => callback(data))
.catch(error => console.error('Error fetching data:', error));
}
"""
## 6. Bootstrap-Specific Conventions
### 6.1. Grid System
* **Do This:** Use Bootstrap's grid system ("container", "row", "col-*") to create responsive layouts.
* **Don't Do This:** Use custom CSS grids or tables for layout purposes.
**Why:** Bootstrap's grid system provides a flexible and consistent way to create responsive layouts that adapt to different screen sizes.
"""html
Content 1
Content 2
Content 1
Content 2
"""
### 6.2. Components
* **Do This:** Utilize Bootstrap's pre-built components (e.g., buttons, forms, cards, navigation) whenever possible. Customize them as needed.
* **Don't Do This:** Re-implement common UI patterns from scratch.
**Why:** Bootstrap's components provide a consistent look and feel, reduce development time, and ensure accessibility.
"""html
Click me
Click me
"""
### 6.3. Responsive Utilities
* **Do This:** Use Bootstrap's responsive utility classes (e.g., "d-none d-md-block", "text-center text-md-left") to control the visibility and behavior of elements on different screen sizes.
* **Don't Do This:** Write custom media queries for simple show/hide or text alignment adjustments.
**Why:** Bootstrap's responsive utilities provide a convenient way to create responsive designs without writing custom CSS.
"""html
<p>This text is visible on medium and larger screens.</p>
<p>This text is visible on medium and larger screens.</p>
"""
### 6.4. Version Compatibility
* **Do This:** Consult the official Bootstrap documentation for the specific version you are using. Be aware of breaking changes when upgrading Bootstrap versions.
* **Don't Do This:** Mix code intended for different Bootstrap versions.
**Why:** Bootstrap evolves, and using outdated approaches can lead to compatibility issues and security vulnerabilities.
### 6.5. Customization
* **Do This:** Customize Bootstrap using SCSS variables or custom CSS classes.
* **Don't Do This:** Modify Bootstrap's core CSS files directly.
**Why:** Customizations via SCSS variables and CSS classes preserve the ability to upgrade Bootstrap in the future without losing your changes.
### 6.6 JavaScript Initialization
* **Do This:** Initialize Bootstrap JavaScript components using data attributes or JavaScript. Use data attributes for simple configurations and Javascript for more complex scenarios.
* **Don't Do This:** Rely solely on one method and neglect the benefits of the other.
**Why:** Choosing the right method for JavaScript initialization improves code readability and maintainability.
"""html
Launch demo modal
"""
"""javascript
//Correct: Using Javascript for complex initialization
const myModal = new bootstrap.Modal(document.getElementById('exampleModal'), {
keyboard: false
})
"""
## 7. Performance Optimization
### 7.1. Minimize CSS and JavaScript
* **Do This:** Minify CSS and JavaScript files for production.
* **Don't Do This:** Deploy unminified files to production.
**Why:** Minification reduces file sizes, improving page load times.
### 7.2. Image Optimization
* **Do This:** Optimize images for the web (e.g., compress, resize, use appropriate formats). Use responsive images ("" or "srcset" attribute).
* **Don't Do This:** Use large, unoptimized images.
**Why:** Optimized images reduce file sizes, improving page load times and bandwidth usage.
### 7.3. Lazy Loading
* **Do This:** Implement lazy loading for images below the fold.
* **Don't Do This:** Load all images upfront, regardless of visibility.
**Why:** Lazy loading improves initial page load time by deferring the loading of non-critical images.
### 7.4. Browser Caching
* **Do This:** Leverage browser caching by setting appropriate cache headers.
* **Don't Do This:** Disable browser caching or use overly short cache durations.
**Why:** Browser caching reduces the number of requests to the server, improving page load times for repeat visitors.
## 8. Security Best Practices
### 8.1. XSS Protection
* **Do This:** Sanitize user inputs to prevent cross-site scripting (XSS) attacks.
* **Don't Do This:** Trust user inputs without validation or sanitization.
**Why:** XSS attacks can compromise the security of your website and its users.
### 8.2. CSRF Protection
* **Do This:** Implement cross-site request forgery (CSRF) protection for forms and AJAX requests.
* **Don't Do This:** Submit forms or AJAX requests without CSRF tokens.
**Why:** CSRF attacks can allow malicious users to perform unauthorized actions on behalf of legitimate users.
### 8.3. Dependencies
* **Do This:** Keep Bootstrap and all dependencies up to date to patch security vulnerabilities. Use tools like "npm audit" or "yarn audit".
* **Don't Do This:** Use outdated versions of Bootstrap or its dependencies.
**Why:** Outdated dependencies may contain known security vulnerabilities that can be exploited by attackers.
### 8.4. Subresource Integrity (SRI)
* **Do This:** Use Subresource Integrity (SRI) hashes for external CSS and JavaScript files.
* **Don't Do This:** Load external resources without SRI hashes.
**Why:** SRI hashes ensure that external files are not tampered with, protecting against malicious code injection.
"""html
or
"""
By adhering to these code style and convention standards, development teams can ensure code quality, maintainability, and security when working with Bootstrap. This document provides a practical and comprehensive guide for Bootstrap developers aiming for professional excellence.
danielsogl
Created Mar 6, 2025
This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.
The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.
Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.
# Project Overview project: name: 'Your Project Name' description: 'Brief project description' stack: - technology: 'Framework/Language' version: 'X.Y.Z' - technology: 'Database' version: 'X.Y.Z'
# Code Standards standards: style: - 'Use consistent indentation (2 spaces)' - 'Follow language-specific naming conventions' documentation: - 'Include JSDoc comments for all functions' - 'Maintain up-to-date README files' testing: - 'Write unit tests for all new features' - 'Maintain minimum 80% code coverage'
# Security Guidelines security: authentication: - 'Implement proper token validation' - 'Use environment variables for secrets' dataProtection: - 'Sanitize all user inputs' - 'Implement proper error handling'
Be Specific
Maintain Organization
Regular Updates
# Common Patterns Example patterns: components: - pattern: 'Use functional components by default' - pattern: 'Implement error boundaries for component trees' stateManagement: - pattern: 'Use React Query for server state' - pattern: 'Implement proper loading states'
Commit the Rules
.clinerules in version controlTeam Collaboration
Rules Not Being Applied
Conflicting Rules
Performance Considerations
# Basic .clinerules Example project: name: 'Web Application' type: 'Next.js Frontend' standards: - 'Use TypeScript for all new code' - 'Follow React best practices' - 'Implement proper error handling' testing: unit: - 'Jest for unit tests' - 'React Testing Library for components' e2e: - 'Cypress for end-to-end testing' documentation: required: - 'README.md in each major directory' - 'JSDoc comments for public APIs' - 'Changelog updates for all changes'
# Advanced .clinerules Example project: name: 'Enterprise Application' compliance: - 'GDPR requirements' - 'WCAG 2.1 AA accessibility' architecture: patterns: - 'Clean Architecture principles' - 'Domain-Driven Design concepts' security: requirements: - 'OAuth 2.0 authentication' - 'Rate limiting on all APIs' - 'Input validation with Zod'
# Component Design Standards for Bootstrap This document outlines coding standards for designing and implementing reusable, maintainable components in Bootstrap projects, leveraging the latest version of the framework. These standards aim to promote consistency, improve code quality, and facilitate collaboration within development teams. ## 1. Principles of Component Design in Bootstrap ### 1.1. Reusability and Modularity **Standard:** Components should be designed to be reusable across different parts of the application. They should encapsulate specific functionality and UI elements. * **Do This:** Design components with generic props/attributes that can be customized to fit various contexts. Separate layout/structure from content-specific data. * **Don't Do This:** Create monolithic components that are tightly coupled to specific pages or sections of the application. Avoid hardcoding data or logic directly within the component. **Why:** Reusable components reduce code duplication, simplify maintenance, and promote consistency across the user interface. **Example:** """html <!-- Reusable Alert Component --> <div class="alert alert-{{type}} alert-dismissible fade show" role="alert"> {{message}} <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button> </div> <!-- Usage in HTML (with templating or JavaScript) --> <div id="alert-container"></div> <script> const alertContainer = document.getElementById('alert-container'); alertContainer.innerHTML = " <div class="alert alert-success alert-dismissible fade show" role="alert"> Your changes have been saved successfully! <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button> </div> "; </script> """ ### 1.2. Single Responsibility Principle (SRP) **Standard:** Each component should have a single, well-defined purpose. * **Do This:** Decompose complex UI elements into smaller, focused components. Each component concentrates its efforts on a specific task. * **Don't Do This:** Combine unrelated functionalities into a single component, making it difficult to understand, test, and maintain. **Why:** Adhering to SRP makes components easier to understand, test, and modify. It also improves reusability, as focused components are more likely to be applicable in different contexts. **Example:** Separate product image display from product details using two components. "ProductImage" handles the image, while "ProductDetails" handles the name, price, and description. """html <!-- Product Image Component --> <img src="{{imageUrl}}" class="img-fluid" alt="{{altText}}"> <!-- Product Details Component --> <h2>{{productName}}</h2> <p class="text-muted">{{productDescription}}</p> <p>Price: ${{productPrice}}</p> """ ### 1.3. Avoid Overriding Bootstrap Styles Directly **Standard:** Minimize direct CSS overrides of Bootstrap classes. Utilize Bootstrap's utility classes and theming capabilities whenever possible. * **Do This:** Use Bootstrap’s utility classes (e.g., "m-2", "text-center", "d-flex") to customize the appearance and layout of components. Leverage Bootstrap's Sass variables for consistent theming. * **Don't Do This:** Write extensive custom CSS to override Bootstrap's default styles, especially for basic styling needs. This leads to CSS bloat and conflicts. **Why:** Overriding Bootstrap styles directly increases the risk of conflicts during updates and makes it harder to maintain a consistent look and feel. Bootstrap utility classes are highly optimized and tested. **Example:** """html <!-- Good Example (Using Bootstrap Utility Classes) --> <button class="btn btn-primary m-2">Save Changes</button> <div class="d-flex justify-content-between align-items-center"> <!-- ... --> </div> <!-- Bad Example (Overriding Bootstrap Styles with Custom CSS) --> <button style="background-color: #007bff; color: white; margin: 8px; border: none; padding: 10px 20px; border-radius: 5px;">Save Changes</button> """ ### 1.4. Semantic HTML **Standard:** Use semantic HTML elements to structure components. This improves accessibility and SEO. * **Do This:** Use "<article>", "<aside>", "<nav>", "<header>", "<footer>", and other semantic elements where appropriate to convey the meaning and structure of the component. * **Don't Do This:** Rely solely on "<div>" and "<span>" elements without considering their semantic value. **Why:** Semantic HTML provides context for assistive technologies and search engines, improving usability and discoverability. **Example:** """html <article class="card"> <header class="card-header"> Article Title </header> <div class="card-body"> Article Content </div> <footer class="card-footer"> Published Date </footer> </article> """ ## 2. Component Structure and Organization ### 2.1. Directory Structure **Standard:** Organize component files in a dedicated directory structure that promotes modularity. * **Do This:** Create a "components" directory in your project's "src" directory (or similar structured setup, depending on project). Within "components", create subdirectories for each component, containing its HTML, CSS/Sass, and JavaScript files. "src/components/MyComponent/MyComponent.html", "src/components/MyComponent/MyComponent.scss", "src/components/MyComponent/MyComponent.js" * **Don't Do This:** Scatter component files throughout the project or mix them with page-specific files. **Why:** A well-defined directory structure makes it easier to find, understand, and maintain components. ### 2.2. Naming Conventions **Standard:** Use consistent and descriptive naming conventions for component files and classes. * **Do This:** Use PascalCase for component names ("MyComponent"), hyphen-separated lowercase for file names ("my-component.html", "my-component.scss"). Prefix custom CSS classes with a project-specific namespace (e.g., "my-project-"). * **Don't Do This:** Use cryptic or inconsistent naming. Avoid generic names that could conflict with Bootstrap classes. Mix naming conventions across different components. **Why:** Consistent naming conventions improve readability and reduce ambiguity. Namespaces prevent CSS conflicts and make overriding Bootstrap styles easier to manage. **Example:** """ src/components/ProductCard/ProductCard.html src/components/ProductCard/ProductCard.scss .my-project-product-card { ... } """ ### 2.3. Component Styling **Standard:** Follow a consistent approach to component styling, such as BEM (Block Element Modifier) or a similar methodology. * **Do This:** Use BEM or another structured CSS methodology to define component styles. This helps to improve the organization of your CSS rules and avoid naming collisions. * **Don't Do This:** Write unstructured CSS that is difficult to understand and maintain. Rely heavily on the global stylesheet for component-specific styles. **Why:** A structured CSS methodology ensures that styles are properly scoped and organized, making it easier to maintain and modify the component's appearance. **Example (BEM):** """scss .product-card { /* Block */ &__image { /* Element */ width: 100%; } &__title { /* Element */ font-size: 1.2rem; } &--featured { /* Modifier */ border: 2px solid blue; } } """ ## 3. Component Implementation Details. ### 3.1. Use of Bootstrap's JavaScript Plugins **Standard:** Utilize Bootstrap's JavaScript plugins (e.g., modals, tooltips, dropdowns) to enhance component functionality. Extend or customize these plugins when necessary. * **Do This:** Initialize Bootstrap plugins using data attributes or JavaScript. Follow Bootstrap's documentation for proper usage and configuration. * **Don't Do This:** Reimplement core functionality that is already provided by Bootstrap's plugins. Do not directly modify Bootstrap's JavaScript files. **Why:** Bootstrap's plugins provide a set of pre-built and tested functionalities. Extending the Plugin (using the documented method) reduces the need to write custom Javascript. **Example:** """html <!-- Modal Component --> <div class="modal fade" id="exampleModal" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true"> <div class="modal-dialog"> <div class="modal-content"> <div class="modal-header"> <h5 class="modal-title" id="exampleModalLabel">Modal title</h5> <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> </div> <div class="modal-body"> ... </div> <div class="modal-footer"> <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> <button type="button" class="btn btn-primary">Save changes</button> </div> </div> </div> </div> <!-- JavaScript Initialization (if needed - often done via data attributes) --> <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal"> Launch demo modal </button> """ ### 3.2. Accessibility Considerations (WCAG compliance) **Standard:** Ensure that components are accessible to users with disabilities. Follow Web Content Accessibility Guidelines (WCAG). * **Do This:** Provide proper ARIA attributes for interactive elements. Use semantic HTML. Provide alternative text for images. Ensure sufficient color contrast. Ensure keyboard navigation works as expected. * **Don't Do This:** Ignore accessibility requirements. Assume that all users can interact with the component using a mouse. **Why:** Accessibility is a fundamental requirement for inclusive design. It ensures that everyone can use the interface, regardless of their abilities. **Example:** """html <button class="btn btn-primary" aria-label="Close dialog">Close</button> <img src="image.jpg" alt="Descriptive alt text"> """ ### 3.3. Responsive Design **Standard:** Design components to be responsive across different screen sizes and devices. * **Do This:** Use Bootstrap's grid system, responsive utility classes, and media queries to create adaptable layouts and styles. Test components on a variety of devices and screen sizes. * **Don't Do This:** Rely on fixed-width layouts or ignore responsiveness, making the component unusable on smaller screens. **Why:** Responsive design ensures that the component looks and functions correctly on all devices, providing a consistent user experience across a wide range of platforms. **Example:** """html <div class="container"> <div class="row"> <div class="col-sm-6 col-md-4"> <!-- Content Here --> </div> </div> </div> """ ### 3.4. Error Handling and Validation **Standard:** Implement robust error handling and validation mechanisms within components that handle user input or data processing. * **Do This:** Validate user input to prevent errors and security vulnerabilities (e.g., XSS, SQL injection). Provide clear and informative error messages to the user. Use Bootstrap's validation states (e.g., ".is-valid", ".is-invalid") to visually indicate errors. * **Don't Do This:** Ignore error handling or validation, leaving the component vulnerable to errors or security risks. Display cryptic or unhelpful error messages. **Why:** Proper error handling and validation improve the user experience and prevent data corruption or security breaches. **Example:** """html <form> <div class="mb-3"> <label for="exampleInputEmail1" class="form-label">Email address</label> <input type="email" class="form-control is-invalid" id="exampleInputEmail1" aria-describedby="emailHelp"> <div id="emailHelp" class="form-text">Please enter a valid email address.</div> </div> <button type="submit" class="btn btn-primary">Submit</button> </form> """ ### 3.5. Performance Optimization **Standard:** Optimize components for performance to minimize load times and improve responsiveness. * **Do This:** Use efficient CSS selectors and JavaScript code. Lazy load images. Minimize DOM manipulations. Consider code splitting for larger components. Prefer Bootstrap utility classes, as they are highly efficient and do not result in excessive CSS. * **Don't Do This:** Use inefficient CSS selectors that trigger unnecessary reflows. Load large images or unnecessary resources. Perform complex DOM manipulations repeatedly. **Why:** Performance optimization is crucial for providing a smooth and enjoyable user experience. Slow-loading or unresponsive components can frustrate users and negatively impact the application. ### 3.6. Testing **Standard:** Write unit and integration tests for components to ensure they function correctly and prevent regressions. * **Do This:** Use a testing framework like Jest or Mocha to write comprehensive tests. Test all key aspects of the component, including rendering, functionality, and error handling. Use tools such as Cypress to enable end-to-end testing of component behavior and interactions within larger systems. * **Don't Do This:** Skip testing or write incomplete tests that do not adequately cover the component's functionality. **Why:** Testing helps to ensure that components are reliable and maintainable. Tests can catch bugs early in the development process and prevent regressions when changes are made to the code. ### 3.7 Use of Bootstrap Icons: **Standard:** Use Bootstrap icons instead of custom-created icons where suitable. * **Do This:** Utilize the official Bootstrap Icons library via CDN or local installation. Choose semantic icons that align with the component's function. """html <i class="bi bi-check-circle-fill"></i> <!-- Example Icon --> """ * **Don't Do This:** Create custom icon sets when Bootstrap icons provide suitable alternatives. Overuse icons or use them inconsistently. **Why:** Bootstrap Icons are designed specifically to integrate seamlessly with Bootstrap’s styling to provide a cohesive look and feel. ## 4. Component Composition ### 4.1. Creating Complex Views **Standard:** Compose complex views from smaller, reusable components. * **Do This:** Break down complex UIs into hierarchies of components. A page layout can be composed of header, footer, and main content components, which themselves are composed of smaller elements. Consider using a "layout" component that controls the overall structure, with slots or props for injecting content. * **Don't Do This:** Create monolithic components that handle the entire view's logic and rendering. **Why:** Component composition promotes modularity, reusability, and maintainability. It aligns with the single responsibility principle, making each component easier to understand and modify. **Example:** An e-commerce product listing page. """ ProductListingPage (Parent) |- ProductFilterComponent |- ProductGridComponent |- ProductCardComponent (Repeated for each product) """ ### 4.2. Prop/Attribute Passing **Standard:** Pass data and functionality to components through props/attributes. * **Do This:** Define clear prop interfaces for components. Use prop validation to ensure that components receive the expected data types. Pass data down from parent components to child components. Use callback functions (passed as props) to trigger actions in parent components from child components. * **Don't Do This:** Directly access global state or modify props within a component. Deeply nest props, making data flow difficult to trace. **Why:** Prop passing promotes data encapsulation and makes components more predictable and reusable. It establishes a clear data flow, making it easier to understand how data is processed and rendered. ### 4.3. Events and Communication **Standard:** Use events to communicate between components. * **Do This:** Leverage *Custom Events* (DOM events) in JavaScript to trigger actions in parent components from child components, especially when using vanilla JavaScript with Bootstrap. Build custom event listeners to act on these events. * **Don't Do This:** Directly manipulate the DOM of other components or rely on global variables for communication. **Why:** Proper event handling will allow components to be properly decoupled. ## 5. Documentation ### 5.1. Component Documentation **Standard:** Provide clear and comprehensive documentation for each component, including its purpose, usage, props, and events. * **Do This:** Use code comments, README files, or documentation generators (e.g., JSDoc, Storybook) to document components. Include examples of how to use the component in different contexts. * **Don't Do This:** Skip documentation or provide insufficient information, making it difficult for others to understand and use the component. **Why:** Clear documentation is essential for component discoverability, reusability, and maintainability. It helps developers understand the component's purpose, how to use it correctly, and how to extend or modify it. ### 5.2. Code Comments **Standard:** Add clear and concise comments to the code to explain complex logic, decisions, and assumptions. * **Do This:** Use comments to explain the purpose of functions, algorithms, and non-obvious code sections. Update comments whenever the code is modified. * **Don't Do This:** Over-comment the code with obvious or redundant information. Leave outdated or incorrect comments. **Why:** Code comments improve readability and help developers understand the code's intent, making it easier to maintain and modify. This document provides a comprehensive guide to component design standards for Bootstrap projects. By following these standards, developers can create reusable, maintainable, and high-quality components that contribute to a successful application. These guidelines will also assist AI coding assistants in generating code that adheres to best practices.
# Tooling and Ecosystem Standards for Bootstrap This document outlines coding standards specifically focused on tooling and ecosystem best practices for Bootstrap development. Adhering to these guidelines will improve project maintainability, performance, and consistency. They are geared toward the latest version of Bootstrap and modern development workflows. ## 1. Dependency Management ### 1.1. Leveraging Package Managers **Standard:** Use npm or yarn for managing Bootstrap and its dependencies. **Do This:** """bash npm install bootstrap # or yarn add bootstrap """ **Don't Do This:** Manually downloading Bootstrap files and including them directly in your project. **Why:** Package managers simplify dependency updates, version control, and ensure consistency across development environments. **Example:** Updating Bootstrap version: """bash npm update bootstrap # or yarn upgrade bootstrap """ ### 1.2. Managing Third-Party Libraries **Standard:** Use npm or yarn for managing third-party libraries used with Bootstrap. **Do This:** When using a library like Popper.js (required for some Bootstrap components), install it via npm/yarn. """bash npm install @popperjs/core # or yarn add @popperjs/core """ **Don't Do This:** Linking to CDNs for third-party libraries without a defined version. This can lead to unpredictable behavior if the CDN's version changes. **Why:** Prevents version conflicts, ensures consistent dependency resolution, and simplifies project setup for new developers. **Anti-Pattern:** Relying on global CDN links without version pinning. """html <!-- Not recommended --> <script src="https://cdn.example.com/popper.js/latest/popper.min.js"></script> """ Instead, use a package manager and import the library in your JavaScript: """javascript // Example using ES modules with Webpack or similar bundler import * as Popper from '@popperjs/core'; """ ### 1.3. Package Versioning **Standard:** Utilize semantic versioning (semver) for managing package versions. **Do This:** Specify version ranges in your "package.json" using semantic versioning. """json { "dependencies": { "bootstrap": "^5.3.0", // Allows updates within the 5.x range "@popperjs/core": "~2.11.6" // Allows updates within the 2.11.x range (but not 2.12+) } } """ **Don't Do This:** Using "*" or "latest" for package versions. **Why:** Semantic versioning provides clarity on the impact of updates and helps avoid breaking changes. "^" allows minor and patch releases, "~" allows patch releases. Consider using exact versions if you must guarantee complete stability. **Code Example:** Demonstrating semantic versioning in "package.json". """json { "name": "my-bootstrap-project", "version": "1.0.0", "dependencies": { "bootstrap": "^5.3.3" }, "devDependencies": { "sass": "^1.62.1" } } """ ### 1.4. Lock Files **Standard:** Always include "package-lock.json" (for npm) or "yarn.lock" (for yarn) in your repository. **Do This:** Ensure these files are committed and pushed to your version control system. **Don't Do This:** Ignoring lock files or deleting them. **Why:** Lock files guarantee that every developer and deployment environment uses the exact same versions of dependencies, preventing unexpected issues. ## 2. Build Tools and Task Runners ### 2.1. Utilizing Module Bundlers **Standard:** Employ a module bundler like Webpack, Parcel, or Rollup.js for managing JavaScript and CSS assets. **Do This:** Configure your bundler to process Bootstrap's Sass files and JavaScript modules. **Don't Do This:** Including individual Bootstrap JavaScript files directly in your HTML without bundling. **Why:** Module bundlers optimize assets, support modular code organization, and enable advanced features such as code splitting and tree shaking. **Code Example:** Webpack configuration for Bootstrap (partial). """javascript // webpack.config.js const path = require('path'); module.exports = { entry: './src/js/app.js', output: { filename: 'bundle.js', path: path.resolve(__dirname, 'dist'), }, module: { rules: [ { test: /\.scss$/, use: [ 'style-loader', // Inject styles into DOM 'css-loader', // Translates CSS into CommonJS 'sass-loader' // Compiles Sass to CSS ] }, { test: /\.js$/, exclude: /node_modules/, use: { loader: 'babel-loader', options: { presets: ['@babel/preset-env'] } } } ] }, devServer: { static: { directory: path.join(__dirname, 'dist'), }, compress: true, port: 9000, }, }; """ In "src/js/app.js": """javascript import 'bootstrap/scss/bootstrap.scss'; //Import Bootstrap's SCSS import * as bootstrap from 'bootstrap'; // Import Bootstrap's JS """ ### 2.2. Sass Compilation **Standard:** Compile Bootstrap's Sass files using a dedicated Sass compiler. **Do This:** Use "node-sass", "dart-sass" or "sass" (the pure JavaScript implementation) via npm and integrate it into your build process. Dart Sass is generally recommended. """bash npm install sass --save-dev # or yarn add sass --dev """ **Don't Do This:** Using outdated or unreliable Sass compilers. **Why:** A proper Sass compiler allows you to customize Bootstrap's variables and mixins, control the generated CSS, and leverage features like modular CSS. **Code Example:** Compiling SASS from command line """bash sass src/scss/custom.scss dist/css/custom.css """ Create "src/scss/custom.scss": Notice that you can override Bootstrap variables! """scss // Override default variables $primary: #007bff; $body-bg: #f8f9fa; // Import Bootstrap @import "bootstrap/scss/bootstrap"; // Your additional styles .custom-element { color: $primary; background-color: $body-bg; } """ ### 2.3. Task Runners **Standard:** Consider Task Runners like Gulp or npm scripts for automating repetitive tasks **Do this:** Define tasks for compiling Sass, watching for changes, and running linters. npm scripts (defined in package.json) are often sufficient. """json { "scripts": { "sass": "sass src/scss/custom.scss dist/css/custom.css", "watch:sass": "sass --watch src/scss/custom.scss dist/css/custom.css", "build": "npm run sass", "start": "npm run watch:sass" } } """ **Don't Do This:** Manually compiling Sass every time you make a change. **Why:** Facilitates efficient development workflows by automating common tasks. ### 2.4. PostCSS **Standard:** Use PostCSS for CSS post-processing, such as adding vendor prefixes, minifying CSS, and running stylelint. **Do this:** Integrate PostCSS with Autoprefixer into your build process. """bash npm install postcss postcss-cli autoprefixer cssnano --save-dev """ Example "postcss.config.js": """javascript module.exports = { plugins: [ require('autoprefixer'), require('cssnano')({ preset: 'default', }), ], }; """ Update your npm scripts: """json { "scripts": { "sass": "sass src/scss/custom.scss dist/css/custom.css", "postcss": "postcss dist/css/custom.css -o dist/css/custom.min.css", "watch:sass": "sass --watch src/scss/custom.scss dist/css/custom.css", "build": "npm run sass && npm run postcss", "start": "npm run watch:sass" } } """ **Don't Do This:** Manually adding vendor prefixes. **Why:** Automates tasks enhances CSS compatibility and optimizes code for production. ## 3. Code Quality and Linting ### 3.1. JavaScript Linting **Standard:** Enforce consistent JavaScript code style using linters such as ESLint. **Do This:** Configure ESLint with a consistent set of rules, including those relevant to Bootstrap usage (e.g., avoiding direct DOM manipulation when Bootstrap components provide alternatives). """bash npm install eslint eslint-config-airbnb-base eslint-plugin-import --save-dev # or yarn add eslint eslint-config-airbnb-base eslint-plugin-import --dev """ Example ".eslintrc.js" """javascript module.exports = { "extends": "airbnb-base", "rules": { "no-console": "off", // Add more specific rules based on your project's needs }, "env": { "browser": true, "node": true } }; """ **Don't Do This:** Ignoring linting errors or warnings. **Why:** Improves code readability, reduces errors, and ensures consistency across the codebase. ### 3.2. Sass Linting **Standard:** Use Stylelint to enforce coding standards in your SCSS files **Do This:** Configure Stylelint, e.g. with the "stylelint-config-standard-scss" configuration: """bash npm install stylelint stylelint-config-standard-scss --save-dev # or yarn add stylelint stylelint-config-standard-scss --dev """ Example ".stylelintrc.js": """javascript module.exports = { extends: 'stylelint-config-standard-scss', rules: { // Add or override rules here }, }; """ **Don't Do This:** Ignoring stylelint errors or warnings **Why:** Ensures consistent code style and prevents common CSS errors. ### 3.3. Editor Integration **Standard:** Integrate linters and formatters (e.g. Prettier) into your editor or IDE for real-time feedback and automatic formatting. **Do This:** Install plugins for your code editor. VS Code, Sublime Text, and Atom all have ESLint, Stylelint, and Prettier plugins. **Don't Do This:** Relying solely on command-line linting without editor integration. **Why:** Provides immediate feedback on code quality and consistency, improving the development experience. ## 4. Testing ### 4.1. Unit Testing **Standard:** Write unit tests for custom JavaScript components and modifications to Bootstrap's behavior. **Do This:** Use a testing framework like Jest or Mocha with Chai or Jasmine for assertions. Consider testing frameworks like Cypress for end-to-end testing. **Don't Do This:** Skipping unit tests for complex JavaScript functionality **Why:** Ensures that individual components function correctly and reduces the risk of regressions. ### 4.2. Cross-Browser Testing **Standard:** Test your Bootstrap-based application in multiple browsers (Chrome, Firefox, Safari, Edge) and devices to ensure compatibility. **Do This:** Use browser testing tools or services like BrowserStack or Sauce Labs. **Don't Do This:** Assuming that your application will work flawlessly in all browsers without testing **Why:** Ensures a consistent user experience across different platforms. ### 4.3. Accessibility Testing **Standard:** Conduct automated accessibility testing using tools like Axe or WAVE to identify and fix accessibility issues. **Do This:** Integrate accessibility testing into your build process or CI/CD pipeline. Follow ARIA guidelines when using Bootstrap. **Don't Do This:** Neglecting accessibility testing. **Why:** Ensures that your application is usable by individuals with disabilities. ## 5. Documentation and Style Guides ### 5.1. Code Comments **Standard:** Provide clear and concise comments to explain complex logic, non-obvious behavior, and the purpose of code sections. **Do This:** Comment your code according to established conventions (e.g., JSDoc for JavaScript). **Don't Do This:** Over-commenting obvious code or writing redundant comments. **Why:** Makes the code easier to understand and maintain, especially for other developers. ### 5.2. Style Guide Documentation **Standard:** Create a living style guide that documents your project's specific Bootstrap customizations, design patterns, and component implementations. **Do This:** Use a tool like Storybook or a custom documentation generator to create and maintain your style guide. **Don't Do This:** Neglecting to document your Bootstrap customizations. **Why:** Promotes consistency, reduces duplication, and improves collaboration among developers and designers. ### 5.3. Component Documentation **Standard:** For custom components extending Bootstrap functionality, provide clear documentation on usage, props/options, and expected behavior. **Do This:** Use a documentation generator (e.g., JSDoc, TypeDoc) to create component documentation automatically from code comments. **Don't Do This:** Relying solely on implicit knowledge or code inspection to understand component usage. **Why:** Makes components easier to use and integrate into other parts of the application. ## 6. Performance Optimization ### 6.1. Tree Shaking **Standard:** Configure your module bundler to perform tree shaking to remove unused Bootstrap components and CSS rules. **Do This:** Ensure that your bundler's configuration is set up to eliminate dead code. This usually involves using ES modules and setting the "sideEffects" property in "package.json" appropriately. **Don't Do This:** Including the entire Bootstrap library when only a subset of components is needed. **Why:** Reduces the size of your application's bundle, improving load times and overall performance. ### 6.2. Code Splitting **Standard:** Use code splitting techniques to divide your application into smaller chunks that can be loaded on demand. **Do This:** Leverage your module bundler's support for code splitting (e.g., Webpack's "import()" syntax or dynamic imports). **Don't Do This:** Loading all of your application's JavaScript code upfront. **Why:** Improves initial load times by only loading the code that is needed for the current page or component. ### 6.3. Asset Optimization **Standard:** Optimize images and other assets to reduce file sizes without sacrificing quality. **Do This:** Use tools like ImageOptim or TinyPNG to compress images. Enable Gzip or Brotli compression on your web server. **Don't Do This:** Serving unoptimized images or assets. **Why:** Reduces load times and improves overall performance. ### 6.4. CSS Optimization **Standard:** Minify and compress your CSS files. Remove unused CSS rules and optimize for browser rendering. **Do This:** Use PostCSS with plugins like cssnano to minify CSS. Analyze CSS coverage to identify and remove unused styles. **Don't Do This:** Serving unminified CSS. **Why:** Reduces download times and improves browser rendering performance. ## 7. Security ### 7.1. Dependency Vulnerability Scanning **Standard:** Regularly scan your project's dependencies for known security vulnerabilities using tools like "npm audit" or "yarn audit". **Do This:** Run vulnerability scans as part of your CI/CD pipeline. Update vulnerable dependencies promptly. **Don't Do This:** Ignoring security vulnerabilities in your dependencies. **Why:** Reduces the risk of security breaches and protects your application from known exploits. ### 7.2. Cross-Site Scripting (XSS) Prevention **Standard:** Sanitize user inputs to prevent XSS attacks. Use Bootstrap's built-in HTML escaping features where applicable. **Do This:** Use a templating engine or library that automatically escapes HTML. **Don't Do This:** Rendering unsanitized user input directly into the DOM. **Why:** Prevents malicious code from being injected into your application's pages. ### 7.3. Cross-Site Request Forgery (CSRF) Protection **Standard:** Implement CSRF protection for forms and other state-changing requests. **Do This:** Use CSRF tokens or other mechanisms to verify the authenticity of requests. **Don't Do This:** Disabling CSRF protection without a valid reason. **Why:** Prevents attackers from forging requests on behalf of legitimate users. ### 7.4. Subresource Integrity (SRI) **Standard:** Use SRI to verify the integrity of third-party resources loaded from CDNs. **Do This:** Add "integrity" attributes to "<script>" and "<link>" tags that load resources from CDNs. **Don't Do This:** Loading third-party resources without integrity checks **Why:** Prevents attackers from injecting malicious code into your application by tampering with third-party resources. While a package manager is preferable, if a CDN is used, SRI helps ensure the CDN content has not been tampered with. ## 8. Bootstrap Specific Tooling ### 8.1. Themes and Customization Generators **Standard**: Leverage tools that help generate Bootstrap themes and customizations. **Do This**: Explore online Bootstrap theme builders or customization tools to generate initial SCSS files. Tools like Bootswatch and ThemeRoller can be helpful. **Don't Do This**: Starting from scratch for common styling needs, unless very custom designs are required. **Why**: Saves time and ensures maintainability when starting new projects or redesigning existing ones. ### 8.2. Snippet Libraries **Standard**: Use snippet libraries within your editor for common Bootstrap components and patterns. **Do This**: Install extensions in your editor that offer code snippets for Bootstrap elements, such as navigation bars, forms, and modals. **Don't Do This**: Rewriting common Bootstrap structures from memory constantly. **Why**: Enhances development speed and reduces errors by injecting correct code structures. ### 8.3. VS Code extensions. **Standard**: Utilize VS Code extensions for advanced Boostrap support. **Do This**: leverage Bootstrap specific VS Code extensions that offer features likes code completion, linting and documentation. **Don't Do This**: Missing opportunity to maximize productivity by taking proper advantage of code extensions **Why**: Improving development process and code quality.
# Performance Optimization Standards for Bootstrap This document outlines performance optimization standards for developing with Bootstrap. It provides guidelines to improve application speed, responsiveness, and resource utilization, specifically focusing on Bootstrap's components, utilities, and JavaScript plugins. These standards are geared towards the latest version of Bootstrap. ## 1. CSS Optimization ### 1.1. Selective Importing of Bootstrap CSS **Standard:** Only import the necessary Bootstrap CSS components into your project. Avoid importing the entire "bootstrap.css" or "bootstrap.min.css" file unless the project truly uses every aspect of the framework. **Why:** Importing the entire stylesheet introduces redundant CSS rules that the browser must parse, even if they are not used. This bloats the overall CSS and increases load times. **Do This:** Use Bootstrap's Sass files to import only the required components. """scss // Custom Bootstrap import @import "node_modules/bootstrap/scss/functions"; @import "node_modules/bootstrap/scss/variables"; @import "node_modules/bootstrap/scss/mixins"; // Core components @import "node_modules/bootstrap/scss/reboot"; @import "node_modules/bootstrap/scss/grid"; @import "node_modules/bootstrap/scss/utilities"; // VERY IMPORTANT! @import "node_modules/bootstrap/scss/buttons"; @import "node_modules/bootstrap/scss/forms"; @import "node_modules/bootstrap/scss/card"; // Optional components @import "node_modules/bootstrap/scss/nav"; @import "node_modules/bootstrap/scss/navbar"; @import "node_modules/bootstrap/scss/alerts"; @import "node_modules/bootstrap/scss/modal"; // Utilities are crucial for responsive design and should usually be included @import "node_modules/bootstrap/scss/utilities/api"; """ **Don't Do This:** """html <!-- Importing the entire Bootstrap CSS --> <link rel="stylesheet" href="css/bootstrap.min.css"> """ ### 1.2. Customizing Bootstrap with Sass Variables **Standard:** Utilize Bootstrap's Sass variables to customize the framework instead of overriding CSS rules directly. **Why:** Modifying Sass variables allows for a consistent and maintainable theme. Changes are compiled into a unified stylesheet, reducing CSS specificity conflicts and improving maintainability. Furthermore, you can customize the Bootstrap configuration before it's compiled, removing unused styles, improving the overall size of the CSS bundle. **Do This:** Customize "_variables.scss" or create a custom configuration file. """scss // Custom _variables.scss file $primary: #007bff; // Bootstrap primary color $secondary: #6c757d; // Bootstrap secondary color $enable-shadows: true; // Import Bootstrap @import "node_modules/bootstrap/scss/bootstrap"; // Add custom styles *after* Bootstrap import to override if necessary body { font-family: 'Arial', sans-serif; } """ **Don't Do This:** """css /* Overriding Bootstrap styles directly, which leads to specificity issues */ .btn-primary { background-color: #007bff !important; /*Avoid !important*/ } """ ### 1.3. CSS Minification and Compression **Standard:** Minify and compress the compiled CSS files before deployment. **Why:** Minification removes unnecessary characters (whitespace, comments) from CSS, reducing file size. Compression (e.g., Gzip) further reduces file size during transmission. **Do This:** Use a build tool like Webpack, Parcel, or Gulp to minify and compress CSS. """javascript // webpack.config.js example const TerserPlugin = require('terser-webpack-plugin'); const CssMinimizerPlugin = require("css-minimizer-webpack-plugin"); module.exports = { //... other webpack configuration, optimization: { minimize: true, minimizer: [ new TerserPlugin(), new CssMinimizerPlugin(), ], }, }; """ **Don't Do This:** Deploy unminified and uncompressed CSS files to production. ### 1.4. Avoid Inline Styles **Standard:** Minimize the use of inline styles. **Why:** Inline styles increase HTML file size and make CSS harder to maintain. They also circumvent CSS caching, as they're unique to each HTML element. **Do This:** Define styles in CSS classes. """html <!-- Preferred --> <button class="btn btn-primary custom-button">Click Me</button> <style> .custom-button { margin-top: 10px; } </style> """ **Don't Do This:** """html <!-- Avoid --> <button style="background-color: #007bff; color: white; border: none; padding: 10px 20px;">Click Me</button> """ ### 1.5. Leverage CSS Sprites **Standard:** Combine multiple small images into a single image sprite and use CSS "background-position" to display specific parts. **Why:** Reduces the number of HTTP requests, improving page load time. This is less critical with HTTP/2 multiplexing, but still can provide benefits in specific scenarios. **Do This:** 1. Combine images into a single sprite using tools like ImageMagick or online sprite generators. 2. Use CSS to control which part of the sprite is visible. """css .icon-email { background-image: url('images/sprite.png'); background-position: 0 0; width: 16px; height: 16px; display: inline-block; } .icon-print { background-image: url('images/sprite.png'); background-position: -16px 0; width: 16px; height: 16px; display: inline-block; } """ **Don't Do This:** Use individual image files for numerous small icons if they can reasonably be combined into a sprite (or use SVG icons, see later). ### 1.6. Consider Using SVG Icons **Standard:** Use SVGs for icons wherever possible. **Why:** SVGs are vector-based, meaning they scale without losing quality, and are generally smaller in file size than raster images (like PNGs or JPGs) – especially for simple icons. They can also be styled with CSS, and animated. **Do This:** """html <svg class="icon" width="24" height="24"> <use xlink:href="path/to/sprite.svg#icon-name"></use> </svg> """ """css .icon { fill: currentColor; /* Allow icon color to be controlled by text color */ } """ **Don't Do This:** Use raster images for icons if SVG alternatives are available. ### 1.7. Utilize Browser Caching **Standard:** Configure your server to set appropriate "Cache-Control" headers for CSS files. **Why:** Enables browsers to cache CSS files, reducing the need to re-download them on subsequent visits. **Do This:** """apache # .htaccess example <filesMatch ".(css)$"> Header set Cache-Control "max-age=31536000, public" </filesMatch> """ ### 1.8. Tree Shaking with PurgeCSS **Standard:** When using a module bundler like Webpack, consider integrating PurgeCSS to eliminate unused Bootstrap styles. **Why:** Further reduces CSS file size by analyzing your HTML, JavaScript, and other template files to remove any CSS rules that are not actually used. **Do This:** Install PurgeCSS and configure it in your Webpack workflow. """javascript // webpack.config.js const PurgeCSSPlugin = require('purgecss-webpack-plugin'); const glob = require('glob'); const path = require('path'); module.exports = { // ... plugins: [ new PurgeCSSPlugin({ paths: glob.sync("${path.join(__dirname, 'src')}/**/*", { nodir: true }), // Paths to all of your HTML, JS, etc. safelist: [/show/, /collapsing/], // Add classes that are dynamically added and should not be removed. Example: Bootstrap's collapse animation classes. }), ], }; """ **Don't Do This:** Assume a small CSS filesize just because you aren't explicitly using all components; Tree shaking ensures *genuinely* unused CSS is removed. ## 2. JavaScript Optimization ### 2.1. Selective Importing of Bootstrap JavaScript **Standard:** Only include the necessary Bootstrap JavaScript plugins. Just like with CSS, avoid importing the entire "bootstrap.bundle.js" unless you genuinely need all the plugins. **Why:** Importing all JavaScript plugins increases the page's load time and parsing time, even if many of them remain unused. **Do This:** Import individual plugins using ES modules. """javascript // Import specific Bootstrap components import Alert from 'bootstrap/js/dist/alert'; import Collapse from 'bootstrap/js/dist/collapse'; // Initialize the plugins where needed const alert = new Alert(document.querySelector('.alert')); const collapseElementList = document.querySelectorAll('.collapse'); const collapseList = [...collapseElementList].map(collapseEl => new Collapse(collapseEl)); """ **Don't Do This:** """html <!-- Importing the entire Bootstrap JavaScript bundle --> <script src="js/bootstrap.bundle.min.js"></script> """ ### 2.2. Deferred or Asynchronous Loading of JavaScript **Standard:** Use the "defer" or "async" attributes when loading JavaScript files. **Why:** Prevents JavaScript from blocking HTML parsing, improving perceived page load time. "defer" ensures scripts are executed in order after HTML parsing is complete; "async" loads scripts asynchronously without guaranteeing order. Use "defer" for scripts that depend on the DOM, "async" for independent scripts. **Do This:** """html <!-- Deferred loading --> <script src="js/bootstrap.bundle.min.js" defer></script> <!-- Asynchronous Loading --> <script src="js/your-script.js" async></script> """ **Don't Do This:** """html <!-- Blocking JavaScript loading --> <script src="js/bootstrap.bundle.min.js"></script> """ ### 2.3. JavaScript Minification and Compression **Standard:** Minify and compress JavaScript files before deployment. **Why:** Reduces file size, improving load times. **Do This:** Use a build tool like Webpack, Parcel, or Gulp. """javascript // webpack.config.js example (Already shown in CSS example) const TerserPlugin = require('terser-webpack-plugin'); module.exports = { //... other webpack configuration, optimization: { minimize: true, minimizer: [ new TerserPlugin() ], }, }; """ ### 2.4. Debouncing and Throttling **Standard:** Implement debouncing or throttling for event handlers that fire frequently (e.g., "resize", "scroll", "keyup"). **Why:** Prevents excessive function calls, improving performance. *Debouncing* executes a function only after a certain amount of time has passed since the last time the event was fired. *Throttling* executes a function at a regular interval. **Do This:** """javascript // Debouncing example function debounce(func, delay) { let timeout; return function(...args) { const context = this; clearTimeout(timeout); timeout = setTimeout(() => func.apply(context, args), delay); }; } window.addEventListener('resize', debounce(() => { // Perform expensive operation here console.log('Resized!'); }, 250)); // Throttling example function throttle(func, limit) { let lastFunc; let lastRan; return function(...args) { const context = this; if (!lastRan) { func.apply(context, args); lastRan = Date.now(); } else { clearTimeout(lastFunc); lastFunc = setTimeout(function() { if ((Date.now() - lastRan) >= limit) { func.apply(context, args); lastRan = Date.now(); } }, limit - (Date.now() - lastRan)); } }; } window.addEventListener('scroll', throttle(() => { // Perform an action on scroll console.log("Scroll event"); }, 100)); """ **Don't Do This:** Execute expensive operations directly within frequently triggered event handlers. ### 2.5. Lazy Loading Images **Standard:** Implement lazy loading for images that are not immediately visible in the viewport. **Why:** Improves initial page load time by deferring the loading of non-critical resources. **Do This:** Use the "loading="lazy"" attribute. """html <img src="image.jpg" alt="Image" loading="lazy"> """ For wider browser compatibility, consider using a JavaScript library like Lozad.js: """html <img class="lozad" data-src="image.jpg" alt="Image"> <script src="https://cdn.jsdelivr.net/npm/lozad/dist/lozad.min.js"></script> <script> const observer = lozad(); // passing a "NodeList" (as "querySelectorAll" returns) observer.observe(); </script> """ **Don't Do This:** Load all images upfront, even those below the fold. ### 2.6. Avoid Excessive DOM Manipulation **Standard:** Minimize DOM manipulations directly within loops or frequently called functions. **Why:** DOM manipulations are expensive operations. Reducing these operations results in performance improvements. **Do This:** Batch DOM updates. """javascript // Better approach: Batch DOM updates function updateList(items) { const list = document.getElementById('myList'); let fragment = document.createDocumentFragment(); // Create a fragment items.forEach(item => { let li = document.createElement('li'); li.textContent = item; fragment.appendChild(li); // Append to the fragment }); list.appendChild(fragment); // Append the fragment to the list in one shot } """ **Don't Do This:** """javascript // Anti-pattern: Excessive DOM manipulation in a loop function addItemsOneByOne(items) { const list = document.getElementById('myList'); items.forEach(item => { let li = document.createElement('li'); li.textContent = item; list.appendChild(li); // Adds a DOM element one by one - slow }); } """ ### 2.7. Remove Unused JavaScript **Standard:** Regularly audit your project and remove any unused or deprecated JavaScript code. **Why:** Unused code bloats the application and increases parsing time. **Do This:** Use code coverage tools to identify unused code and remove it. ### 2.8. Optimize Third-Party Libraries **Standard:** Use third-party libraries judiciously and evaluate their impact on performance. **Why:** Some libraries can significantly increase the application's bundle size and execution time. **Do This:** * Choose lightweight alternatives where possible. * Load libraries from CDNs where appropriate, but be mindful of potential privacy concerns and CDN reliability. * Consider lazy-loading third-party libraries if they are not critical for initial rendering. ## 3. HTML Optimization ### 3.1. Reduce DOM Size **Standard:** Keep the DOM size as small as possible. **Why:** A large DOM can negatively impact performance, especially on mobile devices. The larger the DOM, the more memory it consumes and the slower the browser is to render and manipulate it. **Do This:** * Simplify the HTML structure. * Remove unnecessary elements and attributes. * Use semantic HTML elements appropriately. * Virtualize lists where necessary. ### 3.2. Optimize Images **Standard:** Optimize images by compressing them, using appropriate formats (WebP, AVIF), and resizing them to the correct dimensions. **Why:** Reduces the size of image files, improving load times and reducing bandwidth consumption. Modern formats such as WebP and AVIF provide better compression and quality than older formats like JPEG or PNG. **Do This:** * Use tools like ImageOptim or TinyPNG to compress images. * Use the "<picture>" element to provide different image formats based on browser support. * Use responsive images with the "srcset" attribute. """html <picture> <source srcset="img/image.webp" type="image/webp"> <img src="img/image.jpg" alt="My Image"> </picture> <img src="img/image.jpg" srcset="img/image-small.jpg 480w, img/image-medium.jpg 800w" alt="My Image"> """ ### 3.3. Use Semantic HTML **Standard:** Use semantic HTML elements to provide structure and meaning to your content. **Why:** Improves accessibility, SEO, and maintainability. It also allows browsers to render the page more efficiently. **Do This:** * Use elements like "<article>", "<nav>", "<aside>", "<header>", "<footer>", "<main>" to structure your content. * Use headings ("<h1>" to "<h6>") in the correct order. * Use "<figure>" and "<figcaption>" for images and captions. ### 3.4. Minimize HTTP Requests **Standard:** Reduce the number of HTTP requests by combining files, using CSS sprites, and inlining critical resources. Although HTTP/2 alleviates this issue, reducing requests is still a worthwhile goal. **Why:** Each HTTP request adds overhead and increases page load time. **Do This:** * Combine CSS and JavaScript files. * Use CSS sprites for icons and small images. * Inline critical CSS to avoid render-blocking. * Use data URIs for small images (though be mindful of cacheability). ### 3.5. Leverage Browser Caching for Assets **Standard:** Configure your server to set far-future "Cache-Control" headers for static assets (images, CSS, JavaScript). Also use versioning/cache busting when you *do* need clients to download a updated resource. **Why:** Allows browsers to cache static assets, reducing the need to re-download them on subsequent visits. **Do This:** * Set "Cache-Control" headers to "max-age=31536000" (one year) for static assets. * Use versioning or cache-busting techniques to force browsers to download new versions of assets when they change. """html <!-- versioning the css file to control the cache --> <link rel="stylesheet" href="css/style.css?v=1.0.1"> """ ## 4. Bootstrap-Specific Performance Considerations ### 4.1. Responsive Images in Bootstrap **Standard:** Utilize Bootstrap's responsive image classes (".img-fluid") or the "<picture>" element with "srcset" to serve appropriately sized images for different screen sizes. Bootstrap's built-in responsive image classes are just a starting point; tailor image delivery to actual breakpoints and display densities. **Why:** Prevents browsers from downloading excessively large images for small screens, saving bandwidth and improving load times on mobile devices. **Do This:** """html <img src="image.jpg" class="img-fluid" alt="Responsive image"> """ ### 4.2. Collapse Component Optimization **Standard:** Use the collapse component judiciously and load content within collapsed sections only when needed. **Why:** Collapsed sections with large amounts of content can impact initial page load time. **Do This:** * Load content within collapsed sections dynamically (e.g., using AJAX) when the user expands the section. * Consider using pagination or infinite scrolling for long lists within collapsed sections. ### 4.3. Modal Optimization **Standard:** Avoid placing large or complex content within Bootstrap modals, especially if the modal is not frequently used. Lazy-load the modal content as necessary. **Why:** Large modals can degrade performance, especially on mobile devices. The modal content, even if hidden initially, can still impact initial page load time. **Do This:** * Load modal content dynamically when the modal is opened. * Use a lightweight alternative to modals if the content is simple. ### 4.4. Carousel Optimization **Standard:** Optimize images within Bootstrap carousels. Lazy-load images within the carousel items that are not initially visible. Debounce any carousel controls. **Why:** Inefficiently-sized images and animations within carousels can cause performance bottlenecks. **Do This:** * Use optimized images as mentioned earlier * Implement lazy loading for carousel images: """html <div id="carouselExample" class="carousel slide" data-bs-ride="carousel"> <div class="carousel-inner"> <div class="carousel-item active"> <img src="image1.jpg" class="d-block w-100" alt="Slide 1"> </div> <div class="carousel-item"> <img data-src="image2.jpg" class="d-block w-100 lozad" alt="Slide 2"> </div> <div class="carousel-item"> <img data-src="image3.jpg" class="d-block w-100 lozad" alt="Slide 3"> </div> </div> <button class="carousel-control-prev" type="button" data-bs-target="#carouselExample" data-bs-slide="prev"> <span class="carousel-control-prev-icon" aria-hidden="true"></span> <span class="visually-hidden">Previous</span> </button> <button class="carousel-control-next" type="button" data-bs-target="#carouselExample" data-bs-slide="next"> <span class="carousel-control-next-icon" aria-hidden="true"></span> <span class="visually-hidden">Next</span> </button> </div> <script> const observer = lozad(); observer.observe(); </script> """ ### 4.5. Table Optimization **Standard:** For large tables, consider using pagination, virtualization, or filtering to reduce the amount of data displayed at once. If possible, avoid using DataTables or similar plugins unless genuinely needed - they can add significant overhead. **Why:** Rendering large tables can be slow, especially on mobile devices. **Do This:** * Implement pagination for large tables. * Use virtualization to render only the visible rows. * Allow users to filter the data. ### 4.6. Accessibility Considerations **Standard:** While optimizing for performance, ensure that accessibility is not compromised. **Why:** Accessibility is crucial for providing an inclusive user experience. **Do This:** * Use semantic HTML elements. * Provide alternative text for images. * Ensure sufficient contrast between text and background colors. * Follow WCAG guidelines. ## 5. Monitoring & Measurement ### 5.1. Performance Audits **Standard:** Regularly conduct performance audits using tools like Google PageSpeed Insights, Lighthouse, or WebPageTest. **Why:** Provides insights into performance bottlenecks and areas for improvement. **Do This:** Run audits regularly and address the identified issues. Implement a process for continuous performance monitoring. ### 5.2. Real User Monitoring (RUM) **Standard:** Implement Real User Monitoring (RUM) to capture performance data from real users. **Why:** Provides a more accurate picture of the user experience than synthetic tests. **Do This:** Use tools like Google Analytics, New Relic, or Datadog to collect RUM data. Track key performance metrics like page load time, time to first byte (TTFB), and time to interactive (TTI). ## 6. Version Upgrades ### 6.1 Stay up to date **Standard:** Regularly update Bootstrap to the latest stable version. **Why:** Newer versions often include performance improvements and bug fixes. Keeping up-to-date ensures you benefit from these enhancements. **Do This:** Monitor Bootstrap releases and plan to incrementally upgrade the framework. By adhering to these performance optimization standards, development teams can build faster, more responsive, and more efficient Bootstrap applications. The key is to *always* be measuring and monitoring performance, experimenting with different approaches, and making continuous improvements.
# Testing Methodologies Standards for Bootstrap This document outlines the standards for testing methodologies when developing with Bootstrap. It covers unit, integration, and end-to-end testing strategies specific to Bootstrap components, utilities, and responsive behaviors. Adhering to these standards ensures maintainability, reliability, and high-quality code. It also ensures that Bootstrap upgrades are handled smoothly and potential regressions are caught early in the development cycle. ## 1. General Testing Principles ### 1.1 Follow Test-Driven Development (TDD) Principles **Do This:** Write tests before implementing the actual Bootstrap components or customizations. **Don't Do This:** Write tests as an afterthought or skip testing altogether. **Why:** TDD forces you to think about the expected behavior and API of your components before writing the implementation. This leads to a more robust and well-designed system. **Example:** 1. **Write a test:** Define the expected behavior of a custom Bootstrap button variant. 2. **Run the test (it fails):** The test fails because the button variant isn't implemented. 3. **Write the implementation:** Implement the custom Bootstrap button variant using CSS and customizations. 4. **Run the test (it passes):** The test passes, confirming the button variant behaves as expected. 5. **Refactor:** Improve the implementation without changing its behavior, ensuring the test suite remains passing. ### 1.2 Aim for High Test Coverage **Do This:** Strive for close to 100% test coverage, especially for critical components. **Don't Do This:** Ignore edge cases or complex interactions. **Why:** Higher test coverage reduces the risk of introducing bugs and makes refactoring safer. **Example:** Ensure that all variations of a button's appearance (different sizes, states, and contextual classes) are tested adequately. ### 1.3 Focus on Behavior **Do This:** Test the behavior (what the code *does*), not the implementation (how the code *does* it). **Don't Do This:** Write brittle tests that are overly coupled to the component's internal structure. **Why:** Behavior-based tests are more resilient to refactoring. If you change the implementation details but the component's behavior remains the same, the tests should still pass. **Example:** Test that clicking a button triggers a specific action or modifies the DOM in a predictable way, rather than testing specific CSS properties or internal helper functions. ## 2. Unit Testing ### 2.1 Focus on Individual Components **Do This:** Isolate Bootstrap components and test their functionality in isolation. **Don't Do This:** Rely on external dependencies or complex setup for unit tests. **Why:** Unit tests should be fast and focused, allowing you to quickly identify and fix issues in individual components. Isolation ensures tests are repeatable and not influenced by external factors. **Technology:** Use frameworks like Jest, Mocha, or Jasmine for Javascript unit tests and PHPUnit if you have PHP backend components using Bootstrap templating. **Example (Jest):** """javascript // my-component.js export function calculateTotal(price, quantity) { if (quantity < 0) { return 0; //Handle negative quantites } return price * quantity; } // my-component.test.js import { calculateTotal } from './my-component'; describe('calculateTotal', () => { it('should calculate the total price correctly', () => { expect(calculateTotal(10, 2)).toBe(20); }); it('should return 0 for negative quantity', () => { expect(calculateTotal(10, -1)).toBe(0); }); }); """ ### 2.2 Mock Dependencies **Do This:** Mock out any dependencies that the component relies on. **Don't Do This:** Make actual HTTP requests or interact with databases during unit tests. **Why:** Mocking makes tests faster, deterministic, and isolated. **Example (Jest):** """javascript // api-service.js export async function fetchData() { const response = await fetch('https://api.example.com/data'); return response.json(); } // my-component.js import { fetchData } from './api-service'; export async function processData() { const data = await fetchData(); // ... further processing return data; } // my-component.test.js import { processData } from './my-component'; import * as apiService from './api-service'; jest.mock('./api-service'); // Mock the entire api-service module describe('processData', () => { it('should process data correctly', async () => { const mockData = { name: 'Test Data' , value:100}; apiService.fetchData.mockResolvedValue(mockData); // Set the return value of the mocked function const result = await processData(); expect(result).toEqual(mockData); expect(apiService.fetchData).toHaveBeenCalled(); // Verify that the mocked function was called }); }); """ ### 2.3 Test Bootstrap JavaScript Plugin Behavior **Do This:** Test that Bootstrap JavaScript plugins are correctly initialized and that their methods are called when expected. Use "jest.spyOn" or similar tools to monitor plugin calls. **Don't Do This:** Try to reimplement or duplicate Bootstrap's internal logic; focus on how *your* code interacts with the plugin. **Example:** Suppose you have a custom component that opens a Bootstrap modal. """html <button id="openModalButton" data-bs-toggle="modal" data-bs-target="#myModal"> Open Modal </button> <div class="modal fade" id="myModal" tabindex="-1" aria-labelledby="myModalLabel" aria-hidden="true"> <div class="modal-dialog"> <div class="modal-content"> <div class="modal-header"> <h5 class="modal-title" id="myModalLabel">Modal title</h5> <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> </div> <div class="modal-body"> ... </div> <div class="modal-footer"> <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> </div> </div> </div> </div> """ """javascript // custom-component.js import * as bootstrap from 'bootstrap'; //Import bootstrap export function initializeModalTrigger() { const button = document.getElementById('openModalButton'); button.addEventListener('click', () => { const myModal = new bootstrap.Modal(document.getElementById('myModal')); myModal.show(); }); } // custom-component.test.js import { initializeModalTrigger } from './custom-component'; import * as bootstrap from 'bootstrap'; //Import bootstrap describe('initializeModalTrigger', () => { let button; let modal; beforeEach(() => { document.body.innerHTML = " <button id="openModalButton" data-bs-toggle="modal" data-bs-target="#myModal"> Open Modal </button> <div class="modal fade" id="myModal" tabindex="-1" aria-labelledby="myModalLabel" aria-hidden="true"> <div class="modal-dialog"> <div class="modal-content"> <div class="modal-header"> <h5 class="modal-title" id="myModalLabel">Modal title</h5> <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button> </div> <div class="modal-body"> ... </div> <div class="modal-footer"> <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button> </div> </div> </div> </div>"; button = document.getElementById('openModalButton'); // Mock the Bootstrap Modal class and its show method modal = { show: jest.fn(), }; jest.spyOn(bootstrap, 'Modal').mockImplementation(() => modal); initializeModalTrigger(); // Initialize the component to attach the event listener }); afterEach(() => { jest.restoreAllMocks(); }); it('should initialize a Bootstrap Modal and call show() when the button is clicked', () => { button.click(); expect(bootstrap.Modal).toHaveBeenCalledWith(document.getElementById('myModal')); expect(modal.show).toHaveBeenCalled(); // Verify that modal.show() was called }); }); """ ### 2.4 Test Accessibility Attributes **Do This:** Verify that elements have the correct ARIA attributes and roles, especially for interactive components. This ensures the components are accessible to users with disabilities. **Don't Do This:** Ignore ARIA attributes or assume that assistive technologies will "figure it out." **Why:** Accessibility is crucial. Providing the correct ARIA attributes allows screen readers and other assistive technologies to understand and interpret the structure and behavior of your components. **Example:** When creating a custom accordion component, ensure that the header elements have "aria-expanded" attributes that correctly reflect the accordion panel's state. Test that these attributes are updated correctly when the panels are expanded and collapsed using Javascript ## 3. Integration Testing ### 3.1 Test Component Interactions **Do This:** Verify that different Bootstrap components work together correctly. **Don't Do This:** Assume that components will integrate seamlessly without testing. **Why:** Integration tests catch problems arising from interactions between components that might not be apparent from unit tests alone. **Example:** Test how custom JavaScript interacts with Bootstrap's carousel plugin to verify that it updates the carousel indicators and content correctly. ### 3.2 Test Responsive Behavior **Do This:** Use a testing framework that allows simulating different screen sizes (e.g., Cypress, Puppeteer with viewport settings or specialized libraries). **Don't Do This:** Rely solely on manual testing with browser resizing. **Why:** Bootstrap's responsive grid system is a core feature. Automated testing helps ensure that layouts adapt correctly across different devices. **Example (Cypress):** """javascript // cypress/e2e/responsive.cy.js describe('Responsive Layout', () => { it('should display the mobile layout on small screens', () => { cy.viewport('iphone-6'); // Simulate a small screen cy.visit('/'); cy.get('#mobile-menu').should('be.visible'); cy.get('#desktop-menu').should('not.be.visible'); }); it('should display the desktop layout on large screens', () => { cy.viewport('macbook-15'); // Simulate a large screen cy.visit('/'); cy.get('#desktop-menu').should('be.visible'); cy.get('#mobile-menu').should('not.be.visible'); }); }); """ ### 3.3 Test Complex Layout Scenarios **Do This:** Test complex layouts involving multiple Bootstrap grid columns, offsets, and ordering. **Don't Do This:** Oversimplify layout tests; cover a range of representative scenarios. **Why:** Complex layouts are prone to errors. Thorough testing helps ensure that elements are positioned correctly responsively. **Example:** A dashboard layout with a sidebar, main content area, and widgets. Ensure the sidebar collapses correctly on mobile, and the main content area takes up the full width, and that widgets re-flow properly. ## 4. End-to-End (E2E) Testing ### 4.1 Simulate Real User Interactions **Do This:** Use a tool like Cypress or Puppeteer to automate user flows and verify that the entire application works as expected. **Don't Do This:** Focus solely on technical details; think about how real users will interact with the system. **Why:** E2E tests provide the highest level of confidence that the application is working correctly from the user's perspective. **Example (Cypress):** """javascript // cypress/e2e/user-flow.cy.js describe('User Registration Flow', () => { it('should allow a user to register and log in', () => { cy.visit('/register'); cy.get('#name').type('John Doe'); cy.get('#email').type('john.doe@example.com'); cy.get('#password').type('password123'); cy.get('#confirmPassword').type('password123'); cy.get('button[type="submit"]').click(); // Assert successful registration message cy.contains('Registration successful').should('be.visible'); // Redirect to login page (assuming registration redirects to login) cy.visit('/login'); cy.get('#email').type('john.doe@example.com'); cy.get('#password').type('password123'); cy.get('button[type="submit"]').click(); // Verify successful login and redirection to dashboard cy.url().should('include', '/dashboard'); cy.contains('Welcome, John Doe').should('be.visible'); }); }); """ ### 4.2 Test Across Different Browsers and Devices **Do This:** Run E2E tests on a variety of browsers and devices to ensure compatibility. Use cloud testing providers like BrowserStack or Sauce Labs. **Don't Do This:** Assume that the application will work the same way in all browsers. **Why:** Browser compatibility is essential for a good user experience. **Example:** Test the same user flow in Chrome, Firefox, Safari, and Edge, and on emulated mobile devices. ### 4.3 Test Accessibility Compliance **Do This:** Use automated accessibility testing tools (e.g., axe-core) within your E2E tests to identify accessibility issues. **Don't Do This:** Rely solely on manual accessibility testing; automate as much as possible. **Why:** Automated accessibility testing can catch many common accessibility errors early in the development cycle. **Example (Cypress with axe-core):** """javascript // cypress/e2e/accessibility.cy.js import 'cypress-axe'; describe('Accessibility Tests', () => { it('should have no accessibility violations on the homepage', () => { cy.visit('/'); cy.injectAxe(); cy.checkA11y(); // Check the entire page for accessibility violations }); it('should have no accessibility violations on the registration page', () => { cy.visit('/register'); cy.injectAxe(); cy.checkA11y(); }); // ... more tests for different pages and components }); """ ### 4.4 Testing Bootstrap Theming (Sass Variables) **Do This:** Ensure your tests cover the application of custom Bootstrap themes. Verify that key visual elements (colors, fonts, spacing) are correctly styled according to the selected theme. Use snapshots to compare rendered UI elements against baseline images. **Don't Do This:** Only test the default Bootstrap theme; neglecting custom themes can lead to visual regressions. **Why:** Theming is a key feature allowing customization; testing confirms themes are correctly applied, maintaining visual consistency. **Example (Snapshot testing with Jest and Percy):** requires setting up Percy for visual testing. 1. **Configure Percy:** Set up your Percy account and integrate it into your project. Percy will capture snapshots of your application's UI and compare them against baseline images. """javascript //Add Percy.io to the test import '@percy/cypress'; describe('Theme rendering', () => { beforeEach(() => { cy.visit('http://localhost:3000/'); // Replace with your app URL }); it('Should verify visual appearance of the default theme', () => { cy.percySnapshot('Default Theme'); }); it('Should verify visual appearance of the alternative theme', () => { cy.get('#theme-switcher').select('dark'); // Assuming you have a theme switcher dropdown cy.percySnapshot('Dark Theme'); }); }); """ ### 4.5 Regularly Review and Update Tests **Do This:** Treat your tests as living documentation that needs to be maintained and updated as the application evolves. **Don't Do This:** Let tests become stale or irrelevant. **Why:** Outdated tests can provide a false sense of security or even mislead developers. ## 5. Test Data Management ### 5.1 Use Realistic Test Data **Do This:** Create test data that accurately reflects the data that users will enter into the system. **Don't Do This:** Use unrealistic or simplistic test data. **Why:** Realistic test data helps uncover edge cases and data validation issues. ### 5.2 Seed the Database **Do This:** Use database seeding to populate the database with test data before running tests. **Don't Do This:** Rely on manual data entry. **Why:** Database seeding ensures a consistent and repeatable testing environment. ## 6. Continuous Integration (CI) ### 6.1 Integrate Tests into the CI Pipeline **Do This:** Run all tests automatically as part of the CI pipeline. **Don't Do This:** Rely on manual test execution or skip tests in the CI environment. **Why:** CI ensures that tests are run consistently and that issues are detected early in the development cycle. ### 6.2 Fail the Build on Test Failures **Do This:** Configure the CI pipeline to fail the build if any tests fail. **Don't Do This:** Ignore test failures or allow the build to proceed with failing tests. **Why:** Failing the build prevents broken code from being deployed to production. ## 7. Static Analysis and Linting ### 7.1 Use ESLint, Stylelint, and other linters **Do This:** Integrate linters into your CI pipeline to enforce code style guidelines automatically. **Don't Do This:** Rely solely on manual code reviews to catch style issues. **Why:** Linters help maintain code consistency and identify potential errors early in the development cycle. ### 7.2 Enforce Bootstrap Coding Standards **Do This:** Configure linters to enforce Bootstrap-specific coding standards. **Don't Do This:** Allow violations of Bootstrap's coding standards to accumulate. **Why:** Consistent adherence to Bootstrap's coding standards makes the codebase easier to understand and maintain. For example, you can specify the Bootstrap CSS class order using stylelint plugins. By adhering to these testing methodologies, you can create robust, maintainable, and reliable Bootstrap applications.
# Deployment and DevOps Standards for Bootstrap This document outlines coding standards for Deployment and DevOps when working with Bootstrap-based projects. It covers build processes, CI/CD pipeline integration, and production considerations specific to Bootstrap projects, emphasizing maintainability, performance, and security. These standards aim to provide clear guidelines for developers and serve as a reference for AI coding assistants. ## 1. Build Processes and Dependency Management ### 1.1 Dependency Management **Standard:** Use a modern package manager (npm, yarn, or pnpm) for managing Bootstrap and its dependencies. Explicitly declare all dependencies in "package.json". Avoid direct CDN links in production where possible; instead, manage dependencies through the build tool. **Why:** Package managers guarantee consistent dependency versions across environments, simplify updates, and improve security by allowing for vulnerability scanning. CDN links bypass version control and may introduce unexpected changes or security risks. **Do This:** """json // package.json { "name": "my-bootstrap-project", "version": "1.0.0", "dependencies": { "bootstrap": "^5.3.0", "jquery": "^3.6.0", // Only include if your project needs jQuery. Modern Bootstrap often doesn't "@popperjs/core": "^2.11.6" // Needed for Bootstrap's dropdowns, tooltips, etc. }, "devDependencies": { "sass": "^1.50.0", "autoprefixer": "^10.4.5", "postcss-cli": "^9.1.0", "concurrently": "^7.0.0" , "browser-sync": "^2.27.0" }, "scripts": { "build:css": "sass --style compressed scss:css", "prefix:css": "postcss --use autoprefixer -b 'last 10 versions' css/style.css -o css/style.prefix.css", "build": "npm run build:css && npm run prefix:css", "watch:css": "sass --watch scss:css", "watch:prefix": "postcss --watch --use autoprefixer -b 'last 10 versions' css/style.css -o css/style.prefix.css", "watch": "concurrently \"npm run watch:css\" \"npm run watch:prefix\"", "serve": "browser-sync start --server --files \"css/*.css, *.html, js/*.js\"", "start": "npm run build && concurrently \"npm run watch\" \"npm run serve\"" } } """ **Don't Do This:** """html <!-- index.html --> <!-- BAD: Directly linking to a CDN --> <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/5.3.0/css/bootstrap.min.css"> """ **Anti-Pattern:** Manually managing library files downloaded from the internet or copying them between projects. This leads to version control issues and makes updates difficult. ### 1.2 CSS Preprocessing **Standard:** Use a CSS preprocessor like Sass or Less for managing Bootstrap's styles and customizing the theme. Compile the CSS during the build process. **Why:** CSS preprocessors enable features like variables, mixins, and nesting, enhancing maintainability and organization of styles. Compiling during the build ensures optimized CSS for production. **Do This:** 1. Install Sass as a dev dependency: "npm install -D sass" 2. Create "scss/custom.scss" file to override Bootstrap variables and add custom styles. """scss // scss/custom.scss // Override Bootstrap variables $primary: #007bff; $secondary: #6c757d; // Import Bootstrap @import "../node_modules/bootstrap/scss/bootstrap"; // Custom styles .my-custom-class { color: $primary; } """ 3. Configure the "build" script in "package.json" to compile Sass: """json // package.json { "scripts": { "build:css": "sass --style compressed scss:css", "build": "npm run build:css" } } """ 4. Run "npm run build" to generate "css/style.css". **Don't Do This:** * Editing Bootstrap's core CSS files directly. This makes updates difficult and can break your customizations. * Using inline styles extensively. They're hard to manage and override. **Anti-Pattern:** Using a CSS preprocessor only for a few minor changes. Leverage its full potential for creating a maintainable and scalable stylesheet architecture. Applying a CSS preprocessor inconsistently throughout the project. Pick one and stick with it. ### 1.3 JavaScript Bundling and Minification. **Standard:** Bundle and minify JavaScript files for production using tools like Webpack, Parcel, or esbuild. **Why:** Bundling reduces the number of HTTP requests, and minification reduces file sizes, improving page load times. **Do This:** 1. Install a bundler: "npm install -D webpack webpack-cli" 2. Create a "webpack.config.js" with configurations. """javascript // webpack.config.js const path = require('path'); module.exports = { mode: 'production', // Or 'development' for debugging entry: './js/app.js', // Your main JavaScript file output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js' }, module: { rules: [ { test: /\.js$/, exclude: /node_modules/, use: { loader: 'babel-loader', // Transpile ES6+ to ES5 options: { presets: ['@babel/preset-env'] } } } ] }, optimization: { minimize: true, }, }; """ 3. Integrate the bundling process into your build script: """json // package.json { "scripts": { "build:js": "webpack", "build": "npm run build:css && npm run build:js" } } """ **Don't Do This:** * Deploying unminified or unbundled JS to production. * Including unnecessary libraries or polyfills that increase bundle size. **Anti-Pattern:** Loading all JavaScript files synchronously in the "<head>" of your HTML. This blocks rendering and negatively impacts performance. ### 1.4 Image Optimization **Standard:** Optimize images before deploying to production. Use tools like ImageOptim, TinyPNG, or online optimizers. Consider using modern image formats like WebP where appropriate. **Why:** Optimized images reduce file sizes and improve page load times, contributing to a better user experience. **Do This:** * Use tools to compress images without significant loss of quality. * Use appropriate image formats (JPEG for photos, PNG for graphics with transparency). * Implement responsive images using the "<picture>" element or "srcset" attribute to serve different image sizes based on the device's screen size. """html <img src="image.jpg" alt="My Image" srcset="image-small.jpg 480w, image.jpg 800w" sizes="(max-width: 600px) 480px, 800px"> """ **Don't Do This:** * Uploading large, unoptimized images directly to the server. * Using the same large image for all devices. * Serving images from the same domain as your website assets. Offload image serving to a CDN where possible. ## 2. CI/CD Pipeline Integration ### 2.1 Continuous Integration **Standard:** Integrate your Bootstrap project with a CI/CD pipeline using tools like Jenkins, GitLab CI, GitHub Actions, or CircleCI. **Why:** CI/CD automates the build, test, and deployment processes, ensuring code quality and faster release cycles. **Do This:** 1. Create a CI configuration file (e.g., ".gitlab-ci.yml" for GitLab CI or ".github/workflows/main.yml" for GitHub Actions). 2. Define stages for build, test, and deploy. 3. Configure the pipeline to run tests, linting, and build processes automatically on every code commit or merge request. **Example (GitHub Actions):** """yaml # .github/workflows/main.yml name: CI/CD Pipeline on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Node.js uses: actions/setup-node@v3 with: node-version: '16' # Or your preferred Node.js version - name: Install dependencies run: npm install - name: Run build run: npm run build - name: Run tests (example) run: npm test # Replace with your testing command deploy: needs: build runs-on: ubuntu-latest if: github.ref == 'refs/heads/main' # Only deploy from the main branch steps: - name: Deploy to Production (example) run: | # Add deployment commands here echo "Deploying to Production..." """ **Don't Do This:** * Manually deploying code to production. * Skipping tests or linting in the CI pipeline. * Store secure credentials/keys inside the CI file. Use encrypted variables provided by the CI/CD platform or dedicated secret management tools. ### 2.2 Automated Testing **Standard:** Implement automated tests (unit, integration, and end-to-end) to ensure the quality and stability of your Bootstrap project, especially any custom JS components or styling. **Why:** Automated tests catch bugs early, prevent regressions, and ensure that changes don't break existing functionality. **Do This:** 1. Choose a testing framework (e.g., Jest, Mocha, or Cypress). 2. Write tests for your custom JavaScript components and CSS customizations. 3. Integrate tests into your CI/CD pipeline. **Example (Jest):** """javascript // Example test for a custom Bootstrap component import { MyComponent } from '../js/my-component'; // Adjust path as needed describe('MyComponent', () => { it('should initialize correctly', () => { const component = new MyComponent(); expect(component.initialized).toBe(true); }); it('should handle user input', () => { const component = new MyComponent(); component.handleInput('test input'); expect(component.inputValue).toBe('test input'); }); }); """ **Don't Do This:** * Relying solely on manual testing. * Ignoring failing tests in the CI/CD pipeline. * Do not check sensitive data or API credentials into version control, even within tests. Utilize mocking, environment variables or secure credential storage. ### 2.3 Deployment Strategies **Standard:** Choose an appropriate deployment strategy based on your project's requirements (e.g., blue-green deployment, rolling deployment, or canary deployment). **Why:** Different deployment strategies offer different levels of risk and downtime. Selecting the right strategy minimizes disruption to users. **Do This:** * **Blue-Green Deployment:** Maintain two identical environments (blue and green). Deploy the new version to the inactive environment, test it, and then switch traffic to the new environment. * **Rolling Deployment:** Gradually deploy the new version to a subset of servers, replacing the old version incrementally. * **Canary Deployment:** Deploy the new version to a small subset of users (canary users) to monitor its performance and stability before rolling it out to the entire user base. **Don't Do This:** * Performing large-scale deployments during peak hours. * Lacking a rollback plan in case of deployment failures. ## 3. Production Considerations ### 3.1 Performance Optimization **Standard:** Optimize your Bootstrap project for performance by minimizing HTTP requests, leveraging browser caching, and using a Content Delivery Network (CDN). **Why:** Optimized performance results in faster page load times, improved user experience, and better SEO rankings. **Do This:** * **Minify and compress CSS and JavaScript files:** As covered above in section 1.3. * **Leverage Browser Caching:** Configure your server to set appropriate cache headers for static assets. * **Use a CDN:** Serve static assets (CSS, JavaScript, images) from a CDN to reduce server load and improve download speeds for users across different geographic locations. * **Optimize images:** As covered above in section 1.4. * **Lazy load images and other non-critical assets:** Use the "loading="lazy"" attribute in "<img>" tags and other similar techniques. * Remove unused CSS and JavaScript: Tools like PurgeCSS can help identify and remove unused CSS rules. Similarly, tree shaking in bundlers can remove unused JavaScript code. **Don't Do This:** * Serving large, uncompressed files. * Setting short cache expiration times for static assets. * Overloading your server with requests for static assets. ### 3.2 Security Hardening **Standard:** Implement security best practices to protect your Bootstrap project from vulnerabilities. **Why:** Security hardening protects your application from attacks and data breaches. **Do This:** * **Keep Bootstrap and its dependencies up to date:** Regularly update to the latest versions to patch security vulnerabilities. Use "npm audit" or similar tools to identify and fix vulnerabilities. * **Sanitize user inputs:** Prevent cross-site scripting (XSS) attacks by sanitizing user inputs before displaying them on the page. * **Use HTTPS:** Encrypt all communication between the client and server using HTTPS. * **Implement Content Security Policy (CSP):** Define a CSP to restrict the sources from which the browser can load resources, mitigating XSS attacks. * **Protect against Cross-Site Request Forgery (CSRF) attacks:** Implement CSRF tokens for form submissions. **Don't Do This:** * Using outdated versions of Bootstrap or its dependencies. * Storing sensitive information (e.g., API keys, passwords) in client-side code or version control. * Exposing sensitive data in client-side code. ### 3.3 Monitoring and Logging **Standard:** Implement monitoring and logging to track the performance and health of your Bootstrap project in production. **Why:** Monitoring helps identify and resolve issues quickly, ensuring a stable and reliable application. **Do This:** * **Use a logging framework:** Implement a logging framework (e.g., Winston, Bunyan) to capture application logs. * **Monitor server performance:** Track CPU usage, memory usage, and network traffic. * **Monitor application performance:** Track response times, error rates, and other performance metrics. * **Set up alerts:** Configure alerts to notify you of critical issues, such as high error rates or server downtime. **Don't Do This:** * Ignoring error logs. * Failing to monitor server and application performance. * Logging sensitive information (e.g., passwords, credit card numbers) in plain text. ### 3.4 Accessibility (A11Y) **Standard:** Ensure that your Bootstrap project is accessible to users with disabilities by following accessibility best practices. **Why:** Accessibility ensures that everyone can use your application, regardless of their abilities. **Do This:** * **Use semantic HTML:** Use appropriate HTML elements to structure your content (e.g., "<article>", "<nav>", "<footer>"). * **Provide alternative text for images:** Use the "alt" attribute to provide descriptive text for images. * **Use ARIA attributes:** Use ARIA attributes to enhance the accessibility of dynamic content (e.g., dropdown menus, modal dialogs). * **Ensure sufficient color contrast:** Use tools to check the color contrast of text and backgrounds. * **Provide keyboard navigation:** Ensure that all interactive elements can be accessed and used via keyboard. * **Test with assistive technologies:** Test your application with screen readers and other assistive technologies. **Don't Do This:** * Relying solely on visual cues to convey information. * Using low-contrast colors that are difficult to read. * Creating interactive elements that are not accessible via keyboard. * Overriding default Bootstrap styles and components in a way that breaks accessibility features. ### 3.5 Containerization and Orchestration **Standard:** Containerize your Bootstrap application using Docker and orchestrate it using Kubernetes or Docker Compose. **Why:** Containerization provides consistent environments across development, testing, and production. Orchestration automates deployment, scaling, and management of containers. **Do This:** 1. Create a "Dockerfile" to define the container image. 2. Use Docker Compose for local development and testing. 3. Use Kubernetes for production deployment and scaling. **Example (Dockerfile):** """dockerfile # Use an official Node.js runtime as a parent image FROM node:16 # Set the working directory in the container WORKDIR /app # Copy package.json and package-lock.json to the working directory COPY package*.json ./ # Install application dependencies RUN npm install # Copy the rest of the application code to the working directory COPY . . # Expose the port the app runs on EXPOSE 8080 # Define the command to run the app CMD [ "npm", "start" ] """ **Don't Do This:** * Running applications directly on bare metal servers. * Manually managing container deployments. * Exposing sensitive data into the Docker image itself. Store secret credentials/keys using Docker volumes or dedicated secret management tools. These standards, when followed, will lead to more robust, maintainable, and secure Bootstrap-based applications. Regular review and updates of these standards are recommended to keep abreast of the latest technology and best practices, including adherence to new Bootstrap releases and features.