Kas tas Contentful ir kodėl apie jį verta kalbėti
Jei dirbate su šiuolaikinėmis web aplikacijomis, turbūt jau girdėjote apie headless CMS koncepciją. Contentful yra vienas iš populiariausių tokio tipo sprendimų, kuris leidžia atskirti turinio valdymą nuo jo pateikimo. Skirtingai nei tradicinės CMS sistemos (WordPress, Drupal ir panašūs), Contentful neturi jokio frontend’o – tai grynai backend’inis sprendimas, kuris teikia turinį per API.
Kodėl tai svarbu? Nes šiandien turinys vartojamas ne tik svetainėse. Jums gali prireikti to paties turinio mobilioje aplikacijoje, išmaniuose laikrodžiuose, IoT įrenginiuose ar net balso asistentuose. Contentful leidžia sukurti turinį vieną kartą ir naudoti jį bet kur, bet kokioje platformoje.
Sistema veikia kaip centralizuota turinio saugykla su galingais API – REST ir GraphQL. Tai reiškia, kad jūsų frontend’as gali būti sukurtas su React, Vue, Angular, Next.js ar bet kuria kita technologija, o turinys bus prieinamas per paprastus API užklausimus.
Kaip pradėti: pirmieji žingsniai su Contentful
Prieš pradedant integruoti Contentful į savo projektą, reikia suprasti kelias pagrindines koncepcijas. Pirma, yra Spaces – tai jūsų projekto konteineris, kuriame saugomas visas turinys. Viename account’e galite turėti kelis space’us skirtingiems projektams.
Antra svarbi koncepcija – Content Models. Tai struktūros, kurias apibrėžiate savo turiniui. Pavyzdžiui, jei kuriate blog’ą, galite sukurti „Blog Post” modelį su laukais: pavadinimas, autorius, tekstas, paveikslėlis, data ir pan. Contentful leidžia sukurti labai sudėtingas struktūras su įvairiausiais laukų tipais.
Trečia – Entries. Tai konkretūs turinio įrašai, sukurti pagal jūsų apibrėžtus modelius. Jei Content Model yra šablonas, tai Entry yra užpildytas šablonas su realiais duomenimis.
Registracija Contentful platformoje yra paprasta – jie siūlo nemokamą planą, kurio pakanka eksperimentams ir mažesniems projektams. Po registracijos gausite Space ID ir Access Token – šie du dalykai bus būtini integruojant sistemą į savo kodą.
Content modelių kūrimas ir struktūrizavimas
Kai pradėjau dirbti su Contentful, didžiausia klaida buvo per mažai laiko skirti content modelių planavimui. Vėliau teko viską perprojektuoti, o tai nėra maloni patirtis. Todėl patarimas – gerai apgalvokite savo turinio struktūrą iš anksto.
Contentful palaiko daugybę laukų tipų: Short text, Long text, Rich text, Number, Date, Boolean, Location, Media (paveikslėliai, video), JSON objektai ir, svarbiausia, References – nuorodos į kitus įrašus. Šis paskutinis tipas leidžia kurti sudėtingas ryšių struktūras.
Pavyzdžiui, kuriate e-commerce projektą. Galite turėti tokius modelius:
- Product – su laukais: pavadinimas, aprašymas, kaina, nuotraukos
- Category – kategorijos pavadinimas, aprašymas
- Brand – prekės ženklo informacija
- Review – atsiliepimai apie produktus
Product modelyje galite turėti reference laukus, kurie nurodo į Category ir Brand. Taip sukuriate ryšius tarp skirtingų turinio tipų. Kai vėliau gausiate produktą per API, galėsite automatiškai gauti ir susijusią kategoriją bei prekės ženklą.
Dar vienas svarbus dalykas – Localization. Contentful puikiai palaiko daugiakalbį turinį. Galite apibrėžti, kurie laukai bus lokalizuojami, o kurie bus vienodi visoms kalboms (pavyzdžiui, produkto kodas ar kaina).
API pasirinkimas: REST ar GraphQL
Contentful siūlo du API variantus, ir pasirinkimas tarp jų priklauso nuo jūsų projekto poreikių bei asmeninių preferencijų.
REST API yra paprastesnis ir intuityvesnis pradedantiesiems. Jis veikia per standartinius HTTP endpoint’us. Norėdami gauti visus blog įrašus, darytumėte užklausą į:
https://cdn.contentful.com/spaces/{SPACE_ID}/entries?access_token={ACCESS_TOKEN}&content_type=blogPost
REST API privalumai: paprasta pradėti, gera dokumentacija, lengva debuginti. Trūkumai: gali gauti daugiau duomenų nei reikia (over-fetching), reikia kelių užklausų susijusiems duomenims gauti.
GraphQL API yra galingesnis ir lankstesnis. Galite tiksliai nurodyti, kokių duomenų jums reikia:
{
blogPostCollection {
items {
title
slug
publishDate
author {
name
photo {
url
}
}
}
}
}
GraphQL privalumai: gaunate tiksliai tiek duomenų, kiek reikia, viena užklausa gali gauti sudėtingus susijusius duomenis, geresnė performance. Trūkumai: šiek tiek statesnis mokymosi kreivė, reikia papildomų įrankių (GraphQL klientų).
Asmeniškai dažniausiai naudoju GraphQL, nes jis leidžia optimizuoti užklausas ir sumažinti duomenų perdavimą. Bet jei projektas paprastas arba komandoje ne visi susipažinę su GraphQL, REST API yra puikus pasirinkimas.
Praktinis integravimas su JavaScript frameworkais
Pereikime prie konkretaus kodo. Contentful turi oficialius SDK įvairioms kalboms, bet JavaScript ekosistemoje dažniausiai naudojamas contentful npm paketas.
Pirmiausia įdiekite paketą:
npm install contentful
Paprastas pavyzdys su vanilla JavaScript:
const contentful = require('contentful');
const client = contentful.createClient({
space: 'jūsų_space_id',
accessToken: 'jūsų_access_token'
});
client.getEntries({
content_type: 'blogPost',
order: '-sys.createdAt',
limit: 10
})
.then(response => {
console.log(response.items);
})
.catch(console.error);
React integracija su hooks yra labai elegentiška. Galite sukurti custom hook:
import { useEffect, useState } from 'react';
import { createClient } from 'contentful';
const client = createClient({
space: process.env.REACT_APP_CONTENTFUL_SPACE_ID,
accessToken: process.env.REACT_APP_CONTENTFUL_ACCESS_TOKEN
});
export function useContentful(contentType) {
const [data, setData] = useState([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
useEffect(() => {
client.getEntries({ content_type: contentType })
.then(response => {
setData(response.items);
setLoading(false);
})
.catch(err => {
setError(err);
setLoading(false);
});
}, [contentType]);
return { data, loading, error };
}
Next.js integracija yra ypač įdomi, nes galite naudoti Static Site Generation (SSG) arba Server-Side Rendering (SSR):
export async function getStaticProps() {
const client = createClient({
space: process.env.CONTENTFUL_SPACE_ID,
accessToken: process.env.CONTENTFUL_ACCESS_TOKEN
});
const response = await client.getEntries({
content_type: 'blogPost'
});
return {
props: {
posts: response.items
},
revalidate: 60 // Incremental Static Regeneration
};
}
Svarbu: niekada nekiekite access token’ų į frontend kodą! Naudokite environment variables ir, jei įmanoma, proxy užklausas per savo backend’ą arba naudokite Next.js API routes.
Rich Text apdorojimas ir paveikslėlių optimizavimas
Viena iš sudėtingesnių Contentful integravimo dalių – Rich Text laukų apdorojimas. Contentful grąžina rich text turinį kaip JSON struktūrą, kurią reikia konvertuoti į HTML.
Naudokite @contentful/rich-text-react-renderer paketą React projektuose:
import { documentToReactComponents } from '@contentful/rich-text-react-renderer';
import { BLOCKS, INLINES } from '@contentful/rich-text-types';
const options = {
renderNode: {
[BLOCKS.EMBEDDED_ASSET]: (node) => {
const { url, title } = node.data.target.fields.file;
return ;
},
[BLOCKS.EMBEDDED_ENTRY]: (node) => {
// Custom komponentų renderinimas
return
},
[INLINES.HYPERLINK]: (node, children) => {
return {children};
}
}
};
function BlogPost({ content }) {
return
;
}
Dėl paveikslėlių optimizavimo – Contentful turi galingą Images API, kuris leidžia transformuoti paveikslėlius tiesiogiai URL parametrais:
// Originalus URL
https://images.ctfassets.net/space_id/asset_id/file_id/image.jpg
// Optimizuotas: 800px plotis, WebP formatas, 80% kokybė
https://images.ctfassets.net/space_id/asset_id/file_id/image.jpg?w=800&fm=webp&q=80
Galite sukurti helper funkciją:
function optimizeImage(url, width = 1200, format = 'webp', quality = 80) {
return `${url}?w=${width}&fm=${format}&q=${quality}`;
}
Tai leidžia dinamiškai generuoti skirtingo dydžio paveikslėlius responsive dizainui, neperkraunant serverio ar neįdiegiant papildomų image processing bibliotekų.
Webhooks ir realaus laiko atnaujinimai
Vienas iš Contentful privalumų – webhooks funkcionalumas. Galite nustatyti, kad Contentful automatiškai praneštų jūsų sistemai, kai turinys pasikeičia.
Tai ypač naudinga static site’ams. Pavyzdžiui, naudojate Next.js su SSG ir turite blog’ą. Kai turinio redaktorius publikuoja naują straipsnį Contentful, webhook gali automatiškai paleisti rebuild procesą Vercel ar Netlify platformoje.
Contentful webhooks konfigūracija:
- Eikite į Settings → Webhooks
- Sukurkite naują webhook
- Nurodykite URL, į kurį bus siunčiami pranešimai
- Pasirinkite, kokius įvykius norite sekti (publish, unpublish, delete)
- Galite filtruoti pagal content type
Jūsų serverio endpoint’as galėtų atrodyti taip (Express.js pavyzdys):
app.post('/webhook/contentful', (req, res) => {
const { sys } = req.body;
// Patikrinkite webhook signature saugumo tikslais
const signature = req.headers['x-contentful-webhook-signature'];
if (sys.type === 'Entry' && sys.contentType.sys.id === 'blogPost') {
// Paleiskite rebuild procesą
triggerBuild();
}
res.status(200).send('OK');
});
Vercel integracijai galite naudoti Deploy Hooks:
async function triggerBuild() {
await fetch('https://api.vercel.com/v1/integrations/deploy/...', {
method: 'POST'
});
}
Taip pasiekiate, kad jūsų svetainė automatiškai atsinaujintų, kai turinys pasikeičia, išlaikant static site performance privalumus.
Kai viskas sudėliota į lentynėles
Contentful integravimas iš pirmo žvilgsnio gali atrodyti sudėtingas, bet iš tikrųjų tai gana tiesmuka procedūra, jei žinote pagrindinius principus. Svarbiausias dalykas – gerai suplanuoti content modelius iš anksto. Vėliau juos keisti yra įmanoma, bet tai sukuria papildomo darbo.
Pasirinkimas tarp REST ir GraphQL API priklauso nuo jūsų komandos įgūdžių ir projekto sudėtingumo. Pradedantiesiems rekomenduočiau REST, o sudėtingesniems projektams – GraphQL. Abi opcijos veikia puikiai ir turi gerą dokumentaciją.
Nepamirškite environment variables saugumui, naudokite Contentful Images API paveikslėlių optimizavimui ir išnaudokite webhooks automatizavimui. Jei kuriate static site’ą, Incremental Static Regeneration (Next.js) arba webhooks su auto-rebuild yra būtini dalykai.
Dar vienas patarimas – naudokite Contentful Preview API development metu. Tai leidžia matyti unpublished turinį, kas labai patogu testuojant. Tiesiog naudokite preview access token vietoj delivery access token.
Galiausiai, jei projektas auga ir turite daug užklausų, apsvarstykite caching strategiją. Galite naudoti Redis, Next.js automatic caching arba tiesiog in-memory cache paprastesniems atvejams. Contentful API yra greitas, bet nėra prasmės daryti tą pačią užklausą šimtą kartų per minutę.
Contentful nėra vienintelis headless CMS rinkoje – yra Strapi, Sanity, Prismic ir kiti. Bet Contentful išsiskiria patogumu, dokumentacija ir ekosistema. Jei dar neišbandėte headless CMS koncepcijos, Contentful yra puikus būdas pradėti. Nemokamas planas leidžia eksperimentuoti be jokių įsipareigojimų, o kai projektas išauga, scaling yra sklandus.