block-scripts

Consolidate the pieces around block development for the Element ecosystem

Installing block-scripts

Install via npm and save as a devDependency:

npm install --save-dev @volusion/block-scripts

Using block-scripts

After installing the block-scripts package, it becomes an executable. Use it on its own or as an npm script in your block's package.json (recommended):

block-scripts start

Start the block server, using rollup

block-scripts build

Builds the block, also using rollup

block-scripts lint

Lints the block, using eslint

block-scripts test

Tests the block, using jest

Developing

Clone the repo, change to the directory, and run npm install.

To use the executable, run npm link after running npm run build. Then, the executable block-scripts will be available to run in another terminal, as long as the same version of Node.js is loaded as the version present when you ran npm link.

The .node-version file

To ensure we're all using the same version of Node.js while developing, please use either n or nvm to install the project's Node.js version, and then install AVN, along with the relevant helper:

npm install -g avn

# If you're managing Node versions with NVM:
npm install -g avn-nvm

# If you're managing Node versions with n:
npm install -g avn-n

Then, set up AVN with

avn setup

and after following the on-screen instructions, you should be good to go — upon changing to this directory, you'll be automatically switched to use the correct version of Node.js, specified in the .node-version file.

Releasing

Releases are automated using release-please. You do not need to manually bump versions or publish to NPM.

Commit message format

All commits must follow this format:

<type>: <JIRA-TICKET-ID> <description>

Examples:

• feat: ET-4591 add support for new block config API
• fix: ET-4134 correct jest setup for jsdom environment
• chore: ET-4000 update dependencies

A commit-msg hook (installed via npm install) will reject commits that don't match this format.

Allowed types and their effect on versioning:

| Type | Version bump | Use for | |------|-------------|---------| | feat | minor (x.Y.z) | New feature | | fix | patch (x.y.Z) | Bug fix | | chore | none | Maintenance, dependencies | | docs | none | Documentation only | | refactor | none | Code restructure, no behaviour change | | test | none | Adding or updating tests | | build | none | Build system changes | | ci | none | CI/CD configuration | | perf | patch | Performance improvement | | revert | patch | Reverts a previous commit |

For a major version bump, add a BREAKING CHANGE: footer to your commit:

feat: ET-9999 redesign block config API

BREAKING CHANGE: configSchema prop renamed to schema

How releases work

1. Merge your PR to master with a conventional commit message.
2. The Release Please GitHub Action automatically opens (or updates) a Release PR that bumps the version in package.json and updates CHANGELOG.md.
3. When you're ready to release, merge the Release PR.
4. release-please creates a GitHub Release and git tag (e.g. v2.5.0).
5. The Publish to NPM GitHub Action triggers automatically and publishes the package to npmjs.com with a signed provenance attestation.