cf-content-types-generator

TS contentful content types generator

A CLI to generate Typescript definitions based on JSON export generated with contentful CLI.

Table of Contents

• Installation
• Usage
  • Example
    • Local
    • Remote
  • Input
  • Output
• Renderer
  • Default Renderer
  • Localized Renderer
• Direct Usage
• Browser Usage

Installation

npm install cf-content-types-generator

Usage

Contentful Content Types (TS Definitions) Generator

USAGE
  $ cf-content-types-generator [FILE]

ARGUMENTS
  FILE  local export (.json)

OPTIONS
  -e, --environment=environment  environment
  -h, --help                     show CLI help
  -o, --out=out                  output directory
  -p, --preserve                 preserve output folder
  -l, --localized                add localized types
  -s, --spaceId=spaceId          space id
  -t, --token=token              management token
  -v, --version                  show CLI version

Example

Local

Use a local JSON file to load contentTypes. Flags for spaceId, token and environement will be ignored.

Will print result to console

cf-content-types-generator path/to/exported/file.json

in a real world scenario, you would pipe the result to a file.

Will store resulting files in target directory

cf-content-types-generator path/to/exported/file.json path/to/target/out/directory 

Remote

If no file arg provided, remote mode es enabled. spaceId and token flags need to be set.

cf-content-types-generator -s 2l3j7k267xxx  -t CFPAT-64FtZEIOruksuaE_Td0qBvHdELNWBCC0fZUWq1NFxxx

Input

As input a json file with a contentTypes field is expected:

{
  "contentTypes": [
    {
      "sys": {
        "id": "artist",
        "type": "ContentType"
      },
      "displayField": "name",
      "name": "Artist",
      "fields": [
        {
          "id": "name",
          "name": "Name",
          "type": "Symbol",
          "required": true,
          "validations": [
            {
              "unique": true
            }
          ]
        },
        {
          "id": "profilePicture",
          "name": "Profile Picture",
          "type": "Link",
          "required": false,
          "validations": [
            {
              "linkMimetypeGroup": [
                "image"
              ]
            }
          ],
          "linkType": "Asset"
        },
        {
          "id": "bio",
          "name": "Bio",
          "type": "RichText",
          "required": false,
          "validations": [
            {
              "nodes": {
              }
            },
            {
              "enabledMarks": [
              ],
              "message": "Marks are not allowed"
            },
            {
              "enabledNodeTypes": [
              ],
              "message": "Nodes are not allowed"
            }
          ]
        }
      ]
    },
    {
      "sys": {
        "id": "artwork",
        "type": "ContentType"
      },
      "displayField": "name",
      "name": "Artwork",
      "fields": [
        {
          "id": "name",
          "name": "Name",
          "type": "Symbol",
          "required": true,
          "validations": [
          ]
        },
        {
          "id": "type",
          "name": "Type",
          "type": "Symbol",
          "required": false,
          "validations": [
            {
              "in": [
                "print",
                "drawing",
                "painting"
              ],
              "message": "Hello - this is a custom error message."
            }
          ]
        },
        {
          "id": "preview",
          "name": "Preview",
          "type": "Array",
          "required": false,
          "validations": [
          ],
          "items": {
            "type": "Link",
            "validations": [
              {
                "linkMimetypeGroup": [
                  "image",
                  "audio",
                  "video"
                ]
              }
            ],
            "linkType": "Asset"
          }
        },
        {
          "id": "artist",
          "name": "Artist",
          "type": "Link",
          "required": true,
          "validations": [
            {
              "linkContentType": [
                "artist"
              ]
            }
          ],
          "linkType": "Entry"
        }
      ]
    }
  ]
}

This example shows a subset of the actual payload provided by contentful's cli export command.

Output

import * as CFRichTextTypes from "@contentful/rich-text-types";
import * as Contentful from "contentful";

export interface TypeArtistFields {
    name: Contentful.EntryFields.Symbol;
    profilePicture?: Contentful.Asset;
    bio?: CFRichTextTypes.Block | CFRichTextTypes.Inline;
}

export type TypeArtist = Contentful.Entry<TypeArtistFields>;

export interface TypeArtworkFields {
    name: Contentful.EntryFields.Symbol;
    type?: "print" | "drawing" | "painting";
    preview?: Contentful.Asset[];
    artist: Contentful.Entry<TypeArtistFields>;
}

export type TypeArtwork = Contentful.Entry<TypeArtworkFields>;

This all only works if you add the contentful package to your target project to get all relevant type definitions.

Renderer

Extend the default BaseContentTypeRenderer class, or implement the ContentTypeRenderer interface for custom rendering.

Relevant methods to override:

Methods	Description	Override
render	Enriches a SourceFile with all relevant nodes	To control content type rendering (you should know what you're doing)
getContext	Returns new render context object	To define custom type renderer and custom module name function
addDefaultImports	Define set of default imports added to every file	To control default imported modules
renderField	Returns a PropertySignatureStructure representing a field property	To control Field property rendering
renderFieldType	Returns a string representing a field type	To control field type rendering (recommended)
renderEntry	Returns a TypeAliasDeclarationStructure representing an entry type alias	To control entry type alias rendering
renderEntryType	Returns a string representing an entry type	To control entry type rendering (recommended)

Table represents order of execution

Set content type renderers:

import CFDefinitionsBuilder from "cf-content-types-generator/lib/cf-definitions-builder";
import {DefaultContentTypeRenderer, LocalizedContentTypeRenderer} from 'cf-content-types-generator/lib/renderer/type';

const builder = new CFDefinitionsBuilder([
    new DefaultContentTypeRenderer(),
    new LocalizedContentTypeRenderer()
]); 

DefaultContentTypeRenderer

A renderer to render type fields and entry definitions. For most scenarios, this renderer is sufficient. If no custom renderers given, CFDefinitionsBuilder creates a DefaultContentTypeRenderer by default.

LocalizedContentTypeRenderer

Add additional types for localized fields. It adds utility types to transform fields into localized fields for given locales More details on the utility types can be found here: Issue 121

Example output

export interface TypeCategoryFields {
    title: Contentful.EntryFields.Text;
    icon?: Contentful.Asset;
    categoryDescription?: Contentful.EntryFields.Text;
}

export type TypeCategory = Contentful.Entry<TypeCategoryFields>;

export type LocalizedTypeCategoryFields<Locales extends keyof any> = LocalizedFields<TypeCategoryFields, Locales>;

export type LocalizedTypeCategory<Locales extends keyof any> = LocalizedEntry<TypeCategory, Locales>;

Example usage

const localizedCategory: LocalizedTypeCategory<'DE-de' | 'En-en'> = {
    fields: {
        categoryDescription: {
            "DE-de": 'german description',
            "En-en": 'english description'
        }
    }
}

Direct Usage

If you're not a CLI person, or you want to integrate it with your tooling workflow, you can also directly use the CFDefinitionsBuilder from cf-definitions-builder.ts

import CFDefinitionsBuilder from "cf-content-types-generator/lib/cf-definitions-builder";

const stringContent = new CFDefinitionsBuilder()
    .appendType({
        id: "rootId",
        name: "Root Name",
        sys: {
            id: "sysId",
            type: "ContentType",
        }, fields: [{
            id: "myFieldId",
            type: "Symbol",
            required: true,
            validations: []            
        }]
    })
    .toString();

Browser Usage

You can use CFDefinitionsBuilder also in a browser environment.

Example: TS Content Types Generator App