@flowup/contentful-types-generator

This package provides a CLI tool for automatically generating typings for Contentful spaces in Typescript. It uses the Contentful Management API to fetch all content types in a space, thus requiring a content management token in the configuration.

Types from contentful and @contentful/rich-text-types packages are used in the generated typings, which is why these packages are listed as peer dependencies (though the latter is only needed if some field uses rich text).

The output includes an interface for each content type, as well as an interface for the space itself. It is designed to be used in conjunction with the @flowup/contentful-client package, which provides a type-safe wrapper for the Contentful SDK.

Installation

Local:

npm install --save-dev @flowup/contentful-types-generator

Global:

sudo npm install -g @flowup/contentful-types-generator

Configuration

Create a contentful-config.json file for specifying Contentful spaces and tweaking the output format.

The structure is as follows (see JSON schema for more details):

{
  "contentfulSpaces": {
    "<name for 1st space>": {
      "spaceId": "<space ID>",
      "accessToken": "<access token for Contentful Management API>",
      "environment": "<environment (e.g. master)>",
      "host": "<optional custom host>"
    },
    "<name for 2nd space>": {
      "spaceId": "<space ID>",
      "accessToken": "<access token for Contentful Management API>",
      "environment": "<environment>",
      "host": "<optional custom host>"
    }
  },
  "outputDirectory": "<optional target path for generated files>",
  "typePrefix": "<optional prefix for interface names (e.g. Cf)>",
  "typeSuffix": "<optional suffix for interface names (e.g. Model)>"
}

Environment variables

It is possible to reference environment variables instead of hard-coding values in the JSON configuration. This enables some values (e.g. access tokens) to stay secret and dynamic, since they aren't committed to the repo.

An example configuration might then look like:

{
  "contentfulSpaces": {
    "app": {
      "spaceId": "${CF_SPACE_ID}",
      "accessToken": "${CF_ACCESS_TOKEN}",
      "environment": "master"
    }
  },
  "outputDirectory": "contentful/"
}

Setting environment variables via a local .env file is also supported (see dotenv).

Usage

If installed locally:

npx generate-contentful-types

If installed globally:

generate-contentful-types

When used with @flowup/contentful-client, use the generated Contentful space interface as the generic type when creating the client to enable type-checking. For example:

import { ContentfulClient } from '@flowup/contentful-client';
import { CfAppSpaceModel } from './contentful/app-space/cf-app-space.model';

const contentfulClient = new ContentfulClient<CfAppSpaceModel>({
  /* config */
});

Output

As an example, the generated Typescript files for a Contentful space storing books might look like this:

• contentful/book-reviews-space/cf-book-reviews-space.model.ts

  /* tslint:disable */
  /**
   * This file was automatically generated by contentful-types-generator.
   * DO NOT MODIFY IT BY HAND. Instead, modify the contentful-config.json file if needed,
   * and run generate-contentful-types to regenerate this file.
   */
  
  import { CfAuthorModel } from './types/cf-author.model';
  import { CfBookModel } from './types/cf-book.model';
  import { CfReviewModel } from './types/cf-review.model';
  
  export interface CfBookReviewsSpaceModel {
    author: CfAuthorModel;
    book: CfBookModel;
    review: CfReviewModel;
  }

• contentful/book-reviews-space/types/cf-book.model.ts

  /* tslint:disable */
  /**
   * This file was automatically generated by contentful-types-generator.
   * DO NOT MODIFY IT BY HAND. Instead, modify the contentful-config.json file if needed,
   * and run generate-contentful-types to regenerate this file.
   */
  
  import { Asset, Entry } from 'contentful';
  import { CfAuthorModel } from './cf-author.model';
  import { CfReviewModel } from './cf-review.model';
  
  export interface CfBookModel {
    author?: Entry<CfAuthorModel>;
    cover?: Asset;
    reviews?: Entry<CfReviewModel>[];
    title: string;
  }

• contentful/book-reviews-space/types/cf-author.model.ts

  /* tslint:disable */
  /**
   * This file was automatically generated by contentful-types-generator.
   * DO NOT MODIFY IT BY HAND. Instead, modify the contentful-config.json file if needed,
   * and run generate-contentful-types to regenerate this file.
   */
  
  import { Document } from '@contentful/rich-text-types';
  
  export interface CfAuthorModel {
    bio?: Document;
    dateOfBirth?: string;
    name: string;
  }

• contentful/book-reviews-space/types/cf-review.model.ts

  /* tslint:disable */
  /**
   * This file was automatically generated by contentful-types-generator.
   * DO NOT MODIFY IT BY HAND. Instead, modify the contentful-config.json file if needed,
   * and run generate-contentful-types to regenerate this file.
   */
  
  import { Entry } from 'contentful';
  import { CfAuthorModel } from './cf-author.model';
  
  /* Book review */
  export interface CfReviewModel {
    author: Entry<CfAuthorModel>;
    rating: 'Great' | 'Average' | 'Poor';
    text?: string;
  }