Логотип ForgeCMSForgeCMS
Переглянути документацію

Документаціяv1.0.0 стабільна

Початок роботи

Вступ

Що таке ForgeCMS, що вона вже вміє і чого поки не вміє.

ForgeCMS — це основа для CMS із підходом code-first, нативна для TypeScript, з повноцінною підтримкою Angular, Analog.js і Cloudflare.

Ви описуєте свій контент у TypeScript:

import { defineCollection, defineField } from '@forge-cms/core';

export const posts = defineCollection({
  slug: 'posts',
  drafts: true,
  fields: {
    title: defineField.text({ required: true }),
    slug: defineField.slug({ autoGenerate: true, sourceField: 'title' }),
    body: defineField.richtext(),
    cover: defineField.upload({ collection: 'media' }),
    author: defineField.relation({ collection: 'users' })
  }
});

…і це одне визначення керує схемою бази даних, валідацією під час виконання, REST API, формою в адмін-панелі та типами, які ви отримуєте у своєму Angular-застосунку. Немає жодного файлу схеми, який треба синхронізувати, і жодного кроку генерації коду.

Навіщо вона існує

Кожна серйозна headless CMS у цій ніші розрахована на React. Payload, Strapi і Sanity постачають адмін-панелі на React і клієнтські бібліотеки, створені під React; використовувати їх з Angular означає запускати чужий фреймворк поруч зі своїм або вручну писати клієнт для REST API, який ви не проєктували.

ForgeCMS починає з протилежного боку: сигнали Angular, серверні маршрути Analog.js, адмін-панель із компонентів Angular, які можна імпортувати, і Local API, яку ви викликаєте безпосередньо із серверного коду, — без жодного HTTP-запиту між вашим маршрутом Analog і вашим контентом.

Що вже працює

  • DSL схем і валідація — 15 типів полів, зокрема group, array і blocks (примітив для побудови сторінок), які валідуються під час виконання при кожному записі.
  • Типізований Local API — find, findOne, findByID, create, update, delete, count на об’єкті runtime, що виконують повний конвеєр (контроль доступу, хуки, чернетки, заповнення зв’язків, валідацію) і виводять типи документів із визначень ваших колекцій.
  • REST API — CRUD із фільтрацією (зокрема вкладеними and/or), сортуванням за кількома полями, пагінацією, заповненням зв’язків і видимістю чернеток, у стабільному форматі відповіді.
  • Контроль доступу у вигляді функцій — правило може повернути true/false або запит, який звужує коло документів, до яких може торкатися операція (правила на рівні рядків на кшталт «автори редагують лише власні публікації»).
  • Повний конвеєр хуків — дев’ять етапів для колекцій плюс хуки для окремих полів.
  • Справжня автентифікація — користувачі зберігаються у вашій базі даних із хешуванням PBKDF2, сесії на cookie із захистом від CSRF, ключі API з обмеженими правами та ролі admin/editor/viewer.
  • Життєвий цикл контенту — чернетки, версії документів із відновленням, живий попередній перегляд, globals, локалізація та правила цілісності зв’язків під час видалення.
  • Завантаження файлів — створення через multipart/form-data за допомогою StorageAdapter, з обробником для видачі файлів.
  • Адаптери — in-memory, LibSQL/Turso і Cloudflare D1 для бази даних; in-memory і R2 для сховища; усі вони проходять спільний набір контрактних тестів.
  • Angular-клієнт та адмін-панель — CmsApiService плюс ресурси на основі сигналів, сесія на cookie і guard маршруту, а також адмін-панель, яку ви монтуєте під власними маршрутами (контент, користувачі, вхід).

Що є експериментальним

Будьте чесні із собою щодо цього списку, перш ніж застосовувати ForgeCMS для чогось важливого:

  • Стабільна версія 1.0. Фіксоване сімейство з дванадцяти пакетів опубліковано у версії 1.0.0. Прийнятий кандидат 1.0.0-rc.2 залишається частиною історії випусків. Встановлюйте стабільні пакети однакових версій; експериментальні Agent Kit і Cloudflare Analytics не входять до гарантії сумісності 1.x. Див. Support and compatibility (англійською).
  • Оновлення схеми є явними. Синхронізація схеми застосовує безпечні адитивні зміни й відхиляє розбіжності, що потребують міграції даних. Перевірені міграції застосовують такі зміни з вашого скрипту розгортання рівно один раз. Зворотних міграцій немає. Оновлення зі старіших випусків, а також резервне копіювання й відновлення відпрацьовуються в CI на libSQL і локальних D1/R2, а резервне копіювання та ізольоване відновлення профілю Cloudflare відпрацьовано на реальному ізольованому staging-середовищі Cloudflare. Див. Schema upgrades (англійською).
  • Заповнення зв’язків має глибину лише в один рівень (depth: 1), а всередині складених JSON- значень виконувати запити не можна.
  • SSR використовує явно заданий серверний origin. Публічні сторінки рендеряться й гідратуються з provideForgeCmsServer і клієнтом з credentials: 'omit' (див. SSR, англійською); серверні маршрути й надалі можуть викликати Local API безпосередньо.
  • Надійне сховище — це R2 або S3. @forge-cms/s3 охоплює S3-сумісні сервіси (Garage сертифіковано в CI; AWS S3, B2 і Wasabi можна налаштувати, але вони не сертифіковані). Сховище in-memory призначене лише для розробки.
  • Немає адаптера електронної пошти, системи плагінів чи CLI.

Як поєднуються частини

Your Angular app  ──►  @forge-cms/angular  ──►  HTTP /api/v1/*  ──┐
                                                                  ├─►  @forge-cms/runtime  ──►  adapters (db / auth / storage)
Your server route ──►  runtime.find(...)  (Local API, no HTTP)  ──┘

@forge-cms/core визначає схему, @forge-cms/runtime виконує операції, а пакети адаптерів спілкуються із зовнішнім світом. Повну картину див. у Core concepts (англійською).

Куди рухатися далі

Репозиторій також містить записи для мейнтейнерів: docs/STATE.md (що реалізовано, пакет за пакетом), docs/ARCHITECTURE.md і docs/specs/ (одна специфікація на функцію з обґрунтуванням рішень).