Summary

The website content outlines the best practices and tools for developing a JavaScript SDK using TypeScript, emphasizing the importance of developer experience, documentation, performance, modernization, and reliability.

Abstract

The article discusses the significance of creating a JavaScript SDK with TypeScript, highlighting the benefits of SDKs for custom app development and ease of use. It outlines five key principles for a robust SDK: good developer experience (DX), comprehensive documentation, high performance, modernization, and reliability. The author introduces tools that align with these principles, such as Lerna for managing multi-package repositories, Rollup for module bundling with tree shaking, Codecov for code coverage reports, Jest for JavaScript testing, TypeDoc for generating documentation from TypeScript source code, Prettier for code formatting, and TypeScript itself for static typing and modern JavaScript features. The article emphasizes the role of these tools in ensuring consistency, performance, and reliability in the SDK development process.

Opinions

The author suggests that SDKs are essential for companies to provide customizable services to their customers.
Good developer experience is crucial and is achieved through simple interfaces.
Comprehensive and up-to-date documentation is vital for developers to understand and utilize the SDK effectively.
High performance is non-negotiable, and SDKs should minimize their impact on the performance of the end application.
Modernization, including the use of the latest JavaScript specifications, techniques, and tools, is key to maintaining a relevant and efficient SDK.
Reliability is paramount, with an emphasis on version control and delivering features that work as expected for both developers and end-users.
The use of specific tools like Lerna, Rollup, Codecov, Jest, TypeDoc, Prettier, and TypeScript is advocated for their ability to streamline the development process and adhere to the outlined principles.

Best Practices for Building JavaScript SDKs With TypeScript

Currently, making an SDK has become a common way for companies to make their services more useful to customers who need further customization. SDKs not only let you create new tools efficiently but also make the process easier for everyone involved because everything is pre-built. In this first article, we’re going to see the best tools to build your JavaScript SDK.

What is an SDK?

A software development kit (SDK) is a set of tools that provides a developer with the ability to build a custom app that can be added on, or connected to, another program. SDKs allow programmers to develop apps for a specific platform.

5 Principles of a Good SDK

Before developing an SDK, you must keep in mind the following principles:

Good DX (Developer Experience). It must be easy to use by other developers by providing simple interfaces.

Good Documentation. Developers will need a place to get started or get additional details about certain aspects or features of the SDK.

High Performance. It should have a minimal impact on your customer’s application performance.

Modernized. Keep it updated with the latest JavaScript specification, techniques, and tools.

Reliable. Control your packages’ versions and your codebase based on your SDK updates. Deliver solid features that work for developers/users as expected.

Tools

I’m describing here the best tools used by the big players’ SDKs. Let’s see how these tools can help us follow the principles of creating an SDK.

Lerna

Lerna is a tool that optimizes the workflow around managing multi-package repositories with git and npm.

Be Consistent

normalize package.json of all packages on pre-push/pre-commit
bump all packages version
sync dependencies across all modules
have composite tasks (install, run npm scripts) to ease maintenance
publish the packages to npm

Good Documentation

regenerate READMEs for root readme and all packages that are using

Lerna uses Git and NPM to create an optimal workflow for our SDK packages, via the Lerna CLI. It could include versioning, distribution, testing, and so much more. Essentially, Lerna will orchestrate our monorepo accordingly. In the next article, we will see each Lerna features we are going to use on our SDK.

Rollup

Rollup is a module bundler for JavaScript which compiles small pieces of code into something larger and more complex, such as a library or application.

High Performance

with the Tree Shaking technique, it generates small builds with the help of dead code elimination

Modernized

uses a standardized format (i.e., ES6 module format) to write your code
has node polyfills for import/export

Good DX

it generates bundle for old versions of JavaScript specification (like ES5) and new versions (like ES6)

We’re going to use Rollup to create our ES5 and ES6 bundles. In the next article, we will see how it will help us to optimize ES modules for faster native loading in modern browsers.

Codecov

Improve your code review workflow and quality. Codecov provides highly integrated tools to group, merge, archive, and compare coverage reports.

Reliable

it groups coverage reports isolating coverage metrics
overlay coverage reports directly in Github and Bitbucket for seamless integration into your workflow

We will integrate the Codecov with our CI to create the code coverage reports.

Jest

Jest is a delightful JavaScript Testing Framework with a focus on simplicity. It works with projects using: Babel, TypeScript, Node, React, Angular, Vue, and more!

Reliable

Jest comes with built-in matchers, spies, and its own extensive mocking library
Jest is fast. Very fast. When your tests are CPU bound, it can shave significant time from your test runs
Jest supports TypeScript via the ts-jest package

Jest will be our test framework to test each part of our SDK, including services, components, and the interface.

TypeDoc

TypeDoc converts comments in TypeScript source code into rendered HTML documentation or a JSON model. It is extensible and supports a variety of configurations. Available as a CLI or Node module.

Good Documentation

it completely eliminates the cognitive dissonance associated with writing documentation, since it’s generated on-the-fly
encourages developers, especially new ones, to provide meaningful code comments, which is already something that should be practiced

This library will allow us to generate the SDK documentation based on the comments from your TypeScript source code.

Prettier

Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary.

Reliable

no effort spent fixing formatting
no need to look up rules in a style guide
no time wasted discussing style in pull requests
when the style guide changes (or when it is first introduced) Prettier can automatically apply it across the whole codebase

Prettier will take care of our code format. With that we can ensure that our code will follow the same code standards and style.

TypeScript

TypeScript is an open-source programming language developed and maintained by Microsoft. It is a strict syntactical superset of JavaScript and adds optional static typing to the language.

Good DX

type inference, which gives some of the benefits of types, without actually using them
great tooling support with IntelliSense

Modernized

access to ES6 and ES7 features, before they become supported by major browsers

Reliable

the ability to compile down to a version of JavaScript that runs on all browsers

We’re going to write all our base code and the test code using TypeScript. We will see the best practices of how to create and expose our SDK types.

Conclusion

We saw in the article what are the state of art tools to build a JavaScript SDK. We’ll see in the next post the best practices to create our SDK code base, tests, and much more.