@by-association-only/theme-check-unisian

Shared Shopify Theme Check rules for consistent section and theme-block schemas across BAO projects.

The package is installed by Shopify-starter-theme-2.0, giving projects the same schema diagnostics and safe ordering fixes in Theme Check and VS Code.

What it checks

• Top-level schema property order
• Setting property order
• Option property order
• Block and nested-block property order
• Preset and preset-block property order
• Device-first media IDs such as desktop_image and mobile_video

The agreed orders and naming conventions live in:

config/order.js
config/naming.js

Unknown properties are preserved and ignored until an order is explicitly configured.

Automatic fixes

Ordering rules can safely reorder recognised JSON properties without changing values, array item order, setting IDs or Liquid outside {% schema %}.

For example:

{
  "type": "range",
  "id": "overlay",
  "min": 0,
  "max": 1,
  "step": 0.1,
  "label": "Overlay opacity",
  "default": 0
}

Becomes:

{
  "type": "range",
  "id": "overlay",
  "label": "Overlay opacity",
  "min": 0,
  "max": 1,
  "step": 0.1,
  "default": 0
}

Naming rules report only. They do not rename IDs because related Liquid references would also need updating.

Local testing

Until the package is published to npm, create a tarball from this repository:

npm run check
npm pack

Install the generated .tgz in Shopify-starter-theme-2.0:

npm install --save-dev ~/Desktop/by-association-only-theme-check-unisian-0.3.0.tgz

For shared testing, place the tarball inside the starter-theme repository and install it with a repository-relative path instead of committing a developer-specific Desktop path.

Theme configuration

Add to .theme-check.yml:

extends:
  - theme-check:recommended
  - '@by-association-only/theme-check-unisian/recommended.yml'

require:
  - '@by-association-only/theme-check-unisian'

Existing project-specific Theme Check overrides can remain below this configuration.

Useful project scripts:

{
  "scripts": {
    "dev": "npm run lint:theme && npm run dev:watch",
    "dev:watch": "npm run assets:dev & npm run theme:dev",
    "lint:theme": "shopify theme check",
    "lint:theme:fix": "shopify theme check --auto-correct"
  }
}

VS Code

Use the official Shopify Liquid extension and include:

{
  "themeCheck.checkOnChange": true,
  "themeCheck.checkOnSave": true,
  "themeCheck.checkOnOpen": true,
  "[liquid]": {
    "editor.defaultFormatter": "Shopify.theme-check-vscode",
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit"
    }
  }
}

After installing or updating the package, run Developer: Reload Window in VS Code.

Confirm the checks are loaded with:

npx shopify theme check --list | grep Unisian

Package development

Run all tests and package checks:

npm run check

When changing a convention:

1. Update config/order.js or config/naming.js.
2. Update or add tests.
3. Update CHANGELOG.md.
4. Bump the package version.
5. Run npm run check and npm pack.
6. Test the new tarball in Shopify-starter-theme-2.0.

Use patch versions for fixes and minor versions for new rules or convention changes while the package remains below 1.0.0.

Publishing

Once approved:

npm login
npm run check
npm publish --access public

Then replace the temporary file dependency in Shopify-starter-theme-2.0 with the published package version and commit package.json and package-lock.json.

Usage

Maintained for BAO Agency Shopify projects. Public npm distribution is for installation purposes; no licence is granted for external reuse, modification or redistribution.