Node

TypeScript

Your JavaScript library should be written in TypeScript. This will allow TypeScript applications and JavaScript alike to use your SDK.

Environment support

• All LTS versions of Node should be supported by your SDK.
• Your SDK should support all TypeScript releases above 3.1.

Publishing

All Node SDKs should be publicly available on an IBM GitHub organization. The releases of these SDKs should be published on NPM. Your NPM package should be scoped with @ibm-cloud, so that NPM users can find similar packages across NPM.

To avoid unnecessary redundancy, package names MUST NOT include the term "node". For example, the Platform Services Node SDK would use the NPM package name of @ibm-cloud/platform-services, not @ibm-cloud/platform-services-node-sdk.

Your SDK should follow the semantic versioning best practices.

Community support

Allow your users to find answers to their questions. Users should be able to report problems on GitHub by raising issues on your SDK repository. Having a public Slack channel is a great way to engage with users who have questions specific to their use cases.

Style guidelines

You should follow the Airbnb conventions, with two spaces for indentation.

You should use the standard development tools for JavaScript to check style and code coverage.

Streaming support

If your API takes fileType parameters, you should accept Node.js streams as an input type.

Dependencies

Use a well-defined, well-documented request library that includes browser support, like axios, superagent, or node-fetch.

Objects for arguments

The methods in your SDK should take a JSON object as an argument. This object will contain the options for the requests, instead of using positional parameters in the function definition.

Async architecture

All network calls from your SDK should be asynchronous. All asynchronous calls should be handled using Promises, not callbacks.

Standard features

Authentication

You are not required to use a particular library to provide the authentication for your service.

Your SDK must support all of the authentication methods for your service.

Configuration

In the interests of making your SDK easy to consume and cloud native, you should provide the ability to read in environment variables. Abstracting the application logic from the environment logic allows your users to focus on using your service capabilities their applications.

If you build this capability into your SDK, you must document this mechanism clearly with examples.

Using node-sdk-core

IBM node-sdk-core provides configuration and authentication support. You can use the existing functionality provided by this dependency in your SDK.

Documentation

Your SDK is not useful if your audience cannot understand how to consume it in order to do the basic operations for your service. Your SDK needs to contain the following resources to help your users:

• README.md
• NPM metadata
• Contributor guidelines
• Code Samples
• Service documentation

Samples

For your JavaScript SDK, you will want some simple code samples and explanations of what each does. Linking out to the API reference documentation for more advanced use is strongly encouraged.

At minimum, the samples should be included in the README.md file. They should communicate how to install the library, and complete the basic operations provided by your API.

The samples should include JavaScript and TypeScript examples where applicable as well as simple installation and initialization instructions for Angular and React.