{"filename":"shopify-theme-dev-liquid.mdc","content":"---\ndescription: \"Best practices for Shopify theme development with Liquid, JavaScript, and CSS\"\nglobs: [\"**/*.liquid\", \"assets/**/*.js\", \"assets/**/*.css\", \"sections/**/*.liquid\", \"snippets/**/*.liquid\", \"templates/**/*.liquid\"]\nalwaysApply: false\n---\n# Shopify Theme Development Best Practices\n\n## Project Structure\n- Adopt a clear **directory structure**, e.g., `sections`, `snippets`, `templates`, `assets`.\n- Organize **generic modules** (like JavaScript functionalities) into separate files.\n- Keep **Liquid files** concise and focused on single responsibilities, avoiding monolithic files.\n- Organize templates and sections by **page or functionality**.\n- Implement proper **internationalization (i18n)** file management.\n- Utilize **SCSS/CSS Modules** for style organization to prevent global pollution.\n\n## Liquid Templating\n- Prefer the `render` tag over `include`.\n- Limit **database queries** within loops to avoid N+1 issues.\n- Use **filters** judiciously, especially complex computational ones.\n- Leverage Liquid's **caching mechanisms** to reduce redundant calculations.\n- Avoid complex **logic handling** directly in Liquid; move intricate logic to JavaScript.\n- Use `assign` and `capture` to define and reuse variables effectively.\n\n## JavaScript Development\n- Modularize JS, using **ES Modules** for imports and exports.\n- Follow modern JavaScript **best practices**, such as `const`/`let`, arrow functions, etc.\n- Avoid direct **DOM manipulation**; prioritize event delegation.\n- Optimize **JavaScript performance** to reduce repaints and reflows.\n- Consider using **Webpack/Rollup** for bundling and code optimization.\n- Write clear **comments** and **JSDoc**.\n\n## CSS/SCSS Styling\n- Adhere to naming conventions like **BEM, OOCSS, or Utility-First CSS**.\n- Optimize **CSS selectors** to improve rendering performance.\n- Use **CSS variables** to manage theme configurations like colors and fonts.\n- Implement **responsive design** to ensure consistent theme appearance across devices.\n- Minimize **CSS file size** by removing unused styles.\n- Make good use of **SCSS mixins** and **functions**.\n\n## Sections and Blocks\n- Utilize Section **Schema** to define configurable options.\n- Maintain **section independence and reusability**.\n- Provide clear **presets** for sections.\n- Use **Blocks** appropriately to enhance section flexibility.\n- Ensure sections provide a good user experience in the **Shopify Customizer**.\n- Avoid hardcoding content within sections; use Schema configurations whenever possible.\n\n## Performance Optimization\n- Optimize **image loading** by using Shopify's CDN and the `image_url` filter.\n- Minify **JavaScript and CSS files**.\n- Leverage **browser caching**.\n- Reduce the number of **HTTP requests**.\n- Consider **lazy loading**.\n- Monitor **theme performance** using Google Lighthouse and Shopify Theme Check.\n\n## Accessibility (A11y)\n- Ensure all interactive elements are **keyboard accessible**.\n- Provide meaningful **`alt` text** for images.\n- Use correct **HTML semantic tags**.\n- Consider **color contrast**.\n- Implement clear **focus states**.\n- Use **ARIA attributes** to enhance the accessibility of complex components.\n\n## Maintenance and Scalability\n- Write clear **code comments** and documentation.\n- Follow **naming conventions** to maintain code consistency.\n- Regularly **test** theme functionalities.\n- Ensure compatibility across different **browsers and devices**.\n- Consider future **extensibility**, avoiding tight coupling.\n- Use **Shopify CLI** for local development and deployment.\n\n## Quality and Testing\n- Use **Shopify Theme Check** for static code analysis.\n- Write **unit tests** (where applicable).\n- Conduct thorough **end-to-end testing**.\n- Test in various environments (local, development store, production store).\n- Focus on **compatibility testing** (browsers, devices, Shopify versions).\n- Test **error handling** and edge cases.\n"}