This gem is used to validate themes built for the Easol platform.

You can install the gem globally with the following and the canvas command will be available:

gem install easol-canvas
cd my_easol_theme
canvas lint

Alternatively, you can add it to a Gemfile in your project and run the command using bundle exec:

cd my_easol_theme
bundle exec canvas lint

When called inside the root of a theme directory, the canvas lint command will run various validation checks, such as the following:

1. RequiredFilesCheck
   • Checks that the required files exist (e.g. templates/product/index.html).
2. ValidHtmlCheck
   • Validates all .html files contain valid HTML.
3. ValidLiquidCheck
   • Validates all .html files contain valid Liquid.
4. ValidJsonCheck
   • Validates all .json files contain valid JSON.
5. ValidSassCheck
   • Validates all .css, .scss and .sass files contain valid Sass.
6. ValidBlockSchemasCheck
   • Validates the schema defined in each block.
7. ValidMenuSchemaCheck
   • Validates the schema defined in each menu.
8. ValidFooterSchemaCheck
   • Validates the schema defined in each footer.
9. ValidCustomTypesCheck
   • Validates each custom type defined within the /types directory.

There is a canvas-linter-action, which can be used inside an Easol theme repo to run validations on each push. Here’s an example where it is was set up in alchemist.

Follow the instructions in the README to set up this action inside your theme project.

You can run the tests within the repo with the following:

bundle
bin/rspec

This approach is generally quicker than installing the gem (see below). Please use the built gem for final testing.

Within a theme repo, call the executable of the gem directly, for example:

cd alchemist_theme
../canvas/bin/canvas lint

1. Clone the easolhq/canvas repo locally.

2. Build the gem inside the canvas directory to create a .gem file.

   cd canvas
   gem build
   

3. Install the local version of the gem (make sure this is called inside the canvas directory, gem install will look for a .gem file and use that instead of installing from rubygems if it exists).

   cd canvas
   gem install easol-canvas
   

4. Now you can use the gem within a theme repo.

   cd alchemist_theme
   canvas lint
   

1. Clone the easolhq/canvas repo locally.

2. Build the gem inside the canvas directory to create a .gem file.

   cd canvas
   gem build
   

3. Add the gem to the Gemfile in your Rails app and specify the local path.

   gem "easol-canvas", path: "/path/to/canvas"

4. You can now reference the validators inside Rails, e.g.

   require "canvas"
   
   ...
   
   Canvas::Validator::BlockSchema.new(schema: block_schema)

1. Implement your code changes.
2. Bump the version in the code:
   1. bundle exec gem bump --version [minor|major|patch]
   2. Commit these changes.
3. Push changes, wait for PR to be approved, then merge to main.
4. Pull the latest from main
5. Tag the latest version via git:

   bundle exec gem tag
   

6. Push created tag with git push --follow-tags which will trigger Github actions responsible for publishing new version of the gem to rubygems.org repository
7. On major version changes, update the version lock in the canvas-linter-action repo.