npm package: @kentico/kontent-model-generator
Description: This utility generates strongly-typed models based on Content Types in a Kentico Kontent project. The models are supposed to be used together with the Kentico Kontent Typescript SDK.
Author: richard sustek
Latest version: 5.0.0-3
Deprecated: Package has been renamed to @kontent-ai/model-generator. Please update your code to use the latest version

[![npm version](https://badge.fury.io/js/%40kentico%2Fkontent-model-generator.svg)](https://badge.fury.io/js/%40kentico%2Fkontent-model-generator)
[![Build](https://github.com/Kentico/kontent-model-generator-js/actions/workflows/main.yml/badge.svg)](https://github.com/Kentico/kontent-model-generator-js/actions/workflows/main.yml)
[![GitHub license](https://img.shields.io/github/license/Kentico/kontent-model-generator-js.svg)](https://github.com/Kentico/kontent-model-generator-js)

# Kontent Model Generator

The purpose of this project is to help you generate `Typescript models` based on [Kontent by Kentico](https://kontent.ai) item types. These models can be used with the [Kontent Delivery SDK](https://www.npmjs.com/package/@kentico/kontent-delivery) and enhances your experience by providing strongly typed models.

## Installation

Install package globally so you can use it anywhere:

`npm i @kentico/kontent-model-generator -g`

## Generate models with CLI

Go to folder where you want to create models and run:

`kontent-generate --projectId=xxx --apiKey=yyy`

You may specify other options like:

`kontent-generate --projectId=xxx --apiKey=yyy --addTimestamp=false --elementResolver=camelCase`

## Generate models in code

Apart from generating models via CLI, you may also generate models in code which also gives you some additional configuration options (such as using custom name resolver).

```typescript
import { generateModelsAsync } from '@kentico/kontent-model-generator';

await generateModelsAsync({
    sdkType: 'delivery',
    projectId: 'da5abe9f-fdad-4168-97cd-b3464be2ccb9',
    apiKey: 'yyy',
    addTimestamp: true,
    elementResolver: 'camelCase',
})
```

### Customizing generated file names

You may customize the way filenames are stored on file system using the `contentTypeFileResolver` and / or `taxonomyTypeFileResolver` configuration option:

```typescript
await generateModelsAsync({
  sdkType: 'delivery',
  projectId: 'da5abe9f-fdad-4168-97cd-b3464be2ccb9',
  apiKey: 'yyy',
  addTimestamp: true,
  elementResolver: 'camelCase',
  contentTypeFileResolver: (type) => `content_type_${type.system.codename}`,
  taxonomyTypeFileResolver: (type) => `taxonomy_${type.system.codename}`,
});
```

### Customizing generated content type names

You may customize name of content types using the `contentTypeResolver` configuration option and taxonomy types with the `taxonomyTypeResolver` option:

```typescript
await generateModelsAsync({
  sdkType: 'delivery',
  projectId: 'da5abe9f-fdad-4168-97cd-b3464be2ccb9',
  apiKey: 'yyy',
  addTimestamp: true,
  elementResolver: 'camelCase',
  contentTypeResolver: (type) => `${textHelper.toPascalCase(type.system.codename)}Model`,
  taxonomyTypeResolver: (type) => `${textHelper.toPascalCase(type.system.codename)}Taxonomy`,
});
```

## CLI Configuration

- `projectId` - Id of the Kontent project
- `apiKey`- Management API Key
- `addTimestamp`- Indicates if timestamp is added to generated models
- `elementResolver`- Name resolver for elements. Available options are: `camelCase`, `pascalCase`, `snakeCase`
- `contentTypeFileResolver`- Name resolver for content type filenames. Available options are: `camelCase`, `pascalCase`, `snakeCase`
- `taxonomyTypeFileResolver`- Name resolver for taxonomy filenames. Available options are: `camelCase`, `pascalCase`, `snakeCase`
- `contentTypeResolver`- Name resolver for content type names. Available options are: `camelCase`, `pascalCase`, `snakeCase`
- `taxonomyTypeResolver`- Name resolver for taxonomy type names. Available options are: `camelCase`, `pascalCase`, `snakeCase`
- `sdkType`- Type of sdk for which models are generated. Available options are: `delivery`
- `exportWebhooks` - Indicates if webhooks are exported
- `exportWorkflows` - Indicates if workflows are exported
- `exportAssetFolders` - Indicates if asset folders are exported
- `exportCollections` - Indicates if collections are exported
- `exportLanguages` - Indicates if languages are exported
- `exportRoles` - Indicates if roles are exported

## Example models

Generator creates file for each content type in your project. For example:

`movie.ts`

```typescript
import { IContentItem, Elements } from '@kentico/kontent-delivery';
import { Actor } from './actor';
import { ReleaseCategory } from '../taxonomies/releasecategory';

/**
 * Generated by '@kentico/kontent-model-generator@4.1.0' at 'Tue, 29 Mar 2022 07:19:43 GMT'
 *
 * Movie
 * Id: b0c0f9c2-ffb6-4e62-bac9-34e14172dd8c
 * Codename: movie
 */
export type Movie = IContentItem<{
  /**
   * Title (text)
   * Required: true
   * Id: 3473187e-dc78-eff2-7099-f690f7042d4a
   * Codename: title
   */
  title: Elements.TextElement;

  /**
   * Plot (rich_text)
   * Required: false
   * Id: f7ee4f27-27fd-a19b-3c5c-102aae1c50ce
   * Codename: plot
   */
  plot: Elements.RichTextElement;

  /**
   * Released (date_time)
   * Required: false
   * Id: 5ccf4644-0d65-5d96-9a32-f4ea21974d51
   * Codename: released
   */
  released: Elements.DateTimeElement;

  /**
   * Length (number)
   * Required: false
   * Id: 7e8ecfab-a419-27ee-d8ec-8adb76fd007c
   * Codename: length
   */
  length: Elements.NumberElement;

  /**
   * Poster (asset)
   * Required: false
   * Id: a39a7237-9503-a1ae-8431-5b6cdb85ae9d
   * Codename: poster
   */
  poster: Elements.AssetsElement;

  /**
   * Category (multiple_choice)
   * Required: false
   * Id: 9821c252-6414-f549-c17f-cc171dd87713
   * Codename: category
   */
  category: Elements.MultipleChoiceElement;

  /**
   * Stars (modular_content)
   * Required: false
   * Id: aa26a55d-19f8-7501-fea3-b0d9b1eeac71
   * Codename: stars
   */
  stars: Elements.LinkedItemsElement<Actor | Movie>;

  /**
   * SeoName (url_slug)
   * Required: false
   * Id: 756cc91a-a090-60f9-a7f0-f505bfbe046c
   * Codename: seoname
   */
  seoname: Elements.UrlSlugElement;

  /**
   * ReleaseCategory (taxonomy)
   * Required: false
   * Id: 65f2fd44-1856-bc2b-17c2-decb0635e3d2
   * Codename: releasecategory
   */
  releasecategory: Elements.TaxonomyElement<ReleaseCategory>;
}>;
```

`actor.ts`
```typescript
import { IContentItem, Elements } from '@kentico/kontent-delivery';
/**
 * Generated by '@kentico/kontent-model-generator@4.1.0' at 'Mon, 28 Mar 2022 14:36:32 GMT'
 *
 * Actor
 * Id: 58099989-319f-495f-aa36-cb3710854e36
 * Codename: actor
 */
export type Actor = IContentItem<{
  /**
   * Url (url_slug)
   * Required: false
   * Id: c8658782-f209-a573-9c85-430fb4e3e9f0
   * Codename: url
   */
  url: Elements.UrlSlugElement;

  /**
   * First name (text)
   * Required: true
   * Id: 14dd70e5-c42d-f111-9640-c82b443edf1d
   * Codename: first_name
   *
   * This is the first name of the actor
   */
  firstName: Elements.TextElement;

  /**
   * Last name (text)
   * Required: true
   * Id: 9f7a0dd4-af3a-95ca-0358-400c14ce7075
   * Codename: last_name
   */
  lastName: Elements.TextElement;

  /**
   * Photo (asset)
   * Required: false
   * Id: eaec9ba3-9624-6875-04ec-80d0b2e00781
   * Codename: photo
   */
  photo: Elements.AssetsElement;
}>;
```

`movietype.ts`
```typescript
/**
 * Generated by '@kentico/kontent-model-generator@4.1.0' at 'Mon, 28 Mar 2022 14:36:32 GMT'
 *
 * MovieType
 * Id: 365a17e6-1929-27ab-9f67-a9273c846717
 * Codename: movietype
 */
export type MovieType =
  | 'student'
  | 'film'
  | 'tv'
  | 'blockbuster'
  | 'cinema_only';
```

Generator also creates `_project.ts` file with strongly typed definitions for `languages`, `content types` and `taxonomies`. You can use these in your poject to easily access codenames / names of these objects instead of using strings as identifiers. 

## Example project structure

This model generator will also include additional project objects to help you code with strongly typed access. Supported objects are: `workflows`, `webhooks`, `roles`, `languages`, `contentTypes`, `assetFolders`, `collections`, `roles`, `taxonomies` 

Example `content_types.ts` output: 

```typescript
/**
 * Generated by '@kentico/kontent-model-generator@4.1.0' at 'Mon, 09 May 2022 12:59:46 GMT'
 *
 * Project name: Movie Database
 * Environment: Production
 * Project Id: da5abe9f-fdad-4168-97cd-b3464be2ccb9
 */
export const contentTypes = {
  /**
   * Actor
   * Last modified: Mon Mar 28 2022 09:35:29 GMT+0200 (Středoevropský letní čas)
   */
  actor: {
    codename: 'actor',
    id: '58099989-319f-495f-aa36-cb3710854e36',
    externalId: undefined,
    name: 'Actor',
    elements: {
      /**
       * Url (url_slug)
       */
      url: {
        codename: 'url',
        id: 'c8658782-f209-a573-9c85-430fb4e3e9f0',
        externalId: undefined,
        name: 'Url',
        required: false,
        type: 'url_slug',
      },

      /**
       * First name (text)
       *
       * This is the first name of the actor
       */
      first_name: {
        codename: 'first_name',
        id: '14dd70e5-c42d-f111-9640-c82b443edf1d',
        externalId: undefined,
        name: 'First name',
        required: true,
        type: 'text',
      },

      /**
       * Last name (text)
       */
      last_name: {
        codename: 'last_name',
        id: '9f7a0dd4-af3a-95ca-0358-400c14ce7075',
        externalId: undefined,
        name: 'Last name',
        required: true,
        type: 'text',
      },

      /**
       * Photo (asset)
       */
      photo: {
        codename: 'photo',
        id: 'eaec9ba3-9624-6875-04ec-80d0b2e00781',
        externalId: undefined,
        name: 'Photo',
        required: false,
        type: 'asset',
      },
    },
  },

  /**
   * Movie
   * Last modified: Mon Mar 28 2022 11:56:00 GMT+0200 (Středoevropský letní čas)
   */
  movie: {
    codename: 'movie',
    id: 'b0c0f9c2-ffb6-4e62-bac9-34e14172dd8c',
    externalId: undefined,
    name: 'Movie',
    elements: {
      /**
       * Title (text)
       */
      title: {
        codename: 'title',
        id: '3473187e-dc78-eff2-7099-f690f7042d4a',
        externalId: undefined,
        name: 'Title',
        required: true,
        type: 'text',
      },

      /**
       * Plot (rich_text)
       */
      plot: {
        codename: 'plot',
        id: 'f7ee4f27-27fd-a19b-3c5c-102aae1c50ce',
        externalId: undefined,
        name: 'Plot',
        required: false,
        type: 'rich_text',
      },

      /**
       * Released (date_time)
       */
      released: {
        codename: 'released',
        id: '5ccf4644-0d65-5d96-9a32-f4ea21974d51',
        externalId: undefined,
        name: 'Released',
        required: false,
        type: 'date_time',
      },

      /**
       * Length (number)
       */
      length: {
        codename: 'length',
        id: '7e8ecfab-a419-27ee-d8ec-8adb76fd007c',
        externalId: undefined,
        name: 'Length',
        required: false,
        type: 'number',
      },

      /**
       * Poster (asset)
       */
      poster: {
        codename: 'poster',
        id: 'a39a7237-9503-a1ae-8431-5b6cdb85ae9d',
        externalId: undefined,
        name: 'Poster',
        required: false,
        type: 'asset',
      },

      /**
       * Category (multiple_choice)
       */
      category: {
        codename: 'category',
        id: '9821c252-6414-f549-c17f-cc171dd87713',
        externalId: undefined,
        name: 'Category',
        required: false,
        type: 'multiple_choice',
      },

      /**
       * Stars (modular_content)
       */
      stars: {
        codename: 'stars',
        id: 'aa26a55d-19f8-7501-fea3-b0d9b1eeac71',
        externalId: undefined,
        name: 'Stars',
        required: false,
        type: 'modular_content',
      },

      /**
       * SeoName (url_slug)
       */
      seoname: {
        codename: 'seoname',
        id: '756cc91a-a090-60f9-a7f0-f505bfbe046c',
        externalId: undefined,
        name: 'SeoName',
        required: false,
        type: 'url_slug',
      },
    },
  },
};
```

Example `taxonomies.ts` output: 

```javascript
/**
 * Generated by '@kentico/kontent-model-generator@4.1.0' at 'Mon, 09 May 2022 12:59:46 GMT'
 *
 * Project name: Movie Database
 * Environment: Production
 * Project Id: da5abe9f-fdad-4168-97cd-b3464be2ccb9
 */
export const taxonomies = {
  /**
   * MovieType
   */
  movietype: {
    codename: 'movietype',
    id: '365a17e6-1929-27ab-9f67-a9273c846717',
    externalId: undefined,
    name: 'MovieType',
    terms: {
      student: {
        codename: 'student',
        id: 'b107e12c-124d-705f-1029-c0dfdd0b2438',
        externalId: undefined,
        name: 'Student',
        terms: {},
      },
      film: {
        codename: 'film',
        id: '5a2a1927-41a4-294f-5d89-cf0cc045e943',
        externalId: undefined,
        name: 'Film',
        terms: {
          tv: {
            codename: 'tv',
            id: '47511b09-6c39-fa04-ff59-7c47551e827f',
            externalId: undefined,
            name: 'TV',
            terms: {},
          },
          blockbuster: {
            codename: 'blockbuster',
            id: '875a4657-1dcd-0415-cb3a-892078f5991a',
            externalId: undefined,
            name: 'Blockbuster',
            terms: {},
          },
          cinema_only: {
            codename: 'cinema_only',
            id: 'e15c4e32-ab7c-57a2-1b66-d8e3566a1dd2',
            externalId: undefined,
            name: 'Cinema only',
            terms: {},
          },
        },
      },
    },
  },

  /**
   * ReleaseCategory
   */
  releasecategory: {
    codename: 'releasecategory',
    id: '09b6a348-0f86-7a68-4af3-7cab9a5c60b7',
    externalId: undefined,
    name: 'ReleaseCategory',
    terms: {
      global_release: {
        codename: 'global_release',
        id: '4acaf439-9f3a-f34a-6211-d3fc6ec7152e',
        externalId: undefined,
        name: 'Global release',
        terms: {},
      },
      us_only: {
        codename: 'us_only',
        id: 'b03d990a-55a9-601e-dd5c-aa2edc8698ca',
        externalId: undefined,
        name: 'US only',
        terms: {},
      },
      local_release: {
        codename: 'local_release',
        id: '37e55484-f0dc-14eb-bf2a-b0293a0d1b1f',
        externalId: undefined,
        name: 'Local release',
        terms: {},
      },
    },
  },
};
```
More examples can be found under `sample` folder in this repository.

## Contribution & Feedback

Contributions are welcomed. Simply make a pull request.