@jcoreio/clarity-plugin-toolkit

This is a CLI that makes it easy to build and deploy your plugin to Clarity. It provides a managed webpack config and scripts to orchestrate the process of uploading the webpack bundles to Clarity.

Getting Started

The easiest way to get started is to create a project with create-clarity-plugin:

npx create-clarity-plugin@latest
# or
yarn create clarity-plugin
# or
pnpm create clarity-plugin
# or
bunx create-clarity-plugin

Then in the project use npm run dev to start the Dev Server.

Dev Server

npm exec clarity-plugin-toolkit dev starts the dev server. (create-clarity-plugin adds a dev package script alias for this.) On the first run it will create .env and docker-compose.yml files and ask you to fill out some fields in .env (currently, you only need to set the hostname of our private AWS Elastic Container Repository).

Thereafter running clarity-plugin-toolkit dev will automatically start up build watch processes and the Clarity docker container with your plugin from this project mounted into it. It will automatically open Clarity in your browser once it's up and running!

The dev server supports Webpack Hot Module Replacement and whenever you change client modules the changes should theoretically show up in the browser. However react-refresh hasn't seemed reliable, at least not with the version of react Clarity is on. But changes should at least show up after you refresh the page.

If you change backend modules, the dev server will restart the docker container as soon as possible with the new code.

Updating the Clarity Docker image

Type a newer version in the app image tag in the docker-compose.yml generated by the dev command. Then run npm exec clarity-plugin-toolkit pull-image to pull it. This command logs into the AWS Elastic Container Repository before pulling the image.

AWS Credentials

The dev and pull-image commands use AWS SDK credentials found in your environment (e.g. ~/.aws/credentials). You can manually specify credentials via the AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY environment variables or use the AWS_PROFILE environment variable to specify which profile in your ~/.aws/credentials to use.

Deploying

Run npm exec clarity-plugin-toolkit deploy to begin the interactive plugin deployment process. (create-clarity-plugin adds a deploy package script alias for this.) First the CLI will ask you for the URL of your Clarity deployment. Then, it will have you create a code signing key in Clarity. Finally, it will rebuild the webpack bundles if necessary and upload them to Clarity via its REST API.