Contentful Parser

A small TypeScript library that flattens Contentful entries and assets into plain objects.

Quick Start

Install with your favorite package manager:

npm install @ggcls/contentful-parser
# or
pnpm add @ggcls/contentful-parser
# or
yarn add @ggcls/contentful-parser

Pass an entry to contentfulParser:

import { contentfulParser } from "@ggcls/contentful-parser";

const article = contentfulParser({
  sys: {
    id: "article-1",
    contentType: { sys: { id: "article" } },
  },
  fields: {
    title: "Hello world",
    views: 42,
  },
});

// {
//   title: "Hello world",
//   views: 42,
//   id: "article-1",
//   __typename: "article"
// }

Arrays and collections are supported too. Collections return { items: [...] } without pagination metadata.

Nested entries are flattened, asset URLs starting with // become HTTPS URLs, and the original data is never modified. Provide resolved references: the parser does not resolve links from includes.

Options

contentfulParser(data, {
  depth: 10,
  parseArrays: true,
  parseRefs: true,
});

Option	Default	Description
depth	10	Maximum entry depth. Use a non-negative integer; 0 returns an empty object for an entry.
parseArrays	true	Parse arrays and remove unresolved links.
parseRefs	true	Flatten nested entries, including those inside arrays.

All options are optional. Root entries and collection entries are always processed; these flags control their fields. Root arrays follow both flags.

TypeScript

Field types are inferred from the input, with support for the official contentful types. Parsed fields are optional because depth limits and circular references can truncate entries.

TypeScript is optional: the library also works in JavaScript projects.

Development

pnpm install
pnpm test
pnpm build

License

MIT