# Editing your theme's code (Aqua files)

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

TaskUse Change section settings, add blocks, reorderCustomizer Tweak colors,
fonts, paddingsCustomizer (theme settings) Add a new section type with its own
schemaCode editor Write a new snippet to share logicCode editor Add custom CSS
or JS to an asset fileCode editor Modify a template’s JSON layoutCode editor
Translate strings into a new localeCode 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.