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:
- RequiredFilesCheck
- Checks that the required files exist (e.g.
templates/product/index.html
).
- Checks that the required files exist (e.g.
- ValidHtmlCheck
- Validates all
.html
files contain valid HTML.
- Validates all
- ValidLiquidCheck
- Validates all
.html
files contain valid Liquid.
- Validates all
- ValidJsonCheck
- Validates all
.json
files contain valid JSON.
- Validates all
- ValidSassCheck
- Validates all
.css
,.scss
and.sass
files contain valid Sass.
- Validates all
- ValidBlockSchemasCheck
- Validates the schema defined in each block.
- ValidMenuSchemaCheck
- Validates the schema defined in each menu.
- ValidFooterSchemaCheck
- Validates the schema defined in each footer.
- ValidCustomTypesCheck
- Validates each custom type defined within the
/types
directory.
- Validates each custom type defined within the
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
-
Clone the easolhq/canvas repo locally.
-
Build the gem inside the canvas directory to create a
.gem
file.cd canvas gem build
-
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
-
Now you can use the gem within a theme repo.
cd alchemist_theme canvas lint
-
Clone the easolhq/canvas repo locally.
-
Build the gem inside the canvas directory to create a
.gem
file.cd canvas gem build
-
Add the gem to the
Gemfile
in your Rails app and specify the local path.gem "easol-canvas", path: "/path/to/canvas"
-
You can now reference the validators inside Rails, e.g.
require "canvas" ... Canvas::Validator::BlockSchema.new(schema: block_schema)
- Implement your code changes.
- Bump the version in the code:
- bundle exec gem bump --version [minor|major|patch]
- Commit these changes.
- Push changes, wait for PR to be approved, then merge to
main
. - Pull the latest from
main
- Tag the latest version via git:
bundle exec gem tag
- 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 - On major version changes, update the version lock in the canvas-linter-action repo.