@softlimit/theme-envy

v0.1.12-alpha

Published

a month ago

Softlimit Shopify Theme Development Environment

Downloads

0High
0Medium
0Low

calebsoftlimit

oliviasoftlimit

💚 Theme Envy for Shopify Themes 💚

The lean, mean development machine for your Shopify themes

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.

Theme Envy Features

Get to work:
Use theme-envy CLI 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 /snippets and /sections folders 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's hooks and installs system.
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 your theme.config.js for 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

Use NPM to install Theme Envy.

npm install @softlimit/theme-envy --save-dev

Getting Started

Get started by running the following command and answering the prompts:

npx theme-envy init

Note
During the init command a new "Feature" is added to your project called theme-envy in src/theme-envy/features/theme-envy. This feature will add a snippet and {% render 'theme-envy' %} to the end of your <head> tag in layout/theme.liquid during 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 dev

Theme Directory Structure

The 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 theme

CLI

Note
Precede all commands with npx 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
  deploy                       Deploy your theme to Shopify by copying the live theme then pushing changes to codebase on top of it
  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

Build Tools

Elements

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 an elements directory

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.

Features

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 of src/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 hooks

Hooks/installs

Hooks 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.

Critical CSS

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.

Schema/Theme Require

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.

JS Section Schema

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 a schema directory

Partials

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 a partials directory

Theme

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.js

Theme.config.js

After 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

Tailwind is enabled automatically. It can be disabled in theme.config.js, and customized in tailwind.config.js

Webpack

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.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT