# `@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](https://www.contentful.com/developers/docs/references/content-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`](https://www.npmjs.com/package/@flowup/contentful-client) package, which provides a type-safe wrapper for the Contentful SDK.

## Installation

Local:

```shell script
npm install --save-dev @flowup/contentful-types-generator
```

Global:

```shell script
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](src/types/config.json) for more details):

```json
{
  "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:

```json
{
  "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`](https://www.npmjs.com/package/dotenv)).

## Usage

If installed locally:

```shell script
npx generate-contentful-types
```

If installed globally:

```shell script
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:

```typescript
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`

  ```typescript
  /* 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`

  ```typescript
  /* 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`

  ```typescript
  /* 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`

  ```typescript
  /* 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;
  }
  ```