Вышла бета-версия нового плагина Gatsby Source для WordPress с улучшениями и новыми возможностями для разработчиков

Подключайте WP-контент напрямую через GraphQL без громоздких обходов. Никаких REST-заголовков, никаких танцев с кастомными post-type. Всё прозрачно. Что делать: указывайте endpoint, активируйте доступ к записям, страницам, медиа и пользовательским типам данных. Всё.

Пример конфигурации:

module.exports = {
plugins: [
{
resolve: `gatsby-source-wp`,
options: {
url: `https://example.com/graphql`,
type: {
Post: { limit: 50 },
Page: { excludeFieldNames: [\'blocks\'] }
},
debug: {
graphql: true,
time: true
}
}
}
]
}

Уже есть поддержка для ACF, Yoast, Polylang. Не нужен ни один костыль. Всё забирается по схеме, всё можно видеть в GraphiQL. Обновляется мгновенно. Запросили ACF-поле из кастомного типа? Пришло. Без пробелов. Без зависаний.

Раздражают медленные запросы? Включите параметр schema.timeout. Задержка в 15 секунд? Забудьте. Ускорение видно сразу. Страницы летят. А ещё можно исключать поля прямо в настройках. Не нужно ковырять GraphQL вручную.

Работает даже с Headless-конфигурациями, где админка живёт на поддомене. Указывайте разные базовые адреса для чтения и авторизации. Всё тянется как часы. И, внимание, можно напрямую цепляться к локальной разработке через ngrok или аналогичные туннели – структура сохраняется.

Важно: Если используете Polylang, обязательно проверьте, активен ли REST маршрут /wp-json/wp/v2/languages. Без него локализация работать не будет.

Фичи, которые стоит отключить: lazy images, embedded media. Они замедляют build. Используйте кастомные трансформеры. Или вручную очищайте граф по ID, чтобы не грузить лишнее. Всё это легко конфигурируется. Опции читаются ясно.

Что с безопасностью? Запросы можно ограничить через CORS. Добавляйте API-ключи на сторону WP через Application Passwords. Работает стабильно. Запрос без ключа – 403. Так и должно быть.

Внимание! Не используйте мутации из публичного GraphQL интерфейса – оставьте только чтение. Иначе получите дыру в админке.

Интересный момент: можно использовать custom fragments и объединять их по типу данных. Не хотите повторять описание записей в каждом шаблоне? Создайте общую выборку в отдельном файле, импортируйте. Всё динамически обновляется.

Всё выглядит как стройная конструкция, но чуть не туда – и ломается весь build. Ошибка schema stitching? Значит, где-то поле без типа. Следите за консолью. Там всё по делу. Всё по логам. Ни одной лишней строки.

Итог? Если вы на WP и хотите тянуть данные напрямую, без посредников и без боли – это то, что нужно. Только проверьте каждое поле. Каждую ссылку. И не забудьте: schema может меняться, даже если вы не меняли ничего. WordPress непредсказуем. Проверяйте каждый merge. Всегда.

Как подключить новую бета-версию Gatsby Source к существующему сайту на WordPress

Сначала – отключите кэширование REST API. Особенно если используете WP Super Cache или W3 Total Cache. Без этого вы получите урезанные JSON-ответы и сломанные связи между сущностями. Просто добавьте фильтр:

add_filter( \'rest_cache_skip_cache\', \'__return_true\' );

Далее – проверьте, активен ли REST API JSON endpoint. Зайдите на https://ваш-сайт/wp-json. Ошибка 403? Значит, доступ ограничен через .htaccess или плагин безопасности. Отключите защиту временно или настройте исключение по пути /wp-json.

Теперь установите зависимость в проекте на Node.js:

npm install gatsby-source-wordpress@canary

Да, именно канарейка. Иначе никакой синхронизации с preview и ACF не будет.

В конфигурационном файле gatsby-config.js подключите источник:


{
resolve: \"gatsby-source-wordpress\",
options: {
url: \"https://ваш-сайт/graphql\",
schema: {
timeout: 30000,
},
type: {
MediaItem: {
localFile: {
requestConcurrency: 5,
},
},
},
html: {
fallbackImageMaxWidth: 1024,
},
},
}


Внимание! Если GraphQL endpoint не работает, убедитесь, что установлен модуль WPGraphQL версии не ниже 1.15.0.

Подключение ACF-полей:


npm install @wordpress/acf


И не забудьте разрешить экспорт ACF в GraphQL:


add_filter( \'acf/settings/remove_wp_meta_box\', \'__return_false\' );


Важно: некоторые поля ACF не отображаются, если не указана явная поддержка в группе полей через флаг Show in GraphQL.

Следующий шаг – запуск синхронизации данных:

gatsby clean && gatsby develop

Ошибка \»Cannot query field\»? Вы используете устаревшую схему GraphQL. Очистите кэш WordPress, пересохраните постоянные ссылки, обновите WPGraphQL.

Помните: если ваш проект использует кастомные пост-типы – они должны быть зарегистрированы с параметром show_in_graphql: true, иначе ничего не загрузится.

Да, кажется просто. Но попробуйте сделать это без точной настройки таймингов, кешей, GraphQL и ACF – и вы утонете в бесконечных 404 и пустых полях. Чувствуете?

Итог: всё работает, только если строго соблюдены зависимости, права доступа, настройки схемы и параметры GraphQL. Иначе – хаос. Или белый экран.

Что изменилось в передаче данных через GraphQL между WordPress и Gatsby

Уберите __typename из запросов – теперь этот системный ключ вызывает конфликты при сериализации. Вместо него используйте ручную проверку типа через пользовательские поля или схемы.

Главное нововведение – инкрементальная передача данных. Больше не нужно тянуть весь контент при каждой сборке. Изменился только один пост? Забирается только он. Работает быстрее. Сильно быстрее. Но есть нюанс: необходимо включить persistent cache и настроить fast builds.

Новая схема GraphQL больше не использует префиксы типа WpPost, WpPage. Стало короче, но рушит старые фрагменты. Внимание к кастомным GraphQL-запросам – потребуется пересборка всех фрагментов, особенно вложенных.

Важно! После обновления схемы GraphQL старые запросы часто возвращают null или пустые массивы. Проверьте наличие всех нужных связей вручную.

Типизация полей стала строже. Если раньше можно было вытянуть поле author.name без лишних условий, теперь обязательно проверять наличие объекта author, иначе – ошибка сборки:


query GetPost {
  post(id: \"123\") {
    title
    author {
      name
    }
  }
}


Убрана автоматическая генерация excerpt по умолчанию. Хочешь краткий текст? Создавай поле сам. Иначе GraphQL вернет пустоту.

Добавлена поддержка вложенных ACF-полей через node linking. Но это работает только при включенной опции useACFOption в настройках. Без нее поля разваливаются в null. Не забудь.

Помните! Любое изменение структуры GraphQL требует полной перегенерации схемы. Без этого кеш продолжит отдавать устаревшие типы.

Больше нельзя использовать мутации. Только чтение. Вся логика записи – через REST или отдельные admin-endpoints. GraphQL строго на стороне потребителя, без обходных путей.

Поддержка многоязычности теперь через отдельные ноды – Polylang и WPML создают новые типы с флагами языка. Перестали поддерживаться inline-переводы. Это ломает структуру фронта. Учти это заранее.

Добавлены алиасы для повторяющихся нод. Теперь можно безопасно запрашивать две галереи в одном запросе, без переопределения ключей:


query {
  firstGallery: mediaItem(id: \"abc\") { sourceUrl }
  secondGallery: mediaItem(id: \"def\") { sourceUrl }
}


В итоге: больше гибкости, но и больше ловушек. GraphQL стал злее. И требовательнее. Работает быстро, но без пощады к ошибкам.

Как использовать поддержку кастомных типов записей в новой версии плагина

Сначала добавьте нужные post type в параметр type внутри конфигурации подключения:


module.exports = {
plugins: [
{
resolve: `gatsby-source-wordpress`,
options: {
url: `https://example.com/graphql`,
type: {
Post: {},
Page: {},
MyCustomPost: {},
},
},
},
],
}


Не забудьте: кастомные типы должны быть зарегистрированы через register_post_type с аргументом show_in_graphql => true. Без этого схема GraphQL не увидит их. Всё.

Внимание! Если вы используете ACF и поле привязано к кастомному типу, убедитесь, что ACF Field Group тоже доступен через GraphQL.

Вызовите схему на /graphql и проверьте, появился ли тип myCustomPost. Не отображается? Причина почти всегда в некорректной регистрации или отсутствии REST/GraphQL-экспорта. Убедитесь, что параметры show_in_rest и show_in_graphql включены. Без них – тишина.

Структура данных отличается. Не рассчитывайте, что поля от Post совпадают с кастомным типом. Даже slug и excerpt могут отсутствовать. Проверяйте поля в схеме. Не гадайте.

Нейминг GraphQL-типа важен. Если вы назвали тип case_study, в GraphQL он может появиться как CaseStudy. Это капкан. Убедитесь, что имя типа в конфиге совпадает с GraphQL-схемой. Ошибка в регистре – всё ломается.

Важно помнить: При использовании кастомных типов, pagination работает иначе. Проверяйте pageInfo и hasNextPage вручную.

Пример запроса:


query GetCustomPosts {
myCustomPosts {
nodes {
title
content
slug
}
}
}


Появился тип, но данных нет? Проверяйте права доступа. Приватные записи не попадают в выборку без авторизации. Механизм авторизации через headers – отдельно настраивается.

И ещё. Если добавили новый тип, пересоберите схему через gatsby clean. Иначе данные не подтянутся. Не надейтесь на hot reload. Не работает.