Theme Structure

The project structure generated by Nx-Shopify differs in a great manner with what you are used to with themekit. Despite it was built with ease-of-use in mind, here is an explanation of the main differences with a plain themekit project.

This is the general project structure you will find in a Nx-Shopify theme.

apps/my-theme/src
├── assets
├── config
├── core
├── environments
├── locales
├── theme
│   ├── layout
│   ├── sections
│   ├── snippets
│   └── templates
└── main.ts

Assets#

All the assets content will be placed inside this directory. You can organize your assets using as many subdirectories as you want (can be nested).

apps/my-theme/src/assets
├── favicon
├── fonts
├── images
│   └── example.png
└── svg
    └── example.svg

The theme build output will flatten all the files into a single assets directory. The above example will generate the following output:

dist/apps/my-theme/assets
├── (... css files)
├── (... js files)
├── example.png
├── example.svg
└── ...

warning

Knowing this, you should take special care on not using the exact same name for more than one file inside the src/assets directory or subdirectories as only one of them will go through the build process.

Using assets#

As mentioned above, it does not matter how you organize your assets files at source code level, the output result for any asset will always be assets/<asset name>. So, in order to use assets in your theme code you should not take into account it's subdirectories.

For example:

Given this images:

apps/my-theme/src/assets
└── images
    ├── example.png
    └── product-page
        └── pdp-banner.png

Then, in your liquid code:

// ❌ Bad
<img src="{{ 'images/example.png' | asset_url }}" />
<img src="{{ 'images/product-page/pdp-banner.png' | asset_url }}" />

// ✅ Good
<img src="{{ 'example.png' | asset_url }}" />
<img src="{{ 'pdp-banner.png' | asset_url }}" />

Core#

apps/my-theme/src/core
├── ...
├── theme-bootstrap.ts
├── theme-context.ts
├── theme-module.ts
└── ...

The core directory contains essential TypeScript files related to how the theme is initialized once is loaded into a web browser.

tip

Learn more about the theme is initialized in the Theme Bootstrap Process doc.

Environments#

apps/my-theme/src/environments
├── environment.prod.ts
└── environment.ts

All the TypeScript environment files will be placed in this directory.

tip

Learn more about working with environments in the Environments Guide.

Theme#

The src/theme directory contains all the theme blocks separated in their respective subdirectory

apps/my-theme/src/theme
├── layout
├── sections
├── snippets
└── templates

Each block (layout, template, section or snippet) is composed by 3 files:

Liquid file (.liquid)
TypeScript file (.ts)
Styles file (.sass)

You can have any amount of blocks organized in as much subdirectories as you need in order to have a structured code base that suits your needs.

You could, for example, organize your snippets according to where they are designed to be used:

apps/my-theme/src/theme/snippets
├── index
│   ├── hero-slider
│   │   ├── hero-slider.liquid
│   │   ├── hero-slider.snippet.scss
│   │   └── hero-slider.snippet.ts
│   └── special-promo-news
│       ├── special-promo-news.liquid
│       ├── special-promo-news.snippet.scss
│       └── special-promo-news.snippet.ts
├── index.ts
├── product
│   ├── product-gallery
│   │   ├── product-gallery.liquid
│   │   ├── product-gallery.snippet.scss
│   │   └── product-gallery.snippet.ts
│   └── product-recommendations
│       ├── product-recommendations.liquid
│       ├── product-recommendations.snippet.scss
│       └── product-recommendations.snippet.ts
└── shared
    ├── message
    │   ├── message-body
    │   │   ├── message-body.liquid
    │   │   ├── message-body.scss
    │   │   └── message-body.ts
    │   ├── message-box
    │   │   ├── message-box.liquid
    │   │   ├── message-box-section
    │   │   │   ├── message-box-section.liquid
    │   │   │   ├── message-box-section.snippet.scss
    │   │   │   └── message-box-section.snippet.ts
    │   │   ├── message-box.snippet.scss
    │   │   └── message-box.snippet.ts
    │   ├── message.liquid
    │   ├── message.snippet.scss
    │   └── message.snippet.ts
    ├── promo-banner
    │   ├── promo-banner.liquid
    │   ├── promo-banner.snippet.scss
    │   └── promo-banner.snippet.ts
    └── sidebar-cart
        ├── sidebar-cart.liquid
        ├── sidebar-cart.snippet.scss
        └── sidebar-cart.snippet.ts

You can leverage from our built-in Code Generators to scaffold the theme structure you desire. The code generators will take care of verifying that no duplicated blocks will be created even if you try to do it in different subfolders.

important

Do not forget that a theme block name should be unique in it's block type. You can perfectly have a snippet and a section both called message-box at the same time.