clarity-sdk

JS SDK for interacting with the Clarity API. Allows a user to take advantage of on-chain and off-chain governance through Clarity's servers in their own web apps.

Table of Contents

• Introduction
• Technologies
• Running the sdk locally
• Resources / Acknowledgements

Introduction

This is Javascript SDK for use on other web app's front-ends. The back-end consists of a Node/Express API integrated with Firebase.

Publishing to NPM

npm publish --access private will publish the package to the claritydao NPM organization with private access.

npm publish --access public will publish the package to the claritydao NPM organization with public access.

NPM Package Versioning System

The detailed versioning system is based on this FreeCodeCamp Article.

Example of a semantic version is 1.3.12.

The rightmost number (12 in this case) is the patch version. These are just quick bug fixes with no change on the functionality.

The middle number (3 in this case) is the minor version. It is incremented when new functionality is added to the SDK. When the minor version increments, reset the patch version to 0.

The leftmost number (1 in this case) is the major version. The major version is incremented when there are breaking changes. When the major version increments, you reset both the minor version and patch version to 0.

Running the SDK locally

To run the SDK locally we will use NPM's link feature and pack feature.

NPM Pack

NPM Pack will combine all files from the directory specified in package.json's files property into a single file that can be easily imported into another project.

If running for the first time or if you have made any changes, run npm pack in the root directory. This will trigger the prepack command in package.json which will initiate the build process. During the build process, the lib directory is deleted (if one exists) as this is where the compiled files will be output. The files are then compiled to CommonJS modules and ES modules from Typescript and output to the lib directory.

After the build process completes, NPM Pack will output a file named something similar to claritydao-clarity-sdk-1.0.0-development.tgz. This is the file that will be imported by your local test project. Note that the file name will match the name property in package.json. If you change this value the name of the outputted file will also change.

In your local test React app, add the following package to the dependencies property. The key should be clarity-sdk and the value should be file:"Path to the tgz file generated by NPM Pack.

"@claritydao/clarity-sdk": "file:../clarity-sdk/claritydao-clarity-sdk-1.0.8.tgz",

Run npm install and you should now be able to use the NPM package in your local test app.

NPM Link

NPM Link is another method of locally testing NPM packages. However, I ran into multiple issues attempting to use it. I recommend using the NPM Pack process detailed above instead.

Resources / Acknowledgements

• How to publish a NPM package
• NPM semantic versioning
• Express custom error handler
• Best practices for NPM packages