Home › All rules › Community › Shopify Theme Dev Liquid Cursor Rules

Shopify Theme Dev Liquid Cursor Rules

Best practices for Shopify theme development with Liquid, JavaScript, and CSS

CursorAny stackCommunity (CC0)

How to use

Save this as .cursor/rules/shopify-theme-dev-liquid.mdc in your project, commit it, and Cursor will load it. Review it first: community files can be opinionated or out of date.

Note: Review and test before use. Provided as is, without warranty. See Terms.

---
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.