Project Layout
All Shopify theme files live under theme/, keeping them separate from build tooling at the project root. The Shopify CLI targets this directory with --path theme.
Directory tree
kona-theme/
├── theme/ Shopify theme (deployed to store)
│ ├── assets/ Built output + static assets
│ ├── blocks/ Theme blocks
│ ├── config/
│ │ ├── settings_schema.json Theme settings definitions
│ │ └── settings_data.json Current setting values
│ ├── layout/
│ │ └── theme.liquid Main layout template
│ ├── locales/ 60 locale files (30 languages x 2 types)
│ ├── sections/ Section files
│ ├── snippets/ Reusable partials + icons
│ │ ├── vite-tag.liquid AUTO-GENERATED — don't edit
│ │ ├── importmap.liquid AUTO-GENERATED — don't edit
│ │ └── ...
│ ├── templates/ JSON templates + gift_card.liquid
│ └── frontend/ Source code (NOT deployed)
│ ├── entrypoints/
│ │ ├── theme.js Main JS entry point
│ │ └── theme.css Main CSS entry point
│ ├── islands/ Web Component files
│ ├── lib/ Shared utilities (a11y, events, utils)
│ └── styles/ CSS layers (theme, base, components, utilities)
├── scripts/ Build and utility scripts
├── docs/ This documentation site
├── vite.config.js Vite configuration
├── package.json Dependencies and scripts
├── jsconfig.json Path aliases for editor intellisense
├── eslint.config.js ESLint flat config
└── prettier.config.js Prettier config (Liquid + JS + CSS)Key directories
theme/frontend/
Source code directory. Contains all JavaScript, CSS, and Web Component files that Vite processes. This directory is not deployed to Shopify — only its compiled output in theme/assets/ is.
theme/frontend/entrypoints/
Files here become Vite entry points. entrypoints/theme.js produces assets/theme.js, entrypoints/theme.css produces assets/theme.css.
theme/frontend/islands/
Each .js file defines one Web Component. The filename maps to the custom element tag name. See Islands Architecture.
theme/frontend/lib/
Shared modules imported by islands and entry points:
| Module | Exports |
|---|---|
a11y.js | trapFocus, removeTrapFocus, initDisclosureWidgets |
events.js | Events constants, createEvent, listen |
utils.js | debounce, fetchConfig |
theme/frontend/styles/
CSS files organized into Tailwind v4 layers:
| File | Layer | Purpose |
|---|---|---|
theme.css | — | @theme block with design tokens |
base.css | base | Element resets and defaults |
components.css | components | Reusable component styles |
utilities.css | utilities | Custom utility classes |
Imported by entrypoints/theme.css in cascade order:
@import 'tailwindcss' source('../..');
@import '@/styles/theme.css';
@import '@/styles/base.css' layer(base);
@import '@/styles/components.css' layer(components);
@import '@/styles/utilities.css' layer(utilities);Auto-generated files
Two snippet files are generated by Vite plugins and must not be edited manually:
| File | Generated by | Purpose |
|---|---|---|
vite-tag.liquid | vite-plugin-shopify | Loads JS/CSS from dev server or CDN |
importmap.liquid | vite-plugin-shopify-import-maps | ES module import map |
WARNING
Don't add these to .gitignore. They must be committed because Shopify reads them when rendering pages. They're regenerated on every build and dev server start.
Next steps
- Build Pipeline — How Vite processes these files
- Architecture Overview — The three-layer model
- CSS — Layer system and the
@themerole