@snailicide/vite-plugin-shopify-liquid-modules v0.1.0

🐌 Welcome to @snailicide/vite-plugin-shopify-liquid-modules 🐌

| npm | GitHub |

This plugin enables Shopify theme developers to structure their code into "module" folders which keep Liquid template files (snippets and sections) organized together with their corresponding JS or CSS, while retaining the standard file structure of Shopify themes. Please see Inspiration section for more info and backstory!

Many thanks to barrel-shopify by Barrel NY for readme inspiration.

• 🐌 Welcome to @snailicide/vite-plugin-shopify-liquid-modules 🐌
  • Author
  • Features
    • Build
    • Tests
  • Usage
    • Using scripts in module folders
    • Options
  • Inspiration
    • Liquid Schema Plugin (webpack)
    • vite-plugin-shopify-modules (vite)
  • Helpful Links
  • To-Do
  • Bugs

Table of contents generated with markdown-toc

Author

👤 Gillian Tunney | github | email |

Features

Module System

• Automatically associates each module folder with the matching snippet, section liquid, and section schema files based on parent directory name
• Moves liquid files created within module folders to correct theme folders
• Fully compatible with Shopify GitHub integration and Shopify CLI features for syncing updates from remote theme

Dynamic Shopify Section Schemas

• Build Shopify Section schemas dynamically from Typescript, Javascript, and JSON files
• Share and reuse schema partials between different modules. Promotes efficient code reusability.
• Benefit from the language support provided by IDEs such as VSCode and WebStorm like autocompletion, formatting, collapsing
• Use Typescript autocompletion to declare schema structure using my code library. Included types and validators range from generic to highly specific.

Examples

See example_modules folder for usage examples of validators and types.

Install

#npm
npm i @snailicide/vite-plugin-shopify-liquid-modules -D

# yarn
yarn add @snailicide/vite-plugin-shopify-liquid-modules -D

# pnp
pnpm add @snailicide/vite-plugin-shopify-liquid-modules -D

For pnpm workspace:

pnpm add @snailicide/vite-plugin-shopify-liquid-modules@workspace:*

pnpm --filter=[yourGlob] add @snailicide/vite-plugin-shopify-liquid-modules@workspace:*

Build

pnpm --filter=@snailicide/vite-plugin-shopify-liquid-modules build

Tests

# build example files
pnpm --filter=@snailicide/vite-plugin-shopify-liquid-modules test:example

Usage

Add pluginShopifyLiquidModules plugin to vite.config.js / vite.config.ts:

import pluginShopifyLiquidModules from '@snailicide/vite-plugin-shopify-liquid-modules'

export default {
    plugins: [
        pluginShopifyLiquidModules({
            themeRoot: '.',
            modulesDir: './src/example_modules',
            snippets: {
                copy: true,
            },
            sections: {
                copy: true,
            },
        }),
    ],
}

• Create a "modules" folder alongside your theme folders, or use the modulesDir plugin option to specify an alternate location.
• Create a subfolder for each theme module. The folder name should precisely match the filename of the corresponding liquid section and/or snippet file.
• If a section or snippet file exists matching the module folder name, a symlink will be generated pointing from the module folder to the actual file.
• If a file matching the [module-name].section.liquid or [module-name].snippet.liquid naming convention is found in the module folder, it will be moved to the corresponding theme folder and replaced with a symlink.
• You can place any other files in the module folder, and they will not be affected by the plugin. If you add JS or CSS, make sure these files are imported from an entrypoint file somewhere to include them in the bundled output.

Using scripts in module folders

Adding a script file to a module folder will not have any effect until either:

• file is imported and loaded into your shopify theme
• file is imported at end of section file, using the schema tag:

{% comment %} Example Section File {% endcomment %}
<div class='color-{{ section.settings.color_scheme }} gradient'>Example Section</div>

{% schema 'schema.js' %}

Usage with vite-plugin-shopify by barrel-shopify:

When used in combination with the additionalEntrypoints option from vite-plugin-shopify, you also have the option to treat each module script as its own entry point to be loaded directly onto a page using a script tag. For example:

// vite.config.js / vite.config.ts
import shopify from 'vite-plugin-shopify'
import shopifyModules from 'vite-plugin-shopify-modules'

export default {
    plugins: [
        shopify({
            additionalEntrypoints: ['modules/**/*.js'],
        }),
        shopifyModules(),
    ],
}

<!-- modules/cart-drawer/cart-drawer.section.liquid -->
{% render 'vite-tag' with '@modules/cart-drawer' as vite-tag %}

See the vite-plugin-shopify docs for more details on the plugin configuration and vite-tag snippet usage.

Options

import type { ShopifyLiquidModulesOptions } from './src/options'

/* * Default Options Available * */
const defaultobj: ShopifyLiquidModulesOptions = {
    themeRoot: './theme',
    modulesDir: './modules',
    sections: { prefix: 'g-', copy: false, file_name: 'section' },
    snippets: { prefix: 'g-', copy: false, file_name: '*' },
}

Inspiration

Liquid Schema Plugin (webpack)

This plugin was inspired by David Warrington's article Building Shopify Section Schemas with JavaScript. It is a Webpack build system plugin, and this was exactly what i was looking for.

The Liquid Schema Plugin allows you to export your Shopify Section schemas from JS and JSON files, in turn allowing you to build your schemas dynamically, share schema partials between several schemas, and benefit from the language support provided by IDEs such as VSCode.

My main issue is my code editor would not collapse the Section Schemas in Liquid Templates unless i wrapped in a script tag, and then Shopify Cli would error because that is not allowed in the {% schema %} tag. These schemas also tend to be a mile long and i couldn't check for json formatting errors easily, especially when moving large groups of Section fields.

<!-- causes error when liquid is rendered -->
{% schema 'landing-page' %}
<script type="application/json">
    { "name": "Autumn Winter 2020" }
</script>
{% endschema %}

/* * Plugin Configuration * */
const LiquidSchemaPlugin = require('liquid-schema-plugin')

module.exports = {
    // ...
    'webpack.extend': {
        plugins: [
            new LiquidSchemaPlugin({
                from: {
                    liquid: './src/sections',
                    schema: './src/schema',
                },
                to: './dist/sections',
            }),
        ],
    },
}

I wanted to be able to reuse sections easily so after some use, i felt like defining separate directories for liquid and schema hindered a modular style approach. I decided on using globs to select the files and added a parent directory key. Thus, my fork born.

####GitHub - gbtunney/liquid-schema-plugin: Build reusable section schemas using Javascript

Here is how the plugin options was defined instead in my fork:

const plugin = new LiquidSchemaPlugin({
    from: {
        liquid: `${__dirname}/../../src/shopify/sections/**/section-*.liquid`,
        //  schema: `${__dirname}/../../src/shopify/sections/**/schema.ts`
    },
    to: `${__dirname}/../../shopify/sections`,
})

vite-plugin-shopify-modules by Barrel NY (vite)

I have long been hunting for a perfect Shopify theme development environment boilerplate. I wanted something similar to uicrooks/shopify-theme-lab that uses Vite instead of Webpack. A forum comment lead me to the glorious vite-plugin-shopify by barrel-shopify and then the accompanying vite-plugin-shopify-modules package.

Since this is my first time making a vite plugin, i used this as my starting structure and was heavily inspired by the overall concept. This project is a customized "hybrid" of these two projects.

Helpful Links

• Vite
• Shopify Liquid reference
• Shopify Section schema reference
• Liquid Schema Plugin (webpack)
• vite-plugin-shopify-modules (by barrel-shopify)
• vite-plugin-shopify (by barrel-shopify)

To-Do

• Unit Tests

Bugs

Please create an issue if you found any bugs, to help us improve this project!