{"id":10666,"library":"contentful-typescript-codegen","title":"Contentful TypeScript Codegen","description":"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.","status":"active","version":"3.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/intercom/contentful-typescript-codegen","tags":["javascript","typescript"],"install":[{"cmd":"npm install contentful-typescript-codegen","lang":"bash","label":"npm"},{"cmd":"yarn add contentful-typescript-codegen","lang":"bash","label":"yarn"},{"cmd":"pnpm add contentful-typescript-codegen","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency if the environment configuration file (getContentfulEnvironment.ts) is written in TypeScript.","package":"ts-node","optional":false},{"reason":"Required as a peer dependency for formatting the generated TypeScript files according to the project's Prettier configuration.","package":"prettier","optional":true},{"reason":"Implicitly required by the user's getContentfulEnvironment.js/ts file to connect to the Contentful Management API and fetch content models.","package":"contentful-management","optional":false}],"imports":[{"note":"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.","wrong":"import contentfulCodegen from 'contentful-typescript-codegen'","symbol":"CLI Tool","correct":"npx contentful-typescript-codegen --output path/to/types.d.ts"},{"note":"This type is provided by the package to help strongly type the function exported by your `getContentfulEnvironment.ts` file.","symbol":"EnvironmentGetter","correct":"import { EnvironmentGetter } from 'contentful-typescript-codegen'"},{"note":"The generated types (e.g., IBlogPost, IPage) are imported from the output file specified in your CLI command (e.g., `contentful.d.ts`).","symbol":"Generated Types (Example)","correct":"import { IBlogPost, IPage, TypeBlogPostFields } from '@types/generated/contentful'"}],"quickstart":{"code":"{\n  \"name\": \"my-contentful-app\",\n  \"version\": \"1.0.0\",\n  \"description\": \"\",\n  \"main\": \"index.js\",\n  \"scripts\": {\n    \"contentful-codegen\": \"contentful-typescript-codegen --output @types/generated/contentful.d.ts\"\n  },\n  \"devDependencies\": {\n    \"contentful-typescript-codegen\": \"^3.4.0\",\n    \"contentful-management\": \"^10.0.0\",\n    \"ts-node\": \"^10.0.0\",\n    \"typescript\": \"^5.0.0\",\n    \"prettier\": \"^2.0.0\"\n  }\n}\n\n// File: getContentfulEnvironment.ts\nimport { strict as assert } from \"assert\";\nimport contentfulManagement from \"contentful-management\";\nimport { EnvironmentGetter } from \"contentful-typescript-codegen\";\n\nconst CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN = process.env.CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN ?? '';\nconst CONTENTFUL_SPACE_ID = process.env.CONTENTFUL_SPACE_ID ?? '';\nconst CONTENTFUL_ENVIRONMENT = process.env.CONTENTFUL_ENVIRONMENT ?? '';\n\nassert(CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN, \"CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN is required.\");\nassert(CONTENTFUL_SPACE_ID, \"CONTENTFUL_SPACE_ID is required.\");\nassert(CONTENTFUL_ENVIRONMENT, \"CONTENTFUL_ENVIRONMENT is required.\");\n\nconst getContentfulEnvironment: EnvironmentGetter = () => {\n  const contentfulClient = contentfulManagement.createClient({\n    accessToken: CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN,\n  });\n\n  return contentfulClient\n    .getSpace(CONTENTFUL_SPACE_ID)\n    .then((space) => space.getEnvironment(CONTENTFUL_ENVIRONMENT));\n};\n\nexport = getContentfulEnvironment;\n\n// To run: \n// 1. Set environment variables: CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN, CONTENTFUL_SPACE_ID, CONTENTFUL_ENVIRONMENT\n// 2. yarn install\n// 3. yarn contentful-codegen","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade the package: `yarn upgrade contentful-typescript-codegen` or `npm update contentful-typescript-codegen`.","message":"Version 3.4.1 includes security fixes. It is strongly recommended to update to at least this version or newer to mitigate potential vulnerabilities.","severity":"breaking","affected_versions":"<3.4.1"},{"fix":"Install `ts-node`: `yarn add --dev ts-node` or `npm install --save-dev ts-node`.","message":"Using a TypeScript configuration file (`getContentfulEnvironment.ts`) for fetching your Contentful environment requires `ts-node` to be installed as a peer dependency.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Install `prettier`: `yarn add --dev prettier` or `npm install --save-dev prettier`.","message":"For the generated types to be formatted correctly, `prettier` must be installed as a peer dependency in your project.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Create the environment configuration file and ensure `contentful-management` is installed: `yarn add --dev contentful-management` or `npm install --save-dev contentful-management`.","message":"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`.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `ts-node` as a development dependency: `yarn add --dev ts-node` or `npm install --save-dev ts-node`.","cause":"Attempting to use a `getContentfulEnvironment.ts` file without `ts-node` installed.","error":"Error: Cannot find module 'ts-node'"},{"fix":"Install `contentful-management` as a development dependency: `yarn add --dev contentful-management` or `npm install --save-dev contentful-management`.","cause":"The `getContentfulEnvironment.js` or `getContentfulEnvironment.ts` file tries to import `contentful-management` but it's not installed.","error":"Error: Cannot find module 'contentful-management'"},{"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.","cause":"Required environment variables (like access token, space ID, or environment name) are not set when the codegen tool runs.","error":"AssertionError: CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN is required."},{"fix":"Create the target directory before running the codegen command (e.g., `mkdir -p @types/generated`).","cause":"The specified output directory for the generated types does not exist.","error":"ENOENT: no such file or directory, open 'path/to/types.d.ts'"}],"ecosystem":"npm"}