@inversable/hasura-js-sdk v5.2.1

Hasura JS SDK

The Hasura JS SDK is a JavaScript package that can be used to streamline communication with the Inversable Hasura Backend (IHB). It exposes two classes: Auth and Storage, used for authentication and storage requests respectively.

The Hasura JS SDK was forked from the Nhost JS SDK commit f0086438.

Install

To install the Hasura JS SDK run the following command:

$ npm install @inversable/hasura-js-sdk

Not every version of the Hasura JS SDK is compatible with every version of the IHB. Please refer to the compatibility matrix:

Note that in December 2022 the version numbers of the Hasura JS SDK and IHB were bumped to match eachother

Updating the Hasura JS SDK

Because the Hasura JS SDK is used by multiple projects in the Inversable ecosystem developers should make sure that minor / patch updates do not introduce any breaking changes. Breaking changes are only allowed in major updates, and requires approval of at least another developer that is familiar with the Hasura JS SDK.

Before you continue to make any changes make sure that your development environment (e.g. VSCode) applies the rules specified in .eslintrc.json. If you develop in VSCode the folder .vscode should take care of this, but please verify.

When working on a new feature/update, make sure you follow these steps:

1. Make clear issues on GitLab describing what it is you want to achieve, why this is necessary and how you are going to do this. Please link any existing issues in you issue that have (partial) overlap
2. Make a new branch from the latest version of the master. Make sure you have the latest version of the master branch before you create your branch.
3. Work on your feature in your branch. Make sure you assign yourself to an issue so others know what you are working on, and which parts of the IHB might be subject to change.
4. When your feature request is completed, make a merge request and assign one of the other Hasura JS SDK developers to approve the merge request. As of writing this @bverkuil is the main developer of the Hasura JS SDK.
5. Deploy your new feature (see Deployment)

Easy development with npm link

To quickly test changes you work locally without the need of deployment you can use npm link. Npm link will create a symlink to a global folder that links to the package where the npm link command was executed. This folder ends up in {prefix}/lib/node_modules/<package>. You can find the path of {prefix} using this command: npm prefix -g. Run the following steps to symlink the Hasura JS SDK to your front-end for testing.

1. Make sure you have the version of the Hasura JS SDK open on your machine which you want to use. Navigate to the root of the folder.
2. Run npm link. This creates (or overwrites) an entry for the package in {prefix}/lib/node_modules/<package>. The <package> is taken from package.json name, and is @inversable/hasura-js-sdk for this project.
3. Navigate to a front-end where you want to test the Hasura JS SDK changes. If you are not working on any particular front-end, the Example Project can be used.
4. Open a terminal in the root folder op the front-end directory and run npm link <package>. For the Hasura JS SDk this command will be npm link @inversable/hasura-js-sdk. The front-end should now use the content of your local copy of the Hasura JS SDK

Please note that even though the code for the Hasura JS SDK is written in TypeScript your browser only understands JavaScript. Run npm run build in the Hasura JS SDK directory every time you made changes to .ts files

If you have trouble with npm link, sometimes manually deleting the global package found at {prefix}/lib/node_modules/<package> solves this issue. Make sure to run steps 1-4 again afterwards.

Deployment

The IHB is deployed as a pacakge on npm. The deployment is done via a CI/CD pipeline. The npm package can be found online: @inversable/hasura-js-sdk .

Please make sure you update the version number in package.json before you run the CI/CD pipeline!

If everything is ready for publish click on CI/CD in the left menu, find your merge into the master branch (probably the first entry in the list) and run the publish-on-npm pipeline.

Then, go to Repository --> Tags in GitLab and create a new tag. Make sure the tag name matches the version you specified in package.json.

Finally create a new release. Go to Deployments --> Releases and add a release matching the tag you created in the step before. Enter what things you changed here, including any additions and (breaking) changes.