{"id":11307,"library":"microcms-typescript","title":"MicroCMS TypeScript Type Generator","description":"The `microcms-typescript` package is a command-line interface (CLI) tool designed to generate TypeScript type definitions directly from MicroCMS API schema JSON files. Currently stable at version 1.0.15, this utility provides a bridge between your MicroCMS content models and your TypeScript codebase, enabling strong type-safety for your MicroCMS data. Unlike the `microcms-js-sdk` or `microcms-ts-sdk` which are client libraries for interacting with the MicroCMS API, `microcms-typescript` focuses solely on code generation. It processes local JSON files representing MicroCMS API schemas and outputs corresponding TypeScript `type` declarations, including a comprehensive `EndPoints` type that encapsulates `gets`, `get`, `post`, `put`, and `patch` operations, ensuring type-safe access to your content structure. This distinction is crucial as it targets the build-time generation of types rather than runtime API interaction.","status":"active","version":"1.0.15","language":"javascript","source_language":"en","source_url":"https://github.com/SoraKumo001/microcms-typescript","tags":["javascript","microcms","typescript"],"install":[{"cmd":"npm install microcms-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add microcms-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add microcms-typescript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a CLI tool that *generates* TypeScript types. The 'imports' shown here are for consuming the *output* of the tool (e.g., in your application code), not for importing from the `microcms-typescript` package itself.","symbol":"EndPoints","correct":"import type { EndPoints } from './cms-types';"},{"note":"Accessing the type for a list-format API's GET response, where 'blogs' is the API endpoint name defined in your schema.","symbol":"EndPoints['gets']['your-api-name']","correct":"let listData: EndPoints['gets']['blogs'];"},{"note":"Accessing the type for a detail (single content) GET response for a list-format API. 'blogs' is the API endpoint name.","symbol":"EndPoints['get']['your-api-name']","correct":"let detailData: EndPoints['get']['blogs'];"}],"quickstart":{"code":"mkdir microcms-schemas\ncat > microcms-schemas/api-blogs-schema.json <<EOF\n{\n  \"apiFields\": [\n    {\n      \"idValue\": \"blogTitleField\",\n      \"fieldId\": \"title\",\n      \"name\": \"Title\",\n      \"kind\": \"text\",\n      \"required\": true,\n      \"isUnique\": false\n    },\n    {\n      \"fieldId\": \"slug\",\n      \"name\": \"Slug\",\n      \"kind\": \"text\",\n      \"required\": true,\n      \"isUnique\": true\n    },\n    {\n      \"fieldId\": \"body\",\n      \"name\": \"Body\",\n      \"kind\": \"richEditor\",\n      \"required\": true\n    },\n    {\n      \"fieldId\": \"category\",\n      \"name\": \"Category\",\n      \"kind\": \"relation\",\n      \"required\": false\n    }\n  ],\n  \"customFields\": []\n}\nEOF\n\n# Install the CLI tool\nnpm install microcms-typescript --save-dev\n\n# Generate TypeScript types from your schema files\nnpx microcms-typescript microcms-schemas cms-types.ts\n\n# Example TypeScript usage (e.g., in src/types.ts or similar)\n// Make sure your tsconfig.json includes 'cms-types.ts'\n/*\n// tsconfig.json example:\n// {\n//   \"compilerOptions\": {\n//     \"target\": \"ES2020\",\n//     \"module\": \"ESNext\",\n//     \"moduleResolution\": \"Bundler\",\n//     \"strict\": true,\n//     \"esModuleInterop\": true,\n//     \"skipLibCheck\": true,\n//     \"forceConsistentCasingInFileNames\": true,\n//     \"types\": [\"node\"],\n//     \"outDir\": \"./dist\",\n//     \"rootDir\": \".\",\n//     \"paths\": { \"@/*\": [\"./src/*\"] }\n//   },\n//   \"include\": [\"./src/**/*.ts\", \"./src/**/*.d.ts\", \"cms-types.ts\"]\n// }\n*/\n\nimport type { EndPoints } from './cms-types';\n\n// Type for a list of blog posts\ntype BlogListResponse = EndPoints['gets']['blogs'];\n\n// Type for a single blog post's detail\ntype BlogDetail = EndPoints['get']['blogs'];\n\n// Type for creating a new blog post (POST payload)\ntype BlogCreatePayload = EndPoints['post']['blogs'];\n\n// Example usage with dummy data\nconst fetchedBlogs: BlogListResponse = {\n  contents: [\n    {\n      id: 'blog123',\n      title: 'My First Blog Post',\n      slug: 'my-first-blog-post',\n      body: '<p>Content here</p>',\n      createdAt: '2023-01-01T00:00:00.000Z',\n      updatedAt: '2023-01-01T00:00:00.000Z',\n      publishedAt: '2023-01-01T00:00:00.000Z',\n      revisedAt: '2023-01-01T00:00:00.000Z',\n      category: 'cat456'\n    }\n  ],\n  totalCount: 1,\n  limit: 10,\n  offset: 0\n};\n\nconsole.log(fetchedBlogs.contents[0].title); // Accessing type-safe data","lang":"typescript","description":"This quickstart demonstrates how to install the `microcms-typescript` CLI, create a sample MicroCMS schema JSON file, run the tool to generate `cms-types.ts`, and then import and use the generated `EndPoints` types in a TypeScript application to ensure type safety for your MicroCMS data."},"warnings":[{"fix":"Regularly check for updates to `microcms-typescript` and review generated types after MicroCMS platform updates. If issues arise, report them to the maintainer or temporarily pin to a working version.","message":"The functionality of `microcms-typescript` relies on the stability of MicroCMS's schema export format. Significant changes to how MicroCMS structures its exported JSON schemas could lead to incorrect type generation or runtime errors until the tool is updated.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Avoid making manual edits to the generated type file. If custom types are needed, extend the generated types in a separate file, or integrate the generation step into your build process to manage the output consistently.","message":"The `microcms-typescript` CLI tool will overwrite the specified `dist-file` (e.g., `cms-types.ts`) if it already exists. Ensure that this file is either exclusively generated or that its contents are not manually edited, as changes will be lost on subsequent runs.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your project's Node.js environment and `devDependencies` for `typescript` are sufficiently modern (e.g., Node.js v18+ and TypeScript v5.0+ are recommended for new projects). Update `tsconfig.json` compiler options like `target`, `module`, and `esModuleInterop` to align with modern standards.","message":"When using `microcms-typescript` in a project with an older Node.js or TypeScript version, compatibility issues may arise. TypeScript itself has had breaking changes in recent major versions regarding Node.js requirements (e.g., TS 5.1+ requires Node 14.17+).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Do not import `microcms-typescript` into your code. Instead, run it as a CLI command using `npx microcms-typescript` or, if installed globally, `microcms-typescript`.","cause":"Attempting to `import` the `microcms-typescript` package into application code. It is a command-line interface (CLI) tool, not a library meant for direct import.","error":"Error: Cannot find module 'microcms-typescript' or its corresponding type declarations."},{"fix":"Verify that the `src-dir` argument points to an existing directory containing your MicroCMS schema JSON files. Ensure correct casing and full path if running from a different working directory.","cause":"The source directory (`src-dir`) provided to the CLI tool does not exist or is inaccessible. This typically means the path to your MicroCMS schema JSON files is incorrect.","error":"Error: ENOENT: no such file or directory, stat '<src-dir>'"},{"fix":"Inspect the specified JSON file (`<path/to/schema.json>`) for syntax errors. Validate its content against the expected MicroCMS API schema structure.","cause":"One of the MicroCMS schema JSON files in the `src-dir` is malformed (e.g., invalid JSON syntax) or its structure does not conform to the expected MicroCMS schema format.","error":"Error: Failed to parse schema file: <path/to/schema.json>"},{"fix":"First, ensure your MicroCMS schema JSON files are up-to-date and reflect your current API structure. Then, re-run the `microcms-typescript` CLI to regenerate `cms-types.ts`. Double-check the API name used (e.g., 'blogs') matches the filename of your schema JSON (e.g., `api-blogs-schema.json`).","cause":"The generated types are outdated or the API name used in the `EndPoints` type access doesn't match the actual API endpoint name in your MicroCMS schema files.","error":"Property 'contents' does not exist on type 'EndPoints[\"gets\"][\"your-api-name\"]'."}],"ecosystem":"npm"}