Contentful TypeScript Codegen

3.4.0 · active · verified Sun Apr 19

Contentful TypeScript Codegen is a utility that generates TypeScript type definitions directly from a Contentful environment's content models. It transforms Content Types into interfaces, locales into string union types, and automatically handles links to Contentful Assets and Rich Text fields. The current stable version is 3.4.0, though 3.4.1 includes security fixes, suggesting a maintenance release cadence with feature updates being less frequent. A key differentiator is its ability to automatically generate documentation comments from Contentful descriptions, resolve linked entries to their respective interfaces, and expand Contentful validations into TypeScript union types. It also integrates with Prettier to format generated output according to a project's configuration, ensuring consistency. This tool is primarily a CLI for build-time type generation.

Common errors

```
Error: Cannot find module 'ts-node'
```
cause Attempting to use a `getContentfulEnvironment.ts` file without `ts-node` installed.

fix Install `ts-node` as a development dependency: `yarn add --dev ts-node` or `npm install --save-dev ts-node`.
```
Error: Cannot find module 'contentful-management'
```
cause The `getContentfulEnvironment.js` or `getContentfulEnvironment.ts` file tries to import `contentful-management` but it's not installed.

fix Install `contentful-management` as a development dependency: `yarn add --dev contentful-management` or `npm install --save-dev contentful-management`.
```
AssertionError: CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN is required.
```
cause Required environment variables (like access token, space ID, or environment name) are not set when the codegen tool runs.

fix Ensure `CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN`, `CONTENTFUL_SPACE_ID`, and `CONTENTFUL_ENVIRONMENT` are set in your shell or `.env` file before running the codegen script.
```
ENOENT: no such file or directory, open 'path/to/types.d.ts'
```
cause The specified output directory for the generated types does not exist.

fix Create the target directory before running the codegen command (e.g., `mkdir -p @types/generated`).

Warnings

breaking Version 3.4.1 includes security fixes. It is strongly recommended to update to at least this version or newer to mitigate potential vulnerabilities.
Fix: Upgrade the package: `yarn upgrade contentful-typescript-codegen` or `npm update contentful-typescript-codegen`.
gotcha Using a TypeScript configuration file (`getContentfulEnvironment.ts`) for fetching your Contentful environment requires `ts-node` to be installed as a peer dependency.
Fix: Install `ts-node`: `yarn add --dev ts-node` or `npm install --save-dev ts-node`.
gotcha For the generated types to be formatted correctly, `prettier` must be installed as a peer dependency in your project.
Fix: Install `prettier`: `yarn add --dev prettier` or `npm install --save-dev prettier`.
gotcha You must create a `getContentfulEnvironment.js` or `getContentfulEnvironment.ts` file in your project root that exports a promise resolving to your Contentful environment. This file will implicitly require `contentful-management`.
Fix: Create the environment configuration file and ensure `contentful-management` is installed: `yarn add --dev contentful-management` or `npm install --save-dev contentful-management`.

Install

npm install contentful-typescript-codegen npm
yarn add contentful-typescript-codegen yarn
pnpm add contentful-typescript-codegen pnpm

Imports

CLI Tool
wrong:
```
import contentfulCodegen from 'contentful-typescript-codegen'
```
correct:
```
npx contentful-typescript-codegen --output path/to/types.d.ts
```
This package is a command-line utility; it is not typically imported into application code. Its primary usage is via `npx` or a package.json script.
EnvironmentGetter
```
import { EnvironmentGetter } from 'contentful-typescript-codegen'
```
This type is provided by the package to help strongly type the function exported by your `getContentfulEnvironment.ts` file.
Generated Types (Example)
```
import { IBlogPost, IPage, TypeBlogPostFields } from '@types/generated/contentful'
```
The generated types (e.g., IBlogPost, IPage) are imported from the output file specified in your CLI command (e.g., `contentful.d.ts`).

Quickstart

This quickstart demonstrates setting up `contentful-typescript-codegen` in a project, including the necessary `package.json` script, the `getContentfulEnvironment.ts` configuration file for fetching your Contentful schema, and how to execute the code generation. It highlights the use of `EnvironmentGetter` and the importance of environment variables.

{
  "name": "my-contentful-app",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "contentful-codegen": "contentful-typescript-codegen --output @types/generated/contentful.d.ts"
  },
  "devDependencies": {
    "contentful-typescript-codegen": "^3.4.0",
    "contentful-management": "^10.0.0",
    "ts-node": "^10.0.0",
    "typescript": "^5.0.0",
    "prettier": "^2.0.0"
  }
}

// File: getContentfulEnvironment.ts
import { strict as assert } from "assert";
import contentfulManagement from "contentful-management";
import { EnvironmentGetter } from "contentful-typescript-codegen";

const CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN = process.env.CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN ?? '';
const CONTENTFUL_SPACE_ID = process.env.CONTENTFUL_SPACE_ID ?? '';
const CONTENTFUL_ENVIRONMENT = process.env.CONTENTFUL_ENVIRONMENT ?? '';

assert(CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN, "CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN is required.");
assert(CONTENTFUL_SPACE_ID, "CONTENTFUL_SPACE_ID is required.");
assert(CONTENTFUL_ENVIRONMENT, "CONTENTFUL_ENVIRONMENT is required.");

const getContentfulEnvironment: EnvironmentGetter = () => {
  const contentfulClient = contentfulManagement.createClient({
    accessToken: CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN,
  });

  return contentfulClient
    .getSpace(CONTENTFUL_SPACE_ID)
    .then((space) => space.getEnvironment(CONTENTFUL_ENVIRONMENT));
};

export = getContentfulEnvironment;

// To run: 
// 1. Set environment variables: CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN, CONTENTFUL_SPACE_ID, CONTENTFUL_ENVIRONMENT
// 2. yarn install
// 3. yarn contentful-codegen

view raw JSON →