Webpack Shopify schema splicer

A lightweight Webpack plugin that allows you to splice reusable section settings or blocks into your theme.

• Please note: Once you make changes to your reusable schema, you will need to restart your Webpack compiler. Changes will not occur until the compiler starts up again due to the nature of Node JS.

Installation

1. Install the library

# Using yarn
yarn add webpack-shopify-schema-splicer

# Using npm
npm install webpack-shopify-schema-splicer

2. Add the plugin to your Webpack file

import LiquidSchemaSplicerPlugin from "webpack-shopify-schema-splicer";

export default {
  ..., // The rest of your Webpack file
  plugins: [
    ..., // The rest of your Webpack plugins
    new LiquidSchemaSplicerPlugin(),
  ],
}

3. Create reusable schema

1. Create a src/schema/blocks and a src/schema/settings folder. You can change the location of this file if necessary in advanced options.
2. Recommended: Create a src/schema/options folder, where you will place fields and data that are shared.
3. You will find some example schema settings, blocks, and options in the following folders:

• Example settings files.
• Example blocks files.
• Example options files.

3.1. Create reusable section settings schema

1. Create your first reusable field. Here is an example. Save this file as src/schema/settings/richtext.js.

export default {
  type: "richtext",
  id: "richtext",
  label: "Richtext",
  default: "<p>Nam consectetur sit amet tellus sit amet posuere.</p>"
};

• Please note that you can also borrow settings from the library that comes packaged with the module. You would do this like the following:

  import richtext from "webpack-shopify-schema-splicer/lib/settings/richtext.js";
  
  export default richtext;

2. Run Webpack, and make a change to any src/section file. Under {% schema %}, add to your section's settings:

{% schema %}
{
  "settings": [
    {
      "id": "richtext"
    }
  ]
}
{% endschema %}

3. Hit save, and watch the rest of the data (label, default, etc.) splice in.

• Please note, for section settings, the option is spliced in by the id parameter.
• Please note that every time you save, all of the section settings with "id": "richtext" will be replaced by the splicer. The goal here is reusable settings data, so make sure that your id is specific enough to your needs.

3.2. Create reusable section blocks schema

Create your first reusable block. Here is an example:

1. Save this file as src/schema/blocks/button.js.

export default {
  type: "button",
  name: "Button",
  settings: [
    {
      id: "button_title",
      label: "Button title",
      type: "text",
      default: "Read more",
    },
    {
      id: "button_link",
      label: "Button link",
      type: "url",
    },
  ],
};

• Please note that you can also borrow blocks from the library that comes packaged with the module. You would do this like the following:

  import button from "webpack-shopify-schema-splicer/lib/blocks/button.js";
  
  export default button;

2. Run Webpack, and make a change to any src/section file. Under {% schema %}, add to your section's blocks:

{% schema %}
{
  "blocks": [
    {
      "type": "button"
    }
  ]
}
{% endschema %}

3. Hit save, and watch the rest of the block data splice in.

• Please note, for section settings, the option is spliced in by the type parameter.
• Please note that every time you save, all of the section settings with "type": "button" will be replaced by the splicer. The goal here is reusable settings data, so make sure that your type is specific enough to your needs.

3.3. Create fields that can be shared by section settings and blocks

A lot of fielded data is quite general and can be reused. This can be done by a simple include pointing to data in the src/schema/options folder.

Create your first reusable field. Here is an example:

1. Save this file as src/schema/options/collection.js.

export default {
  type: "collection",
  id: "collection",
  label: "collection"
};

• Please note that you can also borrow settings from the library that comes packaged with the module. You would do this like the following:

  import collection from "webpack-shopify-schema-splicer/lib/settings/collection.js";
  
  export default collection;

2. To use this field in a section, create the file src/schema/settings/collection.js.

import collection from "../options/collection.js";

export default collection;

3. Run Webpack, and make a change to any src/section file. Under {% schema %}, add to your section's settings:

{% schema %}
{
  "settings": [
    {
      "id": "collection"
    }
  ]
}
{% endschema %}

4. Hit save, and watch the rest of the data (label, default, etc.) splice in.
5. Let's use this same data in a block now. Save the following as src/schema/settings/collection_card.js.

import collection from "../options/collection.js";

export default {
  type: "collection_card",
  name: "Collection card",
  settings: [
    collection,
    {
      id: "image",
      label: "Image",
      type: "image_picker"
    },
  ],
};

The same collection field data is populating the setting and block data now. We only have to write this once now and it will change in all locations.

Important: A strategic notes for Shopify since the innovation of theme blocks.

Now that Shopify has released reusable blocks, we recommend the use of this code be largely reduced to replacing reusable settings site-wide.

Pleas note:

• In the current version, settings that appear in theme blocks will be replaced in the same way that section settings are replaced. Eg, if there is a ./src/schema/settings/text_alignment.js file, it will replace the settings with an id of text_alignment in the settings schema in both /blocks/*.liquid and /sections/*.liquid.
• In the same way, if there is a ./src/schema/blocks/copy.js file, it will replace blocks with the type set to copy in the block schema of both /blocks/*.liquid and /sections/*.liquid.
• Because of this, be careful with your naming protocol to ensure that you replace the right things.
• We recommend that you largely use this to replace settings, as blocks can be built of reusable fields quite simply now.

Making use of library settings and blocks

If you want to make use of the schema settings and blocks already present in this library, you can quite simply. You simply indicate in the config which settings or blocks you want included, and the library will splice them in.

Example: Use library setting

To make use of the image_alignment setting offered in the ./lib/settings folder of this library, you would do the following in your webpack configuration:

import LiquidSchemaSplicerPlugin from "webpack-shopify-schema-splicer";

export default {
  ..., // The rest of your Webpack file
  plugins: [
    ..., // The rest of your Webpack plugins
    new LiquidSchemaSplicerPlugin({
      useLibrarySettings: ['image_alignment'],
    })
  ],
}

Any appearance of schema settings with an id of image_alignment will now be replaced with out conntent.

Example: Use library blocks

To make use of the accordion block offered in the ./lib/blocks folder of this library, you would do the following in your webpack configuration:

import LiquidSchemaSplicerPlugin from "webpack-shopify-schema-splicer";

export default {
  ..., // The rest of your Webpack file
  plugins: [
    ..., // The rest of your Webpack plugins
    new LiquidSchemaSplicerPlugin({
      useLibraryBlocks: ['accordion'],
    })
  ],
}

Any appearance of schema blocks with type accordion will now be replaced with out conntent.

Advanced options

import LiquidSchemaSplicerPlugin from "webpack-shopify-schema-splicer";

export default {
  ..., // The rest of your Webpack file
  plugins: [
    ..., // The rest of your Webpack plugins
    new LiquidSchemaSplicerPlugin({
      // The folder containing your block and section files
      path: 'src', // Default
      // This is the folder containing your blocks and settings folders
      schemaPath: 'src/schema', // Default
      // Any library settings you want to use
      useLibrarySettings: [], // Default
      // Any library blocks you want to use
      useLibraryBlocks: [], // Default
    }),
  ],
}

Development

Releases

Releases are fully automated via semantic-release. Do not manually bump package.json or publish to npm. Everything is handled by CI when you merge into main.

How it works

1. Open a PR against main
2. Merge using Squash and Merge — the PR title becomes the commit message
3. The release workflow runs automatically and determines the version bump from the PR title:

| PR title | Version bump | |---|---| | Any title (no prefix) | Patch — 1.4.0 → 1.4.1 | | fix: resolve schema bug | Patch — 1.4.0 → 1.4.1 | | feat: add block support | Minor — 1.4.0 → 1.5.0 | | feat!: redesign plugin API | Major — 1.4.0 → 2.0.0 |

On release, the workflow will automatically:

• Bump the version in package.json
• Update CHANGELOG.md
• Create a GitHub Release with generated release notes
• Publish to npm