Liquid is a templating language similar to JavaScript template literals; learn 10 common objects instead of all 80 available.
Theme structure separates layouts, templates, sections, and snippets; JSON files control section ordering for merchant drag-and-drop editing.
Liquid has no functions, async operations, or direct API access; use snippets and metafields to pass data instead.
Shopify's learning curve is steep for general developers because documentation targets merchants or dedicated Shopify specialists, not web app builders.
You Know React. You Know APIs. Shopify Still Confuses You.
If you are a developer who has built web apps but never touched Shopify, you are not alone. Shopify's documentation assumes you are either a merchant clicking buttons or a dedicated Shopify developer who lives in Liquid templates. If you are a general-purpose developer who just needs an ecommerce backend, the learning curve feels unnecessarily steep.
I learned Shopify the hard way while building RAXXO's store. Custom sections, digital product delivery, webhook billing integration - all built by a developer who had zero Shopify experience a few weeks ago. Here is everything I wish someone had told me on day one.
Shopify powers millions of stores globally and processes enormous transaction volume. It is not going away. Understanding its architecture is a practical skill regardless of whether you love or hate the platform.
Liquid Basics for Developers Who Know JavaScript
Liquid is Shopify's templating language. If you know JavaScript template literals or Jinja2, you already understand 80% of Liquid. The mental model:
JavaScript
Liquid
`${variable}`
`{{ variable }}`
`if (condition) { }`
`{% if condition %} {% endif %}`
`array.forEach(item => { })`
`{% for item in array %} {% endfor %}`
`value.toUpperCase()`
`{{ value | upcase }}`
`items.filter(i => i.active)`
`{% for item in items %} {% if item.active %} {% endif %} {% endfor %}`
The biggest difference: Liquid has no function definitions. You cannot write reusable functions. Instead, you use snippets (partial templates) and sections (self-contained modules). This feels primitive after working with React components, but it works within Shopify's rendering model.
Liquid also has no async operations, no fetch calls, no direct API access from templates. All data must come through Shopify's object model (product, collection, cart, customer objects) or through metafields. According to Shopify's developer docs, there are over 80 Liquid objects available, but you will use about 10 regularly.
Theme Architecture (The Mental Model)
Shopify themes have a strict file structure. Do not fight it:
theme/
layout/ - Base HTML wrappers (think _app.tsx)
theme.liquid - The main layout, wraps everything
templates/ - Page-type templates (think pages/)
index.json - Homepage template
product.json - Product page template
collection.json - Collection page template
sections/ - Reusable content blocks (think components/)
header.liquid
footer.liquid
hero-banner.liquid
snippets/ - Partial includes (think utils/)
price.liquid
product-card.liquid
assets/ - CSS, JS, images
config/ - Theme settings schema
settings_schema.json
settings_data.json
The key insight: JSON templates (index.json, product.json) define which sections appear on a page and in what order. Sections define the actual content. This separation is what powers the Shopify theme editor, where merchants drag and reorder sections visually.
If you come from Next.js (like I do), think of it this way: layout/ is your root layout, templates/ are your page components, sections/ are your reusable components, and the JSON files are your page configuration.
Custom Sections vs Apps
The first question every developer asks: "Should I build a custom section or a Shopify app?"
Use Case
Custom Section
Shopify App
Custom product layout
Yes
No
Landing page design
Yes
No
Custom checkout flow
No
Yes (Checkout UI Extensions)
Inventory management
No
Yes
Email automation
No
Yes
Custom analytics
No
Yes
Digital product delivery
Partial (display only)
Yes (for automation)
Rule of thumb: if it is visual and front-end, use a custom section. If it needs backend logic, webhooks, or third-party API calls, you need an app or external service. Most customization requests from developers can be solved with custom sections and theme code alone. Apps should be the exception, not the default.
For RAXXO's store, I built custom Liquid sections for product landing pages (Git Dojo and OhNine both have custom section-based landing pages), digital download delivery snippets, and collection layouts. The webhook billing integration with RAXXO Studio runs externally on Vercel, not as a Shopify app.
Webhook Integration
Shopify webhooks are how you get notified of events (orders, product updates, customer actions). For developers used to REST APIs, webhooks feel backwards - instead of polling for data, Shopify pushes data to your endpoint.
Setup is straightforward:
// Register a webhook via Shopify Admin API
POST /admin/api/2025-01/webhooks.json
{
"webhook": {
"topic": "orders/create",
"address": "https://your-app.vercel.app/api/webhooks/shopify",
"format": "json"
}
}
Critical gotchas that will waste your time:
HMAC verification is mandatory. Shopify signs every webhook with your app secret. Verify it or you will accept fraudulent requests. The Shopify docs have a Node.js example that works.
Webhooks are not guaranteed to arrive once. They can be duplicated. Build idempotent handlers.
Respond with 200 within 5 seconds. If your handler takes longer, Shopify retries. Do heavy processing asynchronously.
Test locally with ngrok. Shopify cannot send webhooks to localhost. Use ngrok or Cloudflare Tunnel during development.
Want the complete blueprint?
We're packaging our full production systems, prompt libraries, and automation configs into premium guides. Stay tuned at raxxo.shop
The most common webhook integration failures come from missing HMAC verification, timeout issues, and not handling duplicate deliveries. Address all three from the start.
Shopify CLI
The Shopify CLI is how you develop themes locally. Install it with npm:
npm install -g @shopify/cli @shopify/theme
Key commands you will actually use:
# Start local development with hot reload
shopify theme dev --store your-store.myshopify.com
# Push theme changes to store
shopify theme push
# Pull current theme to local
shopify theme pull
# List available themes
shopify theme list
shopify theme dev starts a local proxy that hot-reloads your Liquid changes. It is slow compared to Next.js dev server (2-4 second reload vs instant HMR), but it works. Do not expect Vite-speed development. Shopify's architecture requires server-side rendering for every change.
Pro tip: use Claude Code for Liquid development. It handles Liquid syntax well, understands Shopify's object model, and can generate complete sections including the schema block. This is how I built all of RAXXO's custom sections - describe what I need, Claude Code generates the Liquid, I review and push.
Admin API (When You Need Backend Access)
The Shopify Admin API gives you programmatic access to everything: products, orders, customers, inventory, metafields. Two flavors: REST and GraphQL. Use GraphQL. It is more efficient for complex queries and Shopify is clearly investing more in the GraphQL API.
// Example: Fetch products with metafields via GraphQL
const query = `{
products(first: 10) {
edges {
node {
title
handle
metafields(first: 5) {
edges {
node {
key
value
namespace
}
}
}
}
}
}
}`;
const response = await fetch(
`https://your-store.myshopify.com/admin/api/2025-01/graphql.json`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Shopify-Access-Token': process.env.SHOPIFY_ACCESS_TOKEN
},
body: JSON.stringify({ query })
}
);
Rate limits: REST API allows 40 requests per second. GraphQL uses a cost-based system where simple queries cost 1 point and complex queries cost more, with a 2,000-point budget per second. In practice, you will rarely hit limits unless you are doing bulk operations. For bulk data, use Shopify's Bulk Operations API instead of paginating through thousands of records.
When to Use Shopify vs Build Your Own
Scenario
Use Shopify
Build Custom
Physical product store
Almost always
Rarely
Digital product store
Yes (with workarounds)
If products are complex (SaaS, subscriptions)
Marketplace
No
Yes
Subscription service
Partial (needs app)
Better control with custom
Simple store with < 100 products
Yes
Waste of time
Complex UX requirements
Possible but painful
Better experience
RAXXO uses both: Shopify for the merch store (91 physical products + digital products like Git Dojo and OhNine) and a custom Next.js app for the SaaS (RAXXO Studio). Shopify handles checkout, payment processing, and order management. The SaaS handles everything Shopify cannot: real-time AI generation, user dashboards, usage tracking.
For developers deciding between the two: if your primary value proposition is a physical or simple digital product, use Shopify. You will spend 90% less time on payment processing, tax compliance, and order management. If ya RAXXO product IS the software (not just sold through software), build custom.
Real Examples from RAXXO's Store
Custom landing page sections: Git Dojo's product page uses 5 custom Liquid sections (hero, features grid, pricing comparison, FAQ, CTA). Each section has a schema block that makes it editable in Shopify's theme editor. Total development time: about 4 hours with Claude Code.
Digital download delivery: A custom snippet (digital-downloads-email.liquid) checks order tags and product handles to include download links in order confirmation emails. Files are hosted on Vercel (public/downloads/), not on Shopify. Simple, reliable, no app required.
Webhook billing: When someone subscribes to RAXXO Studio through Shopify, a webhook fires to the Vercel-hosted SaaS, which provisions the account and sets the subscription tier. This bridges Shopify's commerce with the custom app's functionality.
FAQ
Do I need to learn Liquid or can I use React/Next.js with Shopify?
For storefront customization, you need Liquid. Shopify's Hydrogen framework lets you build headless storefronts with React, but it is significantly more complex and you lose the theme editor. For most stores, learning basic Liquid (which takes 1-2 days for an experienced developer) is the faster path.
How long does it take a developer to build a custom Shopify theme?
Starting from an existing theme (like Dawn, Shopify's default), expect 20-40 hours for meaningful customization. Building from scratch is 80-120 hours. Using Claude Code for Liquid generation cuts both estimates by roughly 40-50%. Most developers should modify Dawn rather than starting from zero.
Is the Shopify CLI reliable for local development?
It works but it is slow. Expect 2-4 second reload times. The initial connection to your store can be flaky. My recommendation: use shopify theme dev for testing and shopify theme push for deploying confirmed changes. Do not rely on the local dev server for pixel-perfect preview - always verify in the actual Shopify preview.
Should I use Shopify apps or build custom integrations?
For standard needs (email marketing, reviews, upsells), use established apps. For custom business logic specific to your store, build external integrations via webhooks and the Admin API. Apps add monthly costs and can slow your store. Custom integrations have higher upfront effort but zero ongoing cost.
What is the best resource for learning Shopify development quickly?
Shopify's official developer documentation is actually good (unlike many platforms). Start with the "Themes" section, read about Liquid objects, then look at Dawn's source code on GitHub. Dawn is well-commented and demonstrates all standard patterns. Skip YouTube tutorials - most are outdated within months due to Shopify's rapid release cycle.
This article contains affiliate links. If you sign up through them, I earn a small commission at no extra cost to you.
This article contains affiliate links. If you sign up through them, I may earn a small commission at no extra cost to you. (Ad)
Top comments (0)