contentful-to-zod

🚀 contentful-to-zod

🔄 Generate type-safe Zod schemas from your Contentful content types with ease!

💡 Why?

By validating our contentful data with zod, we can catch any unhandled schema changes and protect ourselves from unexpected runtime errors.

🚀 Quick Start

📦 Install

# npm
npm install -D contentful-to-zod

# yarn
yarn add -D contentful-to-zod

# pnpm
pnpm install -D contentful-to-zod

📤 Export Your Contentful Schema

contentful space export \
  --space-id <SPACE_ID> \
  --management-token <MANAGEMENT_TOKEN> \
  --content-file ./contentful.json \
  --content-model-only=true

⚡️ Generate Schemas

npx contentful-to-zod --input ./contentful.json --output ./schemas.ts

Browse a sample output here

📝 Configuration

You can customize the generator behavior by creating a contentful-to-zod.config.js or contentful-to-zod.config.mjs file in your project root:

// contentful-to-zod.config.js
/** @type {import('contentful-to-zod').ContentfulToZodConfig} */
export default {
  // Generate flat schemas without references
  flat: true,

  // Allow unknown keys in objects
  passthrough: true,

  // Throw error for unsupported types
  abortOnUnknown: false,

  // Custom naming functions
  toTypeName: (entity) => `${entity}Type`,
  toSchemaName: (entity) => `${entity}Schema`,
};

The configuration file supports all generator options. CLI arguments take precedence over config file options.

🚀 Use Schemas

import contentful from "contentful";
import { pageSchema } from "./schemas";

const client = contentful.createClient({
  // ...
});

const response = await client.getEntries({
  content_type: "page",
});

const pages = response.items.map((item) => pageSchema.parse(item));

🛠 CLI Options

Option	Description	Default
-i, --input <path>	Path to Contentful schema JSON file	Required
-o, --output <path>	Output path for generated TypeScript file	Required
--passthrough	Allow unknown keys in objects	false
-a, --abort-on-unknown	Throw error for unsupported types instead of using z.unknown()	false
-f, --flat	Generate flat schemas without references	false

📝 License

MIT

Contributing

Release

npm version major|minor|patch

git push origin main

VERSION=v$(npm version | grep contentful-to-zod | cut -d"'" -f 4)
git push origin $VERSION
gh release create $VERSION --title $VERSION --generate-notes