Blog / Announcements

Introducing the Kentico Cloud TypeScript SDK


by Christopher Jennings

Aug 24, 2017

Delivery API is a REST endpoint, but sometimes you want more than just a simple REST API. If you're developing a server- or client-side JavaScript application, the Kentico Cloud Delivery TypeScript SDK can help.

Why TypeScript?

For those not familiar with TypeScript, it’s a Microsoft-run open source project and superset of JavaScript that compiles with plain JavaScript. It has gained mainstream support across many important projects (open source or proprietary) as it helps make projects more scalable and enables IDEs (like Microsoft’s own Visual Studio Code) to provide productivity enhancements for JavaScript, like code-completion and the “go to definition” functionality. The TypeScript SDK enables you to leverage these benefits and develop your projects faster.

What Does the Kentico Cloud TypeScript SDK Offer?

The Kentico Cloud TypeScript SDK offers tooling that enables the clean and easy consumption of the Delivery API by providing three core features:

  • Strongly-typed base models for the core Delivery objects
  • An extensible Delivery client API that makes querying easy
  • Customizable resolvers for resolving URL slugs and modular content

In addition to these SDK features, there’s also a code generator available to help you easily and automatically generate strongly typed models for your Kentico Cloud project. This can help you save some serious time building out the models for your content types. Both the SDK and the code generator are available as npm packages. 

Strongly-typed Base Models

The base models provided in the SDK enable you to get moving quickly. They cover the basics, like the base content item, the system properties, and field types (text field, Multiple choice field, Date/Time field, etc.). These make it easy to build out your content type models easily. As previously mentioned, you can use the Kentico Cloud model generator utility to generate your models automatically. For example, a simple blog content item might look something like:

import { ContentItem, Fields, IContentItem } from 'kentico-cloud-delivery-typescript-sdk';

/**
 * This class was generated by 'kentico-cloud-model-generator-utility' module.
 * You can substitute instances of 'IContentItem' with a model defined in other class
 * to get access to all properties. This is applicable only if you know what item type the field contains.
 */
export class Blog extends ContentItem {

    public title: Fields.TextField;
    public publicationDate: Fields.DateTimeField;
    public teaserImage: Fields.AssetsField;
    public summary: Fields.RichTextField;
    public bodyCopy: Fields.RichTextField;
    public metaKeywords: Fields.TextField;
    public metaDescription: Fields.TextField;
    
    constructor(){
        super({
            propertyResolver: ((fieldName: string) => {
                
                if (fieldName === 'publication_date'){
                    return 'publicationDate';
                }

                if (fieldName === 'teaser_image'){
                    return 'teaserImage';
                }

                if (fieldName === 'body_copy'){
                    return 'bodyCopy';
                }

                if (fieldName === 'meta_keywords'){
                    return 'metaKeywords';
                }

                if (fieldName === 'meta_description'){
                    return 'metaDescription';
                }

            })
        })    
    }
    
}

For more information on creating models, see the ReadMe on GitHub.

Extensible Client API

The TypeScript SDK also provides a robust implementation of the Delivery API. It provides a configurable Delivery client that supports: 

Using that same blog post model, the code to retrieve all blog posts would look like this:

KenticoCloudClient().items<BlogPost>()
            .type('blog')
            .orderParameter('elements.publication_date', SortOrder.desc)
            .get()
            .subscribe(response => {
                console.log(response.items);
            });

Customizable Resolvers

There are three main resolvers that you can customize for your needs. The first is the property resolver, which allows you to map the Kentico Cloud field names to JavaScript class properties. This is important for when you need to map a field to something other than its Kentico Cloud name. For example, “body_copy” in Kentico Cloud becomes “bodyCopy” in JavaScript. The code generator uses the property resolver to map name that match that pattern automatically. The second resolver is for resolving URL slugs, which enables you to define how a content type is converted into a usable URL. This can be done globally for a content type or it can be specified at the time of a query. The last main resolver is the modular content resolver, which makes it easy to use modular content in rich-text fields. Like the URL slug resolver, this can be done globally or per query. 

How Do I Use It?

This probably sounds a bit like a broken record, but if you’re already familiar with TypeScript, the Kentico Cloud TypeScript SDK’s ReadMe on Github gives you detailed information on how to use it. If you’re not familiar with TypeScript, check out TypeScript’s 5-minute guide to get the basics, then have a look at this simple JavaScript application Richard Sustek built to show the foundations of the TypeScript SDK. This simple sample uses Browserify to compile TypeScript into plain JavaScript. Only the essentials needed to demonstrate the basics of the Kentico Cloud TypeScript SDK are included. This approach allows you to focus on the SDK, rather than how it integrates with other frameworks. 

Richard also built a second, more complex example. This example demonstrates the use of the Kentico Cloud TypeScript SDK in a simple Angular app. If you’re familiar with Angular, this might be a good place to start. 

If React is more your style, stay tuned! I'm putting together a sample site built on React with the TypeScript SDK. It's designed to show a complete example using the default content you get when you first sign up for Kentico Cloud.

What’s Next?

The Kentico Cloud TypeScript SDK will continue to evolve based on Kentico Cloud updates and community direction, feedback, and pull requests. The Kentico Cloud team is also looking to add SDKs for other programming languages. If you have any ideas or an SDK you developed that you want to make available to everyone, let us know in the forums! In the meantime, why not grab the latest version of the SDK and the generator utility from npm and get started on your own project!

Kentico Cloud Delivery TypeScript SDK
on GitHub: GitHub version
on npm: npm version

Kentico Cloud Model Generator Utility:
on GitHub: GitHub version
on npm: npm version