The Complete Guide to Building SDKs
Our lead engineer, Akshit Gupta, deep dives into the whole process of building your own SDK, just like Huddle01.
Building an SDK in TypeScript/JavaScript can significantly enhance the usability and adoption of your software by other developers. TypeScript's static typing and JavaScript's ubiquity make them a powerful duo for crafting reliable and accessible SDKs.
In this guide, we will delve into the process of building SDKs using TypeScript/JavaScript and explore three powerful bundling tools: tsup, preconstruct, and Rollup.
Additionally, we will cover best practices for publishing SDK packages using changesets and releasing beta and alpha versions on npm.
Importance of using TypeScript
To identify whether an npm pkg is a TypeScript pkg or not, you can spot a blue ts logo to the right of the name of the pkg.
Using TypeScript in building npm packages offers several significant advantages that contribute to the overall development process of the SDK Users as well as the developer developing the SDK. Here are some key reasons why I strongly recommend using TypeScript while developing an npm pkg:
Enhanced Code Quality: TypeScript helps identify common coding mistakes, such as typos, incorrect variable usage, and missing properties.
Refactoring Support: TypeScript's static typing enables safer and easier refactoring of code. When making changes to interfaces or types.
Tooling and Ecosystem Support: TypeScript is well-supported by various build tools, testing frameworks, and other development tools.
Type Definitions and Documentation Generation: TypeScript provides a way to create type definitions (
.d.tsfiles) automatically. (essential for typescript projects using the SDK)Integration with Existing JavaScript Code: TypeScript supports incremental adoption, allowing developers to gradually convert existing JavaScript codebases to TypeScript.
1. Getting Started
a. Set up the Project
First, create a new TypeScript project and initialize it with npm or yarn.
# Create a new TypeScript project
mkdir my-sdk
cd my-sdk
npm init -y
# Install TypeScript as a dev dependency
npm install typescript --save-dev
b. TypeScript Configuration
Next, set up the TypeScript configuration by creating a tsconfig.json file in the project root.
{
"compilerOptions": {
"target": "es6",
"module": "esnext",
"declaration": true,
"outDir": "dist",
"strict": true,
"esModuleInterop": true},
"include": ["src"],
"exclude": ["node_modules"]
}
2. Writing the SDK
Code Structure
Place your SDK source code inside the src directory. Organize your code into modules, classes, or functions, depending on the complexity of your SDK.
For example, let's create a simple SDK that exports a function to greet users:
// src/greeter.ts
export function greet(name: string): string {
return `Hello, ${name}!`;
}
Exporting Types and Interfaces
When building SDKs, it's essential to export types and interfaces used by the SDK consumers. Consider creating a separate types.ts file to manage exports.
// src/types.ts
export interface Greeting {
message: string;
}
In the main entry file, ensure that you export all necessary entities.
// src/index.ts
export * from './greeter';
export * from './types';
3. Bundling with tsup
Installing tsup
Tsup is a zero-config bundler specifically designed for TypeScript projects.
Install tsup as a dev dependency:
npm install tsup --save-dev
Building the SDK
To bundle your SDK using tsup, add a build script in your package.json.
{
"scripts": {
"build": "tsup"
}
}
Run the build command to create the bundled files.
npm run build
By default, tsup bundles your SDK as an ES module.
4. Bundling with Preconstruct 🎁
a. Installing Preconstruct
Preconstruct is a flexible build tool designed for modern JavaScript projects.
Install preconstruct as a dev dependency:
npm install preconstruct --save-dev
b. Setting up Preconstruct
Create a preconstruct.config.js file in the project root to configure preconstruct.
module.exports = {
entry: 'src/index.ts',
umdName: 'MySDK',
};
c. Building the SDK
To bundle your SDK using preconstruct, add a build script in your package.json.
{
"scripts": {
"build": "preconstruct build"
}
}
Run the build command to create the bundled files.
npm run build
Preconstruct bundles your SDK in three formats: UMD, CommonJS, and ES modules.
5. Bundling with Rollup
a. Installing Rollup
Rollup is a powerful, configurable bundler suitable for JavaScript projects of any size.
Install Rollup and additional plugins as dev dependencies:
npm install rollup rollup-plugin-typescript2 --save-dev
b. Setting up Rollup
Create a rollup.config.js file in the project root to configure Rollup.
import typescript from 'rollup-plugin-typescript2';
export default {
input: 'src/index.ts',
output: [
{
file: 'dist/my-sdk.umd.js',
format: 'umd',
name: 'MySDK',
},
{
file: 'dist/my-sdk.module.js',
format: 'es',
},
{
file: 'dist/my-sdk.common.js',
format: 'cjs',
},
],
plugins: [typescript()],
};
c. Building the SDK
To bundle your SDK using Rollup, add a build script in your package.json.
{
"scripts": {
"build": "rollup -c"
}
}
Run the build command to create the bundled files.
npm run build
Rollup bundles your SDK in three formats: UMD, ES module, and CommonJS.
💡 If you’re confused as to which bundler to use, this is an exhaustive list of the pros and cons of each
| Features | preconstruct | tsup | rollup |
| Multiple Entrypoints | Best | Better | Good |
| Catching Errors | Bad | Better | Best |
| Ease | Easy | Moderate | Hard |
| Polyfills | Hard | Easier | Best |
| Flexibility | Bad | Better | Best |
6. Publishing with changesets
a. Installing changesets
Changesets is a tool that helps manage and publish version updates for multiple packages in a mono-repository.
Install changesets globally:
npm install -g changesets
b. Configuring changesets
Initialize changesets in your project by running the following command:
changeset init
c. Creating a changeset
To prepare a new release, use the following command:
changeset
This command will prompt you to select the packages that have changed and specify the type of version update (patch, minor, or major).
d. Applying the changeset
Once the changeset is created, apply it to the packages:
changeset version
This command will bump the version numbers, update the changelog, and commit the changes.
e. Publishing the packages
Finally, publish the updated packages to npm:
changeset publish
7. Beta and Alpha Releases on npm
a. Publishing Beta Releases
To publish a beta release on npm, add the --tag flag when running the publish command.
npm publish --tag beta
This will publish the package to the npm registry with the beta tag, allowing users to install the beta version explicitly.
b. Publishing Alpha Releases
Alpha releases are pre-release versions intended for testing and internal use. To publish an alpha release, append -alpha to the version number.
npm version 1.0.0-alpha.1
npm publish --tag alpha
Users can then install the alpha version by specifying the exact version number.
Conclusion
Building SDKs in TypeScript/JavaScript requires careful planning, code organization, and an understanding of bundling tools like tsup, preconstruct, and Rollup.
By following the steps outlined in this guide and adopting best practices for publishing with changesets and releasing beta and alpha versions on npm, you can create robust and user-friendly SDKs that cater to the needs of developers and drive broader adoption.
Remember to actively engage with the developer community, gather feedback, and iterate on your SDK regularly to ensure its continuous improvement and success.
Happy SDK building! 🛠️
Checkout Huddle01 SDKs, where we’ve applied all these learnings: https://huddle01.com/docs
Huddle01 is building the 1st decentralized real-time communication network. Our current suite of developer-friendly SDKs enables powerful live audio and video experiences for web and mobile apps with just a quick plug-in. The Huddle01 app, which is built on Huddle01's own robust media infrastructure, enables wallet-to-wallet video meetings and audio spaces with additional features like token-gating, multi-streaming, recording and much more coming soon.