woo-rest-headless

A generic, framework-agnostic client for using WooCommerce and WordPress as a headless backend. Designed for React, Vue, Next.js, Angular, Svelte, and Node.js.

Prerequisites

Important: This package relies on the woo-rest-headless-plugin to expose necessary endpoints and enable enhanced headless functionality (like CORS, customized menus, and auth).

• Download & Install Plugin
• Ensure the plugin is active on your WordPress site.

Installation

npm install woo-rest-headless

Easy Mode (Global Helpers)

This is the recommended way to use the library in web frameworks like Next.js, Nuxt, etc.

1. Initialize (e.g., in a layout or plugin file)

import { initWrh } from "woo-rest-headless";

initWrh({
  baseUrl: "https://your-wordpress-site.com",
  consumerKey: "ck_xxxxxxxx",
  consumerSecret: "cs_xxxxxxxx",
  debug: false,
});

2. Use Anywhere

Once initialized, you can import and use helpers directly in your components or pages.

import {
  wrh_products,
  wrh_product,
  wrh_page,
  wrh_menu,
} from "woo-rest-headless";

// Get list of products
const products = await wrh_products({ per_page: 8 });

// Get single product
const product = await wrh_product(12345);

// Get page by Slug
const aboutPage = await wrh_page("about-us");

// Get Menu
const primaryMenu = await wrh_menu("primary");

Health Check & Verification

You can verify your API connection (REST, WooCommerce, GraphQL) using the built-in CLI tool or helper function.

CLI Usage (Recommended)

Run this command in your terminal to quickly check your site's health.

npx wrh-verify --url https://your-site.com --consumer-key ck_... --consumer-secret cs_... --graphql-url /graphql

Programmatic Usage

import { wrh_health_check } from "woo-rest-headless";

const health = await wrh_health_check({ graphQLEndpoint: "/graphql" });
console.log(health);
// {
//   restApi: true,
//   wooCommerce: true,
//   graphQL: true,
//   messages: ['✅ ...', '✅ ...']
// }

Classic Usage (Class Instance)

If you prefer dependency injection or multiple instances:

import { WooRestHeadless } from "woo-rest-headless";

const api = new WooRestHeadless({
  baseUrl: "https://your-site.com",
  /* ... */
});

const products = await api.products.list();
const orders = await api.orders.list();
const customers = await api.customers.list();
const siteSettings = await api.settings.get();

// GraphQL
const query = `
  query GetRecentPosts {
    posts(first: 3) {
      nodes {
        id
        title
      }
    }
  }
`;
const data = await api.graphql(query);

Features

• Universal Support: Works with Next.js, Nuxt, React, Vue, Svelte, Angular, etc.
• Global Helpers: Simple efficient API: wrh_product, wrh_page, etc.
• Health Checks: Built-in CLI and API to verify connection status.
• WooCommerce Modules:
  • products, categories, orders, customers, coupons
  • paymentGateways, shipping, taxes
  • reports, systemStatus, refunds
• WordPress Modules:
  • posts, pages, media, menus (requires plugin)
  • users, comments, tags, taxonomies, settings
• GraphQL: Generic support for arbitrary queries.
• TypeScript: Fully typed.
• OpenAPI / Swagger: Generated specs available in docs/.

Docs & API Reference

Complete API documentation usually generated via TypeDoc is available in docs/html/index.html. Swagger specifications for both WordPress and WooCommerce APIs are provided in docs/.

License

MIT

About the Author

Built with ❤️ by Ruhul Amin

• Portfolio: ruhul0.com
• GitHub: github.com/ruhul0
• LinkedIn: linkedin.com/in/ruhul0
• Support: Buy Me a Coffee