DEV Community

Cover image for Rendering Shopify Liquid Code Locally with VS Code
Florian Zeba
Florian Zeba

Posted on • Originally published at fzeba.com

Rendering Shopify Liquid Code Locally with VS Code

#shopify #liquidcode #vscode #html

This guide explains how to set up a local development environment to render and test Shopify Liquid templates using VS Code.

What I like to do if I test code or software with which I usually do not interact with (in this case ruby) is to create a docker container (or a github codespace) with the necessary tools and dependencies. This way I can keep my local machine clean and I can easily share the environment with others.

1. Install Prerequisites

Ensure you have the following installed:

a. Ruby

Shopify's Liquid engine runs on Ruby. Install Ruby using:

  • macOS: brew install ruby
  • Windows: RubyInstaller
  • Linux: sudo apt install ruby

Verify installation:

ruby -v
Enter fullscreen mode Exit fullscreen mode

b. Bundler

Install Bundler for Ruby gem management:

gem install bundler
Enter fullscreen mode Exit fullscreen mode

c. Node.js

Some front-end assets may rely on Node.js:

node -v
npm -v
Enter fullscreen mode Exit fullscreen mode

Tip: In a Github-Codespace you can use the pre-installed ruby and node.js versions. You just need to install the bundler gem. (see image below)

Ruby Requirements

2. Set Up Your Project Folder

  1. Create a project folder: 
   mkdir shopify-liquid-local && cd shopify-liquid-local
Enter fullscreen mode Exit fullscreen mode
  1. Initialize Ruby environment: 
   bundler init
Enter fullscreen mode Exit fullscreen mode
  1. Edit Gemfile to include: 
   source "https://rubygems.org"
   gem "liquid"
Enter fullscreen mode Exit fullscreen mode
  1. Install dependencies: 
   bundle install
Enter fullscreen mode Exit fullscreen mode

3. Create a Basic Liquid Template

Create index.liquid:

<!DOCTYPE html>
<html>
<head>
  <title>{{ title }}</title>
</head>
<body>
  <h1>Welcome to {{ site_name }}</h1>
  {% if products.size > 0 %}
    <ul>
      {% for product in products %}
        <li>{{ product.name }} - {{ product.price }}</li>
      {% endfor %}
    </ul>
  {% else %}
    <p>No products available.</p>
  {% endif %}
</body>
</html>
Enter fullscreen mode Exit fullscreen mode

Tip: I recommend the extension "Liquid" from panoply for syntax highlighting and autocompletion and the extension "Shopify Liquid" from Shopify for formatting.

Tip: To get proper formatting click the right mouse button and select "Format Document With..." or use the shortcut "Shift+Alt+F". Select the "Shopify Liquid" formatter. This results in having the "Liquid" extension for syntax highlighting and autocompletion and the "Shopify Liquid" extension for formatting. (see images below)

Liquid Extension

Shopify Liquid Extension

Formatting Option

Shopify Formatting

4. Write a Ruby Script to Render Liquid

Create render.rb:

require "liquid"

# Load the Liquid template
template_file = File.read("index.liquid")
template = Liquid::Template.parse(template_file)

# Define data
data = {
  "title" => "Shopify Local Testing",
  "site_name" => "My Local Shop",
  "products" => [
    { "name" => "T-Shirt", "price" => "$20" },
    { "name" => "Jeans", "price" => "$40" }
  ]
}

# Render template and save to HTML
output = template.render(data)
File.open("output.html", "w") { |file| file.write(output) }

puts "Template rendered to output.html"
Enter fullscreen mode Exit fullscreen mode

5. Run the Script

Execute:

ruby render.rb
Enter fullscreen mode Exit fullscreen mode

Open output.html in your browser.

Output

6. Optional: Set Up Live Preview

a. Option 1: Install HTTP Server with python OR node.js

  • Python: 
  python -m http.server
Enter fullscreen mode Exit fullscreen mode

Visit http://localhost:8000.

  • Node.js: 
  npm install -g http-server
  http-server
Enter fullscreen mode Exit fullscreen mode

b. Option2: VS Code Live Server Extension

  1. Install the Live Server extension.
  2. Right-click output.html and select Open with Live Server.

7. Optional: Enhance with Shopify Features

a. Install Shopify CLI

  1. Install Shopify CLI (Guide).
  2. Log in: 
   shopify login
Enter fullscreen mode Exit fullscreen mode

b. Sync Changes Locally

Pull or create themes:

shopify theme pull --store your-store-name.myshopify.com
Enter fullscreen mode Exit fullscreen mode

Run local preview:

shopify theme dev
Enter fullscreen mode Exit fullscreen mode

8. Optional: Debugging and Testing

a. VS Code Extensions

b. Debug Liquid Output

Use:

{{ variable | json }}
Enter fullscreen mode Exit fullscreen mode

c. Ruby Debugging

Modify render.rb to print rendered output:

puts template.render(data)
Enter fullscreen mode Exit fullscreen mode

9. Advanced Setup

a. Asset Compilation

Use Webpack or Gulp to compile assets (CSS/JS).

b. Shopify Theme Check

Install Shopify Theme Check for linting:

gem install theme-check
theme-check
Enter fullscreen mode Exit fullscreen mode

By following this guide, you can efficiently render and test Liquid templates locally.

The Link to the Github repository can be found here: Shopify Liquid Local on Github.

> Read this article and more on fzeba.com.

Top comments (1)

Collapse
 
stackedboost profile image
Peter Hallander •

Nice workflow for local Liquid rendering! Having a fast local feedback loop makes theme development so much more enjoyable.

Once you're happy with a theme build, two things consistently move the needle on the actual storefront experience:

  • Navigation speed: I built Prefetch (apps.shopify.com/prefetch) which preloads pages when customers hover over links. Super lightweight addition to any theme and the speed improvement is immediately noticeable.
  • Product image consistency: Eye Catching (apps.shopify.com/beautiful-brands) standardizes product image backgrounds and adds overlays/badges — saves a ton of time compared to manually fixing images in Liquid templates.

(I'm the developer of both — sharing in case it's useful for theme devs here.) The VS Code local setup you described is exactly the kind of environment where you'd be iterating on these kinds of enhancements!