Theme Envy is a feature-rich, performance-optimized Shopify theme development environment. With the extended liquid tools, you can move beyond liquid snippets with repeatable code. Theme Envy compiles everything for you using a combination of custom build processes, Node, Webpack, and Tailwind.
- Get to work:
Usetheme-envyCLI commands to build, serve, initialize, add new feature structure, and much more, without touching your package.json. ⚡ Bonus: Theme Envy's build and watch processes are super fast. ⚡ - Stay organized:
Put related files together in their own feature subdirectories instead of the default Shopify theme structure. You can also add subdirectories within the default Shopify/snippetsand/sectionsfolders to group files. - Repeat yourself:
Break up code into smaller, reusable pieces with Theme Envy's extended liquid partials and schema files. - Integrate with Ease:
Manage app and feature implementation using Theme Envy'shooksandinstallssystem. - Code in Style:
Nest custom styling or apply classes with PostCSS and Tailwind built in. - Stay Consistent:
Customize new feature starter files with your own markup and settings to establish consistency in your theme code base. - Customize your Configuration:
Add and update values in yourtheme.config.jsfor direct reference in liquid files using the{% theme %}tag - Optimize Performance:
Automatically lazy-load custom JS elements only when they are present on the page and use Webpack dynamic imports to conditionally load assets. - Build for Production:
Automatically prettify liquid and minify javascript on production builds.
Table of Contents
- Installation
- Getting Started
- Theme Directory Structure
- CLI
- Build Tools
- Theme.config.js
- Tailwind
- Webpack
- Contributing
- License
Use NPM to install Theme Envy.
npm install @softlimit/theme-envy --save-devGet started by running the following command and answering the prompts:
npx theme-envy initNote
During theinitcommand a new "Feature" is added to your project calledtheme-envyinsrc/theme-envy/features/theme-envy. This feature will add a snippet and{% render 'theme-envy' %}to the end of your<head>tag inlayout/theme.liquidduring project build. This handles all the Theme Envy JS and CSS.
You are now ready to start developing! Get started with this simple command in your terminal
npx theme-envy devThe directories are Shopify standard directories except for theme-envy.
/
└── assets/
└── config/
└── layout/
└── locales/
└── sections/
└── snippets/
└── templates/
└── customers/
└── theme-envy/
└── elements/ # for Custom Elements/Web Components
└── features/ # individual directories of discrete features
└── partials/ # small .liquid files that are reusable/inserted across the theme
└── schema/ # .js files for sharing bits of section/config schema across the themeNote
Precede all commands withnpx theme-envy
Usage: theme-envy [options] [command]
Theme Envy CLI Tools
Options:
-h, --help display help for command
Commands:
build [options] [env] Build Shopify theme
clean Empty output directory
convert [options] [source] Convert an existing Shopify theme to Theme Envy directory structure
dev Start development process and sync with Shopify using the Shopify CLI
find-orphans Find unused snippets, partials, and assets in your Shopify theme
init [options] [source] Initialize a new Shopify theme project with Theme Envy directory structure
new <type> <name> [include] Create new Feature or Element from starter files
pull-json Pull json template, section, and settings_data files from theme using Shopify CLI
tree [options] [filepaths] Display the dependency tree for a .liquid file
help [command] display help for command
Theme Envy is optimized for using Web Components. You can initialize a new Web Component using utils/starter-element.js in your project with this command in your terminal:
npx theme-envy new element <your-element>Your element file must have the same name as your new CustomElement (Web Component). Theme Envy will only load the asset(s) for your-element if element is present in the DOM.
Warning
To take advantage of Theme Envy's smart loading of elements they must be inside anelementsdirectory
You can also setup an element as a subdirectory of theme-envy/elements by using an index.js file (theme-envy/elements/your-element/index.js). In this case your subdirectory must have the same name as your Web Component.
Theme Envy "Features" are bigger pieces/sections of your site. Any JS/CSS assets associated with a feature will be loaded as part of the main theme-envy.js file on all templates in your theme.
Note
Features are subdirectories ofsrc/theme-envy/features.
/
└── theme-envy/features
└── your-feature/
└── config/ # .js files concatenated and added to settings_schema.json
└── partials/ # .liquid files that are referenced using Theme Envy {% partial 'file-name' %} tag
└── schema/ # .js files with module.exports to be injected into section files, or referenced with ThemeRequire()
└── scripts/ # .js files to be imported into index.js
└── sections/ # .liquid files only, included in build automatically
└── snippets/ # .liquid files only, included in build automatically
└── styles/ # contains any .css files, must be imported into index.js
└── critical.css # optional file that adds render blocking, sitewide CSS
└── index.js # is concatenated and loaded sitewide
└── install.js # defines where to inject code into hooksHooks are places in the theme code where Features and Elements can insert code during build. This allows us to keep integrations discrete and easily undoable. To define a hook in the theme, we only need to add a hook tag like so:
{% hook 'head-end' %}We can then reference this hook's location with an install.js file in a feature or element.
module.exports = [
{
hook: 'head-end',
content: "{% render 'custom-snippet' %}",
priority: 0-100 // optional, 50 is default
}
]During the build, all code for the head-end hook will be collected, sorted by priority (where 0 is highest in the code), and will replace the {% hook 'head-end' %} tag.
In "Features" you may write render blocking CSS that you want to load site wide in a critical.css file in the Feature's directory. The critical.css files are concatenated with the Tailwind Stylesheet (when enabled), so that they are render blocking, loaded once, and then cached for subsequent page loads.
We were frustrated by how difficult it is to share smaller pieces of Shopify Section schema across sections. Theme Envy includes a couple of tools to make this easier.
Use this syntax in section .liquid files in place of the normal {% schema %}{% endschema %} tags:
{% schema 'schema-your-section.js' %}Note
Don't worry about relative/absolute paths here, Theme Envy will find your uniquely named schema js file within your project.
When managing your section as a Feature we recommend putting all of your schema files in that feature's schema subdirectory. Schema that is shared across multiple features/sections should go in src/theme-envy/schema
Warning
All schema files must be within aschemadirectory
By using the syntax
{% partial '_file-name' %}the contents of the liquid file named _file-name.liquid are inserted directly into the output file. Our practice is to name these files with a leading _, but it is not required.
Warning
All partial files must be within apartialsdirectory
We can use this markup to access properties of the theme.config.js file within liquid files. This is especially helpful for when you have to access a breakpoint value within your markup.
{% theme 'breakpoints.md' %} // defined in theme.config.jsAfter initializing your Theme Envy project, you will find a theme.config.js file in your project root. This is where we manage all of the Theme Envy build options.
module.exports = {
entry: {
// Add entrypoints (Webpack) here
// main: './src/scripts/main.js',
},
store: 'sl-dev-testing.myshopify.com',
themePath: 'src', // directory for theme source files
outputPath: 'dist', // directory for build output
// tailwind: true, // set to false to disable Tailwind
breakpoints: {
sm: '640px',
// => @media (min-width: 640px) { ... }
md: '768px',
// => @media (min-width: 768px) { ... }
lg: '1024px',
// => @media (min-width: 1024px) { ... }
xl: '1280px',
// => @media (min-width: 1280px) { ... }
'2xl': '1536px'
// => @media (min-width: 1536px) { ... }
}
}Tailwind is enabled automatically. It can be disabled in theme.config.js, and customized in tailwind.config.js
Webpack is used to bundle and manage JS and CSS. By default, the only entry point is Theme Envy which will handle all elements and features. Any additional scripts or stylesheets can be added to the entry in theme.config.js.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.