Shipping JS SDK in the development environment
Developing and shipping an SDK is slightly different from a full-fledged web app. You can spin up a development server with a hot module replacement, and you will have an app that reflects your live changes. Once you are happy with your changes, you can upload them to a dev server, where your peers can review the changes, and finally, you can upload them to production.
However, the SDKs do not work independently. A web app or other library must consume it to work. Hence, you’ll need an additional project to consume your SDK during the development. This article will explore how we ship the SDK in different environments so your app can consume it quickly.
This article is for freelancers or developers starting their development journey and developing a JS SDK for the first time. So, let’s dive in.
Tl;dr: Use npm intall to work locally, have a prepare script that runs your build script, and use GitHub branches or GitHub private packages to share the SDK with your peers without pushing it to NPM.
If you want to follow along, go to https://github.com/Deepak-Kharah/blog-ship-sdk-in-different-env and clone it.
Once cloned, you will see two folders: simple-star-wars-sdk and simple-star-wars-ui. Open this folder in your favorite code editor.
Now, open these two folders in two separate terminals and Switch the branch to 01-start-from-here.
git switch 01-start-from-here
Install the dependencies using the npm install command and run the server using npm run dev command.
Open http://localhost:3000/, and you will see your application running.
However, clicking on any card will not fetch the character’s details and will show Classified instead.
We will fix this error by the end of this article by modifying the code only in the SDK folder.
Local development
We want to update the SDK to fetch the character details. Open the simple-star-wars-sdk/src/index.js in your text editor. The line 21 shows you what you need to update to fix the code.
However, before that, let’s prepare your development environment to see the changes in real time.
Stop both terminals by pressing ctrl+c. In the SDK’s terminal, run the pwd command. It will show you the current working directory.
Copy the output and run the npm i <pwd-path> command in the UI’s terminal.
This will create a symlink of the SDK in the UI. When you turn your servers back, you will see the changes in the SDK reflected in the UI automatically.
Let’s open the simple-star-wars-sdk/src/index.js file back and fix the code.
...
static async getCharacter(id) {
return fetch(`https://swapi.dev/api/people/${id}`)
.then((response) => response.json())
- .then((data) => ({}));
+ .then((data) => data);
}
...Once you fix it, you’ll see the UI update and fetch the correct data automatically without reloading the server.
You will find the code here in the 02-local-development-complete branch.
Shared development
Once your development is completed, you will push your changes to a branch where your peer will pull them and use them to review. Alternatively, once your SDK is updated, the other team may use it in their UI. Since the product is still under development, you cannot publish your SDK in the NPM registry. Hence, you’ll need an alternative method to share the SDK with your peers.
There are two methods I use when I develop SDKs. The first is installing the GitHub branches directly, and the second is using private packages.
Before we explore the methods, let’s prepare our SDK to handle it. If you start directly from this section, you can use the 02-local-development-complete branch to follow along.
You had to build your SDK manually to use in the UI at this stage. We did it by running the npm run dev command. In this scenario, we must push the dist/ files in GitHub.
Here’s where the problem lies. You are bloating your Git history by keeping the dist/ files, and if you forgot to build before pushing, you will have an outdated SDK.
To solve this, we will use the prepare script in the package.json. The prepare script runs when a user installs our package and some other times. You can learn more about the prepare script from the NPM documentation.
Open simple-star-wars-sdk/package.json and add the prepare script to run the build command.
...
"scripts": {
+ "prepare": "npm run build",
"build": "parcel build",
"test": "npm run test",
"dev": "parcel watch"
},
...You can test it by deleting the simple-star-wars-sdk/dist folder and installing the SDK back in the UI. It should generate the dist/ folder again. Push your changes to GitHub for the next steps.
The code changes are available in the 03–1-shared-development branch.
Using GitHub branches to share the SDK
You can specify a GitHub branch directly to the package.json, which will be installed from it.
Here’s the format
...
"dependencies": {
...
"simple-star-wars-sdk": "github:<owner>/<repository>/#<branch>"
},
...Or you can use the npm command like this:
npm install "https://github.com/<owner>/<repository>.git#<branch>"Please note: Until today, while I am drafting this article there is no native way to
npm installa GitHub subfolder. You can use https://gitpkg.vercel.app/about/ for installing the sub folders.
This will build your project and install it for others to use.
Using private packages
You can share your private repository with the GitHub package manager if your repository is private.
You have to create an access token (classic) with the scope of read:packages and use it to publish the package. The GitHub’s documentation covers using the NPM registry with GitHub packages. Hence, I won’t be going in-depth about using it here.
Alternatively, you can publish using the --tag to mark a release as alpha or beta. This will allow you to push your changes to the NPM without affecting the mass users. They can install it if they opt-in.
Let me know if you know other ways to build and share SDKs during development. I’ll see you soon. Till then, have a great day. ✌️
