Back to Lab

The Developer's Guide to Shopify (When You're Not a Shopify Dev)

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.

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

Dieser Artikel enthält Affiliate-Links. Wenn du dich darüber anmeldest, erhalte ich eine kleine Provision - für dich entstehen keine Mehrkosten. Ich empfehle nur Tools, die ich selbst nutze. (Werbung)