Editing your theme’s code (Aqua files)

Most merchants do everything they need from the visual customizer. But when you need a custom snippet, a new section type, or to tweak how a template renders, the code editor lets you work directly in your theme’s Aqua files.

When to use the code editor vs. the customizer

Task	Use
Change section settings, add blocks, reorder	Customizer
Tweak colors, fonts, paddings	Customizer (theme settings)
Add a new section type with its own schema	Code editor
Write a new snippet to share logic	Code editor
Add custom CSS or JS to an asset file	Code editor
Modify a template’s JSON layout	Code editor
Translate strings into a new locale	Code editor

Folder structure

Every Aqua theme follows the same directory layout:

• layout/ — the outer wrapper rendered around every template (typically theme.aqua).
• templates/ — JSON files describing each page type: index.json, product.json, collection.json, etc.
• sections/ — reusable sections with their schema and markup.
• blocks/ — reusable blocks usable inside sections.
• snippets/ — small reusable Aqua snippets, included via {% render 'name' %}.
• assets/ — CSS, JS, images, fonts. Referenced via {{ 'file.css' | asset_url }}.
• config/ — settings_schema.json (theme settings catalog), settings_data.json (current values).
• locales/ — per-language translation files (en.default.json, fr.json, etc.).

Opening the code editor

From your admin, navigate to Online store → Themes → Edit code. The editor opens with a file browser on the left and the Monaco-based editor on the right. Aqua files get Liquid-aware syntax highlighting; CSS, JS and JSON get their native modes.

Common tasks

Add a new section

1. Create sections/my-section.aqua.
2. Define a {% schema %} block with settings and presets.
3. Write the Aqua markup above the schema.
4. Save — the section is now available in the customizer’s “Add section” catalog.

Add a new snippet

1. Create snippets/badge.aqua.
2. Use the parameters passed in via render: {% render 'badge', text: 'NEW' %}.
3. Snippets do not have their own schema — they are pure rendering helpers.

Upload an asset

Drop the file into the assets/ folder via the browser. Reference it from any Aqua file with {{ 'file.css' | asset_url | stylesheet_tag }} or {{ 'file.js' | asset_url | script_tag }}.

Edit a template

Templates are JSON: a section ordering plus the settings for each section instance. Editing them by hand is rarely needed — the customizer writes here on every save — but you might want to seed a new section instance or version-control template diffs.

Saving and cache invalidation

When you save a file, LMS automatically invalidates the relevant caches:

• The theme file cache for the changed path.
• The compiled-template cache for any template that depends on the file.
• The page HTML cache for affected templates.

You should see the change in the storefront on the next request — no manual purge needed.

Theme settings vs. file edits

Most appearance tweaks (logo, colors, fonts) live in config/settings_data.json and should be changed via the customizer’s Theme settings panel, not the code editor. Editing the JSON file by hand bypasses validation and can break the customizer.

Safety net: duplicate before risky edits

From Themes, click Duplicate on the active theme before making destructive changes. If something breaks, swap the active theme back to the duplicate while you fix the working copy.

FAQ

Can I rename a file in the code editor?

Yes. Use the file’s context menu in the browser pane. References elsewhere (e.g. {% render 'old-name' %}) need to be updated manually.

Where does the editor save my changes?

Directly to the theme’s files in your store’s theme storage. There’s no “draft” mode in the code editor itself — duplicate the theme if you want one.

Why doesn’t my new section appear in the customizer?

The section’s {% schema %} block must include a presets array. Sections without presets are renderable but not addable from the customizer. Add at least one preset and reload.

What’s the difference between a snippet and a block?

A snippet is a reusable Aqua include — pure rendering, no schema, no merchant configuration. A block is a configurable child of a section with its own schema and settings.

Can I upload a large image as an asset?

Yes — the editor accepts files up to several megabytes. For very large images, use the media library instead and reference its CDN URL.

Will edits affect my live storefront immediately?

Yes. The code editor writes to the active theme. If you need a review step, duplicate first, edit the duplicate, then publish it.