Registry / type-stubs / microcms-typescript

microcms-typescript

library1.0.15jsnpmunverified

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.

type-stubs

npm install microcms-typescript

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MICROCMS-TYPESCRIP

microcms-typescript

type-stubsjavascriptv1.0.15

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

EndPoints

✓ import type { EndPoints } from './cms-types';

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.

EndPoints['gets']['your-api-name']

✓ let listData: EndPoints['gets']['blogs'];

Accessing the type for a list-format API's GET response, where 'blogs' is the API endpoint name defined in your schema.

EndPoints['get']['your-api-name']

✓ let detailData: EndPoints['get']['blogs'];

Accessing the type for a detail (single content) GET response for a list-format API. 'blogs' is the API endpoint name.

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.

mkdir microcms-schemas cat > microcms-schemas/api-blogs-schema.json <<EOF { "apiFields": [ { "idValue": "blogTitleField", "fieldId": "title", "name": "Title", "kind": "text", "required": true, "isUnique": false }, { "fieldId": "slug", "name": "Slug", "kind": "text", "required": true, "isUnique": true }, { "fieldId": "body", "name": "Body", "kind": "richEditor", "required": true }, { "fieldId": "category", "name": "Category", "kind": "relation", "required": false } ], "customFields": [] } EOF # Install the CLI tool npm install microcms-typescript --save-dev # Generate TypeScript types from your schema files npx microcms-typescript microcms-schemas cms-types.ts # Example TypeScript usage (e.g., in src/types.ts or similar) // Make sure your tsconfig.json includes 'cms-types.ts' /* // tsconfig.json example: // { // "compilerOptions": { // "target": "ES2020", // "module": "ESNext", // "moduleResolution": "Bundler", // "strict": true, // "esModuleInterop": true, // "skipLibCheck": true, // "forceConsistentCasingInFileNames": true, // "types": ["node"], // "outDir": "./dist", // "rootDir": ".", // "paths": { "@/*": ["./src/*"] } // }, // "include": ["./src/**/*.ts", "./src/**/*.d.ts", "cms-types.ts"] // } */ import type { EndPoints } from './cms-types'; // Type for a list of blog posts type BlogListResponse = EndPoints['gets']['blogs']; // Type for a single blog post's detail type BlogDetail = EndPoints['get']['blogs']; // Type for creating a new blog post (POST payload) type BlogCreatePayload = EndPoints['post']['blogs']; // Example usage with dummy data const fetchedBlogs: BlogListResponse = { contents: [ { id: 'blog123', title: 'My First Blog Post', slug: 'my-first-blog-post', body: '<p>Content here</p>', createdAt: '2023-01-01T00:00:00.000Z', updatedAt: '2023-01-01T00:00:00.000Z', publishedAt: '2023-01-01T00:00:00.000Z', revisedAt: '2023-01-01T00:00:00.000Z', category: 'cat456' } ], totalCount: 1, limit: 10, offset: 0 }; console.log(fetchedBlogs.contents[0].title); // Accessing type-safe data

microcms-typescript --version

Debug

Known issues

gotchaThe 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.

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.

affects: >=1.0.0

gotchaThe `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.

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.

affects: >=1.0.0

gotchaWhen 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+).

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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'microcms-typescript' or its corresponding type declarations.

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.

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

Error: ENOENT: no such file or directory, stat '<src-dir>'

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.

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.

Error: Failed to parse schema file: <path/to/schema.json>

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.

fix

Inspect the specified JSON file (`<path/to/schema.json>`) for syntax errors. Validate its content against the expected MicroCMS API schema structure.

Property 'contents' does not exist on type 'EndPoints["gets"]["your-api-name"]'.

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.

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`).

Upgrade

Version history

1.0.15latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/SoraKumo001/microcms-typescript ↗

packagehttps://www.npmjs.com/package/microcms-typescript ↗

homepagehttps://microcms.io ↗