wpapi

library1.2.2jsnpmunverified

An isomorphic JavaScript client for the WordPress REST API, enabling query-builder-style requests from Node.js or browser environments. Current stable version is 1.2.2, with a release cadence of major versions every few years. Key differentiators: built for the official WordPress REST API (WordPress 5.0+), supports auto-discovery, custom routes, media uploads, pagination, and embedding. Unlike generic HTTP clients, wpapi provides fluent methods for posts, comments, categories, tags, and custom post types, with built-in authentication support (Basic Auth, OAuth, nonces).

cms

npm install wpapi

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WPAPI

wpapi

cmsjavascriptv1.2.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WPAPI

✓ import WPAPI from 'wpapi'

✗ const wpapi = require('wpapi')

Default export, not named. In TypeScript, use `import WPAPI from 'wpapi'` or `const WPAPI = require('wpapi').default` for CommonJS.

EndpointRequest

✓ import WPAPI from 'wpapi'; const request = WPAPI.EndpointRequest;

✗ const { EndpointRequest } = require('wpapi')

EndpointRequest is a static property of WPAPI, not a separate export. Use WPAPI.EndpointRequest after default import.

registerRoute

✓ const site = new WPAPI({ endpoint: 'https://example.com/wp-json' }); site.registerRoute('myplugin/v1', '/resource/(?P<id>\\d+)')

✗ import { registerRoute } from 'wpapi'

registerRoute is an instance method, not a static function. Must be called on a WPAPI instance.

Demonstrates basic CRUD operations: fetching categories, creating a post with auth, and updating a post by ID.

import WPAPI from 'wpapi'; async function main() { const site = new WPAPI({ endpoint: process.env.WP_ENDPOINT || 'https://wordpress.org/wp-json', username: process.env.WP_USERNAME ?? '', password: process.env.WP_PASSWORD ?? '' }); // Fetch categories const categories = await site.categories().get(); console.log('Categories:', categories); // Create a new post if (site.username && site.password) { const post = await site.posts().create({ title: 'Hello from node-wpapi', content: 'This post was created via the REST API.', status: 'draft' }); console.log('Post created:', post.id); } // Update a post if (site.username && site.password) { const updated = await site.posts().id(1).update({ title: 'Updated title' }); console.log('Post updated:', updated.title) } } main().catch(console.error);

Debug

Known issues

breakingUsage with WordPress versions older than 5.0 is not officially supported; some endpoints may not exist or behave differently.

fix

Ensure your WordPress site runs version 5.0 or later. For older versions, use the WP REST API plugin and check compatibility.

affects: <1.0

gotchaMethods like `posts()`, `comments()` etc. return a handler instance, not a Promise. Chain `.get()`, `.create()`, `.update()`, `.delete()` to execute the request.

fix

Call `.get()` or similar at the end: `site.posts().get()` returns a Promise.

affects: >=0.1.0

gotchaThe `.embed()` method must be called before the HTTP method (e.g., `.get()`) to include embedded data.

fix

Use `site.posts().embed().get()` instead of `site.posts().get().embed()`.

affects: >=0.1.0

deprecatedThe `.param()` method is deprecated in favor of using setter methods directly (e.g., `.perPage()`, `.page()`, `.categories()`) or passing an object to the handler.

fix

Use dedicated setter methods: `site.posts().perPage(10).get()` instead of `site.posts().param('per_page', 10).get()`.

affects: >=1.0.0

gotchaIf using Basic Auth, the library does not send credentials automatically unless you pass `username` and `password` in constructor options or use `.auth()` method. CORS issues may arise in browsers.

fix

Always set auth on the instance: `new WPAPI({ endpoint, username, password })` or call `site.auth({ username, password })`.

affects: >=0.1.0

Errors

Common errors & fixes

Cannot find module 'wpapi'

Missing npm installation or incorrect import path.

fix

Run `npm install --save wpapi` and ensure import/require path is correct: `import WPAPI from 'wpapi'`.

TypeError: site.posts is not a function

Instantiating WPAPI incorrectly; likely not awaiting the constructor or using wrong variable.

fix

Correct usage: `const site = new WPAPI({ endpoint: 'https://example.com/wp-json' }); site.posts().get();`

401 Unauthorized

Missing or incorrect authentication credentials when accessing protected endpoints (create/update/delete).

fix

Provide `username` and `password` in the constructor or use `.auth()` method. Ensure the user has appropriate capabilities.

Cannot read property 'id' of undefined

Trying to access property on a response that is not the expected object; often because `.get()` returns an array for collections.

fix

For single item requests, use `.id(123).get()` to get a post by ID, which returns an object with `id`.

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

37 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/wp-api/node-wpapi ↗

packagewpapi ↗

homepagehttps://github.com/wp-api/node-wpapi ↗