@tiebreak-websites/astro

Tiebreak Astro components, styles, helpers, WordPress integrations, and more.

Installation

npm install @tiebreak-websites/astro

WordPress API

The package includes helper modules under api/wp for reading WordPress REST API data from Astro projects.

All WordPress requests use the shared helpers in api/wp/wordpress.js:

• getWpUrl(astro) resolves the WordPress base URL.
• wpQueryParams(params) builds the default query string.
• wpFetch(url, params, options) adds default query params and WordPress auth headers.
• getWpRequestUrl(url, params) returns the final URL used by wpFetch.

Environment Variables

Configure the WordPress connection in your Astro environment:

WP_URL=https://example.com/
SITE_LANG=en
WP_ENV=production

Optional variables for authenticated WordPress requests:

WP_USER=wordpress-user
WP_APP_PASSWORD=wordpress-application-password

When WP_USER and WP_APP_PASSWORD are set, requests include:

Authorization: Basic <base64-user-and-application-password>

When WP_ENV=dev and auth is available, default WordPress status becomes publish,pending,private. Otherwise it is publish.

For local development with self-signed certificates:

IS_LOCAL=true

Astro Context

Most helpers accept an optional astro argument. Pass the Astro global object when you need middleware-provided values:

const page = await getPage('about', Astro);

getWpUrl(astro) checks astro.locals.wpUrl first and falls back to import.meta.env.WP_URL.

getWpLang(astro) checks astro.locals.lang first and falls back to SITE_LANG or en.

Default Query Params

wpFetch applies these defaults to every request:

{
  orderby: 'menu_order',
  order: 'asc',
  per_page: 100,
  status: 'publish'
}

Pass params to override or extend them:

import { wpFetch } from '@tiebreak-websites/astro/api/wp/wordpress.js';

const wpUrl = import.meta.env.WP_URL;
const response = await wpFetch(`${wpUrl}wp-json/wp/v2/pages`, {
  slug: 'about',
  per_page: 1,
});

const pages = await response.json();

Existing query params in a URL are preserved and merged:

await wpFetch(`${wpUrl}wp-json/wp/v2/posts?_fields=id,title`, {
  per_page: 5,
});

Common Data Loader

Use wordpressDataLoader to load common website data and an optional page in one call:

import { wordpressDataLoader } from '@tiebreak-websites/astro/api/wp/loader.js';

const website = await wordpressDataLoader({
  astro: Astro,
  page: 'about',
});

It returns global data such as options and menus, plus the requested page. Common data is cached per language during builds. In WP_ENV=dev, it refreshes on every call.

You can pass extra values and they will be merged into the returned object:

const website = await wordpressDataLoader({
  astro: Astro,
  page: 'contact',
  formName: 'contact-form',
});

Pages

import {
  getPage,
  getPageById,
  getAllPages,
  getRootPages,
  getSubPages,
  getAllSubPages,
} from '@tiebreak-websites/astro/api/wp/pages.js';

const page = await getPage('about', Astro);
const pageById = await getPageById(123, Astro);
const pages = await getAllPages(Astro);
const rootPages = await getRootPages(Astro);
const childPages = await getSubPages('parent-page', Astro);
const allChildPages = await getAllSubPages(Astro);

Posts

import { getPostById } from '@tiebreak-websites/astro/api/wp/posts.js';

const post = await getPostById(123);

Custom Post Types

import {
  getCptItems,
  getCptById,
  getCptBySlug,
  getCptTotal,
} from '@tiebreak-websites/astro/api/wp/custom-post-types.js';

const announcements = await getCptItems('announcement');
const pagedAnnouncements = await getCptItems('announcement', {
  page: 2,
  per_page: 25,
  orderby: 'date',
  order: 'desc',
});

const announcement = await getCptBySlug('announcement', 'example-slug');
const announcementById = await getCptById('announcement', 123);
const total = await getCptTotal('announcement');

Forms

import {
  getForms,
  getForm,
  getFormById,
} from '@tiebreak-websites/astro/api/wp/forms.js';

const forms = await getForms(Astro);
const contactForm = await getForm('contact', Astro);
const formById = await getFormById(123, Astro);

Media

import { getMedia, getPdfFiles } from '@tiebreak-websites/astro/api/wp/media.js';

const image = await getMedia(123, Astro);
const pdfFiles = await getPdfFiles({}, Astro);

getPdfFiles returns an object keyed by file ID. Each item includes a localUrl where the WordPress base URL is replaced with /_assets/files/.

If the languages endpoint returns a 404 response body, the helpers return English as a fallback.

Static Paths

Use these helpers in Astro getStaticPaths functions:

import {
  getStaticPathsRoot,
  getStaticPathsSubPages,
} from '@tiebreak-websites/astro/api/wp/static-paths.js';

export async function getStaticPaths() {
  const pages = await getStaticPathsRoot();

  return pages.map((page) => ({
    params: { slug: page.slug },
    props: { page },
  }));
}

TablePress

import {
  getSheetAndCosts,
  getSheetAndCostsStaticPaths,
  getPageSheetAndCostsPaths,
} from '@tiebreak-websites/astro/api/wp/tablepress.js';

const table = await getSheetAndCosts(123, Astro);
const tableIds = await getSheetAndCostsStaticPaths(Astro);
const pageTableIds = await getPageSheetAndCostsPaths('about', Astro);

Auth Helpers

Use these only when you need direct access to WordPress authentication state:

import {
  hasWpAuth,
  getWpAuthToken,
  getWpAuthHeaders,
} from '@tiebreak-websites/astro/api/wp/auth.js';

if (hasWpAuth()) {
  const headers = getWpAuthHeaders();
}

Most code should use wpFetch instead of calling these directly.

HTML Content Helpers

Use processWpImages to rewrite image URLs in WordPress HTML content:

import { processWpImages } from '@tiebreak-websites/astro/api/wp/process-content.js';

const html = processWpImages({
  html: page.content.rendered,
  wpUrl: import.meta.env.WP_URL,
  relative: true,
});

With relative: true, image URLs are rewritten to start at /wp-content. With relative: false, relative image URLs are converted back to absolute WordPress URLs.

Middleware

The middleware in api/util/middleware.ts is meant for SSR language switching. In practice, it inspects the incoming request and picks the active language from the subdomain, for example de.example.com or fr.example.com, then stores the resolved values in context.locals so the WordPress helpers can use the right endpoint.

How it works:

• It runs only when SSR is enabled.
• It checks the request host first for subdomain-based language detection.
• It falls back to a path-based match if needed.
• It writes context.locals.lang and context.locals.wpUrl, which helpers such as getWpUrl() and getWpLang() can consume.

How to use it in Astro:

1. Create a language mapping file in your project at src/data/languages.json:

[
  { "code": "en", "wpUrl": "https://wordpress.plexop.dev/fiversity/" },
  { "code": "de", "wpUrl": "https://wordpress.plexop.dev/fiversity/de/" }
]

2. Add an Astro middleware entrypoint:

// src/middleware.ts
import { onRequest } from '@tiebreak-websites/astro/api/util/middleware.ts';

export { onRequest };

3. Make sure your Astro project uses SSR (output: 'server' or output: 'hybrid') and that the middleware is enabled for the deploy target.

If no language config file is present, the middleware falls back to the default WordPress URL from import.meta.env.WP_URL and the en language.

Recommended Usage

Prefer the specific helper modules for common data needs, such as getPage, getMenuAll, or getCptItems.

Use wpFetch when you need a custom WordPress endpoint that does not already have a helper.

Pass Astro to helpers when middleware can override astro.locals.wpUrl or astro.locals.lang.