--- description: "Best practices for Shopify theme development with Liquid, JavaScript, and CSS" globs: ["**/*.liquid", "assets/**/*.js", "assets/**/*.css", "sections/**/*.liquid", "snippets/**/*.liquid", "templates/**/*.liquid"] alwaysApply: false ---

Shopify Theme Development Best Practices

Project Structure

• Adopt a clear **directory structure**, e.g., `sections`, `snippets`, `templates`, `assets`.
• Organize **generic modules** (like JavaScript functionalities) into separate files.
• Keep **Liquid files** concise and focused on single responsibilities, avoiding monolithic files.
• Organize templates and sections by **page or functionality**.
• Implement proper **internationalization (i18n)** file management.
• Utilize **SCSS/CSS Modules** for style organization to prevent global pollution.

Liquid Templating

• Prefer the `render` tag over `include`.
• Limit **database queries** within loops to avoid N+1 issues.
• Use **filters** judiciously, especially complex computational ones.
• Leverage Liquid's **caching mechanisms** to reduce redundant calculations.
• Avoid complex **logic handling** directly in Liquid; move intricate logic to JavaScript.
• Use `assign` and `capture` to define and reuse variables effectively.

JavaScript Development

• Modularize JS, using **ES Modules** for imports and exports.
• Follow modern JavaScript **best practices**, such as `const`/`let`, arrow functions, etc.
• Avoid direct **DOM manipulation**; prioritize event delegation.
• Optimize **JavaScript performance** to reduce repaints and reflows.
• Consider using **Webpack/Rollup** for bundling and code optimization.
• Write clear **comments** and **JSDoc**.

CSS/SCSS Styling

• Adhere to naming conventions like **BEM, OOCSS, or Utility-First CSS**.
• Optimize **CSS selectors** to improve rendering performance.
• Use **CSS variables** to manage theme configurations like colors and fonts.
• Implement **responsive design** to ensure consistent theme appearance across devices.
• Minimize **CSS file size** by removing unused styles.
• Make good use of **SCSS mixins** and **functions**.

Sections and Blocks

• Utilize Section **Schema** to define configurable options.
• Maintain **section independence and reusability**.
• Provide clear **presets** for sections.
• Use **Blocks** appropriately to enhance section flexibility.
• Ensure sections provide a good user experience in the **Shopify Customizer**.
• Avoid hardcoding content within sections; use Schema configurations whenever possible.

Performance Optimization

• Optimize **image loading** by using Shopify's CDN and the `image_url` filter.
• Minify **JavaScript and CSS files**.
• Leverage **browser caching**.
• Reduce the number of **HTTP requests**.
• Consider **lazy loading**.
• Monitor **theme performance** using Google Lighthouse and Shopify Theme Check.

Accessibility (A11y)

• Ensure all interactive elements are **keyboard accessible**.
• Provide meaningful **`alt` text** for images.
• Use correct **HTML semantic tags**.
• Consider **color contrast**.
• Implement clear **focus states**.
• Use **ARIA attributes** to enhance the accessibility of complex components.

Maintenance and Scalability

• Write clear **code comments** and documentation.
• Follow **naming conventions** to maintain code consistency.
• Regularly **test** theme functionalities.
• Ensure compatibility across different **browsers and devices**.
• Consider future **extensibility**, avoiding tight coupling.
• Use **Shopify CLI** for local development and deployment.

Quality and Testing

• Use **Shopify Theme Check** for static code analysis.
• Write **unit tests** (where applicable).
• Conduct thorough **end-to-end testing**.
• Test in various environments (local, development store, production store).
• Focus on **compatibility testing** (browsers, devices, Shopify versions).
• Test **error handling** and edge cases.