{"id":13903017,"url":"https://github.com/contentful-userland/cf-content-types-generator","last_synced_at":"2026-04-02T17:53:22.784Z","repository":{"id":38034724,"uuid":"242743214","full_name":"contentful-userland/cf-content-types-generator","owner":"contentful-userland","description":"Generate TS declarations for content types","archived":false,"fork":false,"pushed_at":"2025-09-15T18:58:08.000Z","size":1603,"stargazers_count":134,"open_issues_count":19,"forks_count":30,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-09-15T20:28:41.880Z","etag":null,"topics":["builder","cli","contentful","generator","type-tool","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/contentful-userland.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-02-24T13:27:55.000Z","updated_at":"2025-09-15T18:31:54.000Z","dependencies_parsed_at":"2022-07-16T09:30:48.661Z","dependency_job_id":"59682d9d-532f-437d-9a78-9fa7c2a9ccb7","html_url":"https://github.com/contentful-userland/cf-content-types-generator","commit_stats":{"total_commits":214,"total_committers":16,"mean_commits":13.375,"dds":0.4532710280373832,"last_synced_commit":"d26dc7532504a3bccb47908aad68fb1178cb6ed2"},"previous_names":["contentful-labs/cf-content-types-generator"],"tags_count":62,"template":false,"template_full_name":null,"purl":"pkg:github/contentful-userland/cf-content-types-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentful-userland%2Fcf-content-types-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentful-userland%2Fcf-content-types-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentful-userland%2Fcf-content-types-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentful-userland%2Fcf-content-types-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/contentful-userland","download_url":"https://codeload.github.com/contentful-userland/cf-content-types-generator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentful-userland%2Fcf-content-types-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29593911,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T18:54:29.675Z","status":"ssl_error","status_checked_at":"2026-02-18T18:50:50.517Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["builder","cli","contentful","generator","type-tool","typescript"],"created_at":"2024-08-06T22:01:33.742Z","updated_at":"2026-04-02T17:53:22.767Z","avatar_url":"https://github.com/contentful-userland.png","language":"TypeScript","funding_links":[],"categories":["cli"],"sub_categories":[],"readme":"# cf-content-types-generator\n\nGenerate TypeScript types from your Contentful content model, either from a local `contentful space export` JSON file or by fetching the model directly from Contentful.\n\nUse the generated types with `contentful.js` v10+ for safer queries, autocomplete, and less schema drift between Contentful and your app.\n\n\u003e As of v3.x, pre-v10 output is removed. If you are upgrading from `2.x`, modern `contentful.js` typing is now the default and only output model.\n\n[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)\n[![Version](https://img.shields.io/npm/v/cf-content-types-generator.svg)](https://npmjs.org/package/cf-content-types-generator)\n[![Downloads/week](https://img.shields.io/npm/dw/cf-content-types-generator.svg)](https://npmjs.org/package/cf-content-types-generator)\n[![License](https://img.shields.io/npm/l/cf-content-types-generator.svg)](https://github.com/contentful-userland/cf-content-types-generator/blob/master/package.json)\n[![Coverage Status](https://coveralls.io/repos/github/contentful-userland/cf-content-types-generator/badge.svg)](https://coveralls.io/github/contentful-userland/cf-content-types-generator)\n\n```ts\nimport type { TypeAnimal } from './@types/generated';\n```\n\n## Install\n\n```bash\nnpm install --save-dev cf-content-types-generator\n```\n\n## Quickstart In 60 Seconds\n\nYou can generate types in two ways:\n\n- from a local export JSON file in the exact [Input](#input) shape, usually created with `contentful space export`\n- by providing Contentful credentials and letting the CLI fetch the same model data on the fly\n\n### Path A: Generate From A Local Export JSON File\n\nExport your space model:\n\n```bash\ncontentful space export --config ./export-config.json\n```\n\nGenerate types:\n\n```bash\ncf-content-types-generator ./contentful-export.json -o src/@types/generated\n```\n\nUse the generated type:\n\n```ts\nimport type { TypeAnimal } from './@types/generated';\n```\n\n### Path B: Generate By Fetching From Contentful\n\n```bash\ncf-content-types-generator \\\n  -s \u003cspace-id\u003e \\\n  -t \u003cmanagement-token\u003e \\\n  -e \u003cenvironment\u003e \\\n  --proxy https://user:password@proxy.example:8443 \\\n  -o src/@types/generated\n```\n\nIf your network requires a proxy, you can also add `--rawProxy` to pass the proxy config straight to Axios.\n\n## What It’s For\n\n- turn a Contentful content model into generated TypeScript types\n- use those generated types in apps built with `contentful.js` v10+\n- optionally add JSDoc, type guards, and response aliases\n\n### When To Use It\n\n- you keep Contentful schema in source control and want generated app types\n- you use `contentful.js` in TypeScript and want typed entries based on your real model\n- you want type generation in CI from either exports or live space data\n\nFurther reading: if you want broader context on typing Contentful projects with TypeScript, see Contentful’s guide to [TypeScript and Contentful](https://www.contentful.com/blog/contentful-typescript/).\n\n## CLI Usage\n\n```text\ncf-content-types-generator [FILE]\n```\n\nCommon tasks:\n\n- generate from a local export JSON file: `cf-content-types-generator ./contentful-export.json -o src/@types/generated`\n- generate by fetching live data: `cf-content-types-generator -s \u003cspace-id\u003e -t \u003cmanagement-token\u003e -e \u003cenvironment\u003e -o src/@types/generated`\n- add optional helpers: `cf-content-types-generator ./contentful-export.json -o src/@types/generated --jsdoc --typeguard --response`\n\nKey flags:\n\n- `-o, --out` output directory\n- `-p, --preserve` preserve existing output folder\n- `-d, --jsdoc` add JSDoc comments\n- `-g, --typeguard` add modern type guards\n- `-r, --response` add response aliases\n- `-s, --spaceId` Contentful space id\n- `-t, --token` Contentful management token\n- `-e, --environment` Contentful environment\n- `-a, --host` Management API host\n- `--proxy` proxy URL in HTTP auth format\n- `--rawProxy` pass proxy config to Axios directly\n\nRemoved in v3.x:\n\n- `--v10`\n- `--localized`\n\nBoth now error with explicit migration hints.\n\n## Optional Renderers\n\nAll examples below use the same generated base type:\n\n```ts\nexport interface TypeAnimalFields {\n  breed?: EntryFieldTypes.Symbol;\n}\n\nexport type TypeAnimalSkeleton = EntrySkeletonType\u003cTypeAnimalFields, 'animal'\u003e;\nexport type TypeAnimal\u003c\n  Modifiers extends ChainModifiers,\n  Locales extends LocaleCode = LocaleCode,\n\u003e = Entry\u003cTypeAnimalSkeleton, Modifiers, Locales\u003e;\n```\n\n### `-d, --jsdoc`\n\nAdds generated comments to fields, skeletons, and entries.\n\n```diff\n /**\n  * Fields type definition for content type 'TypeAnimal'\n  * @name TypeAnimalFields\n  * @type {TypeAnimalFields}\n  * @memberof TypeAnimal\n  */\n export interface TypeAnimalFields {\n   /**\n    * Field type definition for field 'breed' (Breed)\n    * @name Breed\n    * @localized false\n    */\n   breed?: EntryFieldTypes.Symbol;\n }\n```\n\n### `-g, --typeguard`\n\nAdds a runtime predicate for the generated entry type.\n\n```ts\nexport function isTypeAnimal\u003cModifiers extends ChainModifiers, Locales extends LocaleCode\u003e(\n  entry: Entry\u003cEntrySkeletonType, Modifiers, Locales\u003e,\n): entry is TypeAnimal\u003cModifiers, Locales\u003e {\n  return entry.sys.contentType.sys.id === 'animal';\n}\n```\n\n### `-r, --response`\n\nAdds aliases for common response modifier combinations.\n\n```ts\nexport type TypeAnimalWithoutLinkResolutionResponse = TypeAnimal\u003c'WITHOUT_LINK_RESOLUTION'\u003e;\nexport type TypeAnimalWithAllLocalesResponse\u003cLocales extends LocaleCode = LocaleCode\u003e = TypeAnimal\u003c\n  'WITH_ALL_LOCALES',\n  Locales\n\u003e;\n```\n\nThese aliases are convenience aliases for the top-level entry type only. Linked entries still stay typed as `Entry\u003cLinkedSkeleton, Modifiers, Locales\u003e`, which is expected and matches `contentful.js`.\n\n### Link Resolution Tips\n\nIf you want resolved assets and entries without unresolved-link unions, call the client with the matching chain modifier:\n\n```ts\nconst articles = await client.withoutUnresolvableLinks.getEntries\u003cTypeBlogArticleSkeleton\u003e({\n  content_type: 'blogArticle',\n  include: 4,\n});\n\narticles.items[0]?.fields.image?.fields.file?.url;\narticles.items[0]?.fields.category?.[0]?.fields;\n```\n\nIf a reference field allows multiple content types, generate type guards with `--typeguard` and narrow linked entries where you use them.\n\n## Programmatic Usage\n\n```ts\nimport {\n  CFDefinitionsBuilder,\n  ContentTypeRenderer,\n  ResponseTypeRenderer,\n  TypeGuardRenderer,\n} from 'cf-content-types-generator';\n\nconst builder = new CFDefinitionsBuilder([\n  new ContentTypeRenderer(),\n  new TypeGuardRenderer(),\n  new ResponseTypeRenderer(),\n]);\n```\n\nIf you want custom output, extend `BaseContentTypeRenderer` or implement the `Renderer` interface.\n\n## Input\n\nThis tool accepts either:\n\n- a local JSON file in the exact shape produced by `contentful space export`\n- or enough CLI credentials for the generator to fetch equivalent model data live\n\nTypical export command:\n\n```bash\ncontentful space export --config ./export-config.json\n```\n\nIf you pass a local file, that exported JSON shape is the exact shape this tool expects.\n\nWhen you fetch the model remotely, this tool intentionally skips entry data and only reads schema data. A log line about skipping content entries is expected and does not mean generation is incomplete.\n\nAt minimum, this generator needs a JSON object with a `contentTypes` field. A full `contentful space export` dump usually also contains keys such as `entries`, `assets`, `locales`, `roles`, `webhooks`, and `editorInterfaces`, but this generator mainly reads `contentTypes` and `editorInterfaces`.\n\nExample shape:\n\n```json\n{\n  \"contentTypes\": [\n    {\n      \"sys\": {\n        \"id\": \"animal\",\n        \"type\": \"ContentType\"\n      },\n      \"name\": \"Animal\",\n      \"fields\": [\n        {\n          \"id\": \"breed\",\n          \"type\": \"Symbol\",\n          \"required\": false,\n          \"localized\": false,\n          \"omitted\": false,\n          \"disabled\": false,\n          \"validations\": []\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Migration From 2.x To 3.x\n\n`3.x` removes all pre-v10 output behavior. If you are upgrading from `2.x`, use this migration path:\n\n1. Remove `--v10` from CLI usage.\n2. Remove `--localized`; no replacement needed.\n3. Rename programmatic imports:\n   `V10ContentTypeRenderer` -\u003e `ContentTypeRenderer`\n   `V10TypeGuardRenderer` -\u003e `TypeGuardRenderer`\n   `createV10Context()` -\u003e `createContext()`\n4. Regenerate all generated types.\n5. Update downstream code that still assumes classic `Entry\u003cTypeFields\u003e` output.\n\nCLI before:\n\n```bash\ncf-content-types-generator ./contentful-export.json -o src/@types/generated --v10 --response\n```\n\nCLI after:\n\n```bash\ncf-content-types-generator ./contentful-export.json -o src/@types/generated --response\n```\n\nProgrammatic before:\n\n```ts\nimport {\n  CFDefinitionsBuilder,\n  V10ContentTypeRenderer,\n  V10TypeGuardRenderer,\n} from 'cf-content-types-generator';\n\nconst builder = new CFDefinitionsBuilder([\n  new V10ContentTypeRenderer(),\n  new V10TypeGuardRenderer(),\n]);\n```\n\nProgrammatic after:\n\n```ts\nimport {\n  CFDefinitionsBuilder,\n  ContentTypeRenderer,\n  TypeGuardRenderer,\n} from 'cf-content-types-generator';\n\nconst builder = new CFDefinitionsBuilder([new ContentTypeRenderer(), new TypeGuardRenderer()]);\n```\n\nIf downstream code still expects classic output, regenerate and adapt those types in the same change.\n\n## Development\n\n```bash\npnpm test\npnpm build\n```\n\nRelated app: [cf-content-types-generator-app](https://github.com/marcolink/cf-content-types-generator-app)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontentful-userland%2Fcf-content-types-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontentful-userland%2Fcf-content-types-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontentful-userland%2Fcf-content-types-generator/lists"}