Przejdź do treści
Biblioteka skilli
Programowanie · Integracja z narzędziem

contentful

/contentful

Pomaga pracować z Contentful, headless CMS: pobierać wpisy przez Content Delivery API, typować je w TypeScript, renderować rich text, podglądać szkice oraz publikować wpisy ze skryptu.

Repozytorium
skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
25.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Pomaga pracować z Contentful, headless CMS: pobierać wpisy przez Content Delivery API, typować je w TypeScript, renderować rich text, podglądać szkice oraz publikować wpisy ze skryptu.

Oryginalny opis (EN)

Contentful is an API-first headless CMS: content lives in typed content models and is served through the Content Delivery API (published, CDN), the Content Preview API (drafts) and the Content Management API (writes). Use when a user wants to fetch Contentful entries in a website or app, type them in TypeScript, render rich text, resolve linked entries and assets, preview drafts, write or publish entries from a script, or trigger rebuilds with webhooks.

Jak działa

  1. Overview
  2. Instructions
  3. Examples
  4. Guidelines
Sekcje z nagłówków SKILL.md, w oryginale · 215 linii, 1 173 słów
Podgląd SKILL.md
---
name: contentful
description: >-
  Contentful is an API-first headless CMS: content lives in typed content models and is served through the Content Delivery API (published, CDN), the Content Preview API (drafts) and the Content Management API (writes). Use when a user wants to fetch Contentful entries in a website or app, type them in TypeScript, render rich text, resolve linked entries and assets, preview drafts, write or publish entries from a script, or trigger rebuilds with webhooks.
license: Apache-2.0
compatibility: "Node.js 20+, contentful 11.x, contentful-management 12.x, a Contentful space with API keys"
metadata:
  author: terminal-skills
  version: "1.1.0"
  category: content
  repository: https://github.com/contentful/contentful.js
  tags: "headless-cms, contentful, content-api, cdn, typescript"
---

# Contentful

## Overview

Contentful stores structured content in a space. You define content types (a blog post, an author), editors create entries, and your code reads them over REST (or GraphQL). Reads of published content use the Delivery API on `cdn.contentful.com`; unpublished drafts use the Preview API on `preview.contentful.com` with a separate token; writes use the Management API with a personal access token or an app token. The `contentful` package (v11) is the read client, `contentful-management` (v12) the write client, and `@contentful/rich-text-react-renderer` turns rich text fields into React.

## Instructions

### Install and configure

```bash
npm install contentful @contentful/rich-text-react-renderer @contentful/rich-text-types
npm install contentful-management      # only for scripts that create or publish entries
```

Keep the space ID and tokens in environment variables: `CONTENTFUL_SPACE_ID`, `CONTENTFUL_DELIVERY_TOKEN`, `CONTENTFUL_PREVIEW_TOKEN` (server-side only), `CONTENTFUL_MANAGEMENT_TOKEN` (scripts only, never in browser code).

### Typed Delivery API client

Since v10 the client is typed through entry skeletons: describe each content type once with `contentTypeId` and `fields`, then pass the skeleton to `getEntries<...>`. The `content_type` query parameter is required when you filter on `fields.*`.

```typescript
// src/lib/contentful.ts: Contentful client and typed queries
import * as contentful from "contentful";

export type AuthorSkeleton = {
  contentTypeId: "author";
  fields: {
    name: contentful.EntryFieldTypes.Text;
  };
};

export type BlogPostSkeleton = {
  contentTypeId: "blogPost";
  fields: {
    title: contentful.EntryFieldTypes.Text;
    slug: contentful.EntryFieldTypes.Symbol;
    excerpt: contentful.EntryFieldTypes.Text;
    body: contentful.EntryFieldTypes.RichText;
    featuredImage: contentful.EntryFieldTypes.AssetLink;
    author: contentful.EntryFieldTypes.EntryLink<AuthorSkeleton>;
    tags: contentful.EntryFieldTypes.Array<contentful.EntryFieldTypes.Symbol>;
    publishDate: contentful.EntryFieldTypes.Date;
  };
};

const preview = process.env.CONTENTFUL_PREVIEW === "true";

export const client = contentful.createClient({
  space: process.env.CONTENTFUL_SPACE_ID!,
  environment: process.env.CONTENTFUL_ENVIRONMENT ?? "master",
  accessToken: preview
    ? process.env.CONTENTFUL_PREVIEW_TOKEN!
    : process.env.CONTENTFUL_DELIVERY_TOKEN!,
  host: preview ? "preview.contentful.com" : "cdn.contentful.com",
});

export async function getBlogPosts(limit = 10) {
  const response = await client.withoutUnresolvableLinks.getEntries<BlogPostSkeleton>({
    content_type: "blogPost",
    order: ["-fields.publishDate"],
    limit,
    include: 2,
    "fields.slug[exists]": true,
  });
  return response.items;
}

export async function getBlogPostBySlug(slug: string) {
  const response = await client.withoutUnresolvableLinks.getEntries<BlogPostSkeleton>({
    content_type: "blogPost",
    "fields.slug": slug,
    include: 3,
    limit: 1,
  });
  return response.items[0] ?? null;
}

```

Notes on the queries: `include` sets how many levels of linked entries and assets are resolved. `withoutUnresolvableLinks` removes links to entries that are unpublished or deleted instead of leaving raw link objects, so `post.fields.author` is either a resolved entry or absent. In v11 asset files are optional (`asset.fields.file?.url`) because an asset may have no file in the requested locale.

You can generate the skeletons from your content model instead of writing them: `npx cf-content-types-generator -s $CONTENTFUL_SPACE_ID -t $CONTENTFUL_MANAGEMENT_TOKEN -e master -o src/@types/generated` (a community tool that targets contentful.js 10 and later).

### Rich text rendering

```tsx
// src/components/RichText.tsx: render Contentful rich text
import { documentToReactComponents, type Options } from "@contentful/rich-text-react-renderer";
import { BLOCKS, INLINES, type Document } from "@contentful/rich-text-types";

const renderOptions: Options = {
  renderNode: {
    [BLOCKS.EMBEDDED_ASSET]: (node) => {
      const file = node.data.target.fields?.file;
      if (!file?.url) return null;
      const width = file.details?.image?.width;     // absent for non-image files
      const height = file.details?.image?.height;
      return (
        <img
          src={`https:${file.url}?w=800&fm=webp&q=80`}
          alt={node.data.target.fields.title ?? ""}
          width={width}
          height={height}
          loading="lazy"
        />
      );
    },
    [BLOCKS.EMBEDDED_ENTRY]: (node) => {
      const entry = node.data.target;
      if (entry.sys.contentType?.sys.id === "codeBlock") {
        return (
          <pre>
            <code className={`language-${entry.fields.language}`}>{entry.fields.code}</code>
          </pre>
        );
      }
      return null;
    },
    [INLINES.HYPERLINK]: (node, children) => (
      <a href={node.data.uri} target="_blank" rel="noopener noreferrer">
        {children}
      </a>
    ),
  },
};

export function RichText({ document }: { document: Document }) {
  return <div className="prose">{documentToReactComponents(document, renderOptions)}</div>;
}
```

Embedded entries and assets only render if the query resolved them: use `include: 2` or more on the page query. Replace the `<img>` with your framework's image component if you use one, and allow the `images.ctfassets.net` host in its config.

### Image transformations

Asset URLs accept query parameters (`w`, `h`, `q`, `fm`, `fit`, `f`) so the CDN resizes and re-encodes on the fly:

```typescript
import type { Asset } from "contentful";
type ImageOptions = { width?: number; height?: number; quality?: number; format?: "webp" | "avif" | "jpg" | "png"; fit?: "pad" | "fill" | "scale" | "crop" | "thumb"; focus?: "face" | "center" | "top" | "bottom" };
export function contentfulImageUrl(asset: Asset, o: ImageOptions = {}): string {
  const file = asset.fields.file;
  if (!file?.url) throw new Error("Asset has no file in this locale");
  const url = new URL(`https:${file.url}`);
  if (o.width) url.searchParams.set("w", String(o.width));
  if (o.height) url.searchParams.set("h", String(o.height));
  if (o.quality) url.searchParams.set("q", String(o.quality));
  if (o.format) url.searchParams.set("fm", o.format);
  if (o.fit) url.searchParams.set("fit", o.fit);
  if (o.focus) url.searchParams.set("f", o.focus);
  return url.toString();
}
```

### Preview and pagination

Set `host: "preview.contentful.com"` with the preview token (the `preview` flag in the client above) to see drafts; never use that client for public pages. For long lists, `client.getEntriesWithCursor({ limit: 100 })` returns `pages.next` to pass as `pageNext` on the next call, instead of `skip` offsets.

### Localization

Fetch one locale with `locale: "de-DE"` in the query. To get every locale, use the modifier `client.withAllLocales.getEntries(...)`, which changes each field to an object keyed by locale code (`post.fields.title["de-DE"]`). Locale codes come from the space settings, so use the exact codes (`en-US`, not `en`).

### Writing with the Management API

```typescript
// scripts/create-draft.ts
import { createClient } from "contentful-management";

const cma = createClient({ accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN! });
const scope = { spaceId: process.env.CONTENTFUL_SPACE_ID!, environmentId: "master" };

async function main() {
  const entry = await cma.entry.create(
    { ...scope, contentTypeId: "blogPost" },
    { fields: { title: { "en-US": "Launch notes" }, slug: { "en-US": "launch-notes" } } },
  );
  const published = await cma.entry.publish({ ...scope, entryId: entry.sys.id }, entry);
  console.log("published version", published.sys.publishedVersion);
}

main().catch((error) => { console.error(error); process.exit(1); });
```

Management API field values are always keyed by locale. Publishing fails if a required field is empty or a linked entry is unpublished. Test content-model changes in a separate environment (a sandbox copy of `master`) before applying them to `master`.

## Examples

### Example 1: "Show my five latest posts with the author's name on the homepage"

Add the skeletons and client above, then:

```typescript
const posts = await getBlogPosts(5);
for (const post of posts) {
  console.log(post.fields.title, "by", post.fields.author?.fields.name);
}
```

The request goes to `/spaces/<space>/environments/master/entries?content_type=blogPost&order=-fields.publishDate&limit=5&include=2&...` with an `Authorization: Bearer` header carrying the delivery token, and each author comes back already resolved from the `includes` section.

### Example 2: "Render the article body, including embedded images"

Fetch with `getBlogPostBySlug("launch-notes")` (it uses `include: 3`) and render `<RichText document={post.fields.body} />`. Each embedded asset becomes an `<img>` on the `images.ctfassets.net` host with `?w=800&fm=webp&q=80` appended, and links open in a new tab.

## Guidelines

- Use the Delivery token for production reads and the Preview token only on preview routes or server-side draft mode; keep both, and the Management token, out of client bundles.
- Prefer `withoutUnresolvableLinks` for public pages; otherwise unpublished linked entries appear as bare `{ sys: { type: "Link" } }` objects and break rendering.
- Keep `limit` and `include` as small as the page allows, and cache responses or build statically instead of fetching on every request; the Delivery API is rate limited.
- Trigger rebuilds or cache revalidation from a Contentful webhook on publish and unpublish events; check the shared secret header you configured before acting on the request.
- Make content-model changes in a separate environment first, then promote them, because removing a field breaks every query that selects it.
- Do not use the Management API for page rendering: it is slower, rate limited and not cached.
Pliki w paczce (2)
  • SKILL.md 11 KB
  • _scores.json 1 KB

Wersje

W bazie nie ma innych skilli o nazwie contentful.

Migawka bazy z 13.11.2026 · wersja paczki 2cd05b56c0dd (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100contentful-nextjs
    Dodaje i konfiguruje Contentful w istniejącym projekcie Next.js: SDK JavaScript, zmienne środowiskowe, klienty produkcyjne i podglądowe, pobieranie treści w App Router i Pages Router oraz Draft Mode.
  • 95cms
    Wspiera integrację headless CMS (Sanity, Strapi, Contentful): zapytania GROQ, Portable Text, draft mode, kolekcje treści i podgląd z rewalidacją.
  • 100local-cms-52e4ef01
    Podpowiada, jak zintegrować headless CMS, takie jak Sanity, Contentful, DatoCMS, Storyblok lub Builder.io, z Vercelem.
  • 100contentful-migration
    Pisze i uruchamia skrypty migracji modelu treści Contentful z biblioteką contentful-migration i CLI: typy treści, pola, walidacje, interfejs edytora, transformacje wpisów, tagi i adnotacje.
  • 100add-cms
    Dodaje headless CMS, np. Sanity, Payload lub Strapi, z modelem treści, podglądem i odświeżaniem po webhooku.
  • 100migration-companion
    Prowadzi migrację treści i aplikacji z innego CMS do Contentstack, obecnie z Contentful: modele treści, treści, zasoby, lokalizacje, integracje i kod strony.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.