Term Actions – astrojs-wp-integration

Term actions let you create, update, and delete WordPress taxonomy terms from Astro server-side code.

They support built-in taxonomies (categories, tags) and custom taxonomies by passing the taxonomy REST resource.

Actions overview Shared auth patterns, validation layers, and ActionError behavior.

Post actions Content resource actions for posts, pages, and custom post types.

Setup

1. Register term action factories in your Astro src/actions/index.ts.
2. Choose the target taxonomy endpoint via resource.
3. Call the actions from server components, endpoints, or form handlers.

import {
  createCreateTermAction,
  createUpdateTermAction,
  createDeleteTermAction,
} from 'wp-astrojs-integration';
import { WordPressClient } from 'fluent-wp-client';

const wp = new WordPressClient({
  baseUrl: import.meta.env.WP_URL,
  auth: {
    username: import.meta.env.WP_USERNAME,
    password: import.meta.env.WP_APP_PASSWORD,
  },
});

export const server = {
  createCategory: createCreateTermAction(wp, { resource: 'categories' }),
  updateTag: createUpdateTermAction(wp, { resource: 'tags' }),
  deleteGenre: createDeleteTermAction(wp, { resource: 'genres' }),
};

Creating and updating terms

Category

const { data } = await Astro.callAction(actions.createCategory, {
  name: 'Newsroom',
  slug: 'newsroom',
  description: 'Editorial updates and announcements.',
});

Tag

const { data } = await Astro.callAction(actions.updateTag, {
  id: 25,
  name: 'editorial',
});

Custom taxonomy term

import { WordPressClient } from 'fluent-wp-client';
import { createCreateTermAction } from 'wp-astrojs-integration';

const wp = new WordPressClient({
  baseUrl: import.meta.env.WP_URL,
  auth: { username: import.meta.env.WP_USERNAME, password: import.meta.env.WP_APP_PASSWORD },
});

const createGenre = createCreateTermAction(wp, { resource: 'genres' });

const created = await Astro.callAction(createGenre, {
  name: 'Science Fiction',
  slug: 'science-fiction',
});

Deleting a term

Term deletion behavior

WordPress term deletion is permanent in REST workflows. Use delete actions carefully in production.

const { data } = await Astro.callAction(actions.deleteGenre, {
  id: 42,
  force: true,
});

// data -> { id: 42, deleted: true }

Typed input and response overrides

Use schema to validate custom term payload fields and responseSchema for typed result parsing.

import { z } from 'astro/zod';
import { WordPressClient } from 'fluent-wp-client';
import { createCreateTermAction, createTermInputSchema } from 'wp-astrojs-integration';

const wp = new WordPressClient({
  baseUrl: import.meta.env.WP_URL,
  auth: { username: import.meta.env.WP_USERNAME, password: import.meta.env.WP_APP_PASSWORD },
});

const createGenre = createCreateTermAction(wp, {
  resource: 'genres',
  schema: createTermInputSchema.extend({
    custom_label: z.string().optional(),
  }),
  responseSchema: z.object({
    id: z.number().int().positive(),
    taxonomy: z.literal('genre'),
    name: z.string(),
  }),
});

Execute helpers

The raw execute helpers are useful in tests and custom wrappers.

import {
  executeCreateTerm,
  executeUpdateTerm,
  executeDeleteTerm,
} from 'wp-astrojs-integration';
import { WordPressClient } from 'fluent-wp-client';

const wp = new WordPressClient({
  baseUrl: 'https://example.com',
  auth: { username: 'admin', password: 'app-password' },
});

const created = await executeCreateTerm(wp, { name: 'Release Notes' }, { resource: 'tags' });
await executeUpdateTerm(wp, { id: created.id, slug: 'release-notes' }, { resource: 'tags' });
await executeDeleteTerm(wp, { id: created.id, force: true }, { resource: 'tags' });