WP-Node lets you work directly with your WordPress data — using modern TypeScript and Node.js. No PHP. No WordPress runtime. Just clean APIs for querying posts, users, terms, and metadata, backed by a powerful CLI.
Whether you're building automation scripts, developer tools, or headless apps, WP-Node gives you the flexibility of Node with the structure of WordPress.
🧩 When You Just Want to Work with WordPress Data
WordPress is one of the most widely used CMS platforms, but its all-in-one architecture often gets in the way for developers who just need to work with the data.
Out of the box, WordPress includes:
- A full PHP runtime
- Gutenberg block editor
- Admin UI and themes
While this is great for editors and site owners, it can feel heavy when you're focused purely on backend or integration work.
Common developer tasks that are harder than they need to be:
-
🧱 Running
wp-cli
to inspect dataRequires a full WordPress environment, PHP setup, and deep knowledge of WordPress internals — even for simple scripting tasks.
-
🪵 Navigating WordPress database by hand
You need to understand internal SQL schema and join behavior — with no typing or IDE support.
-
🌐 Building modern apps (e.g., Next.js, NestJS for REST API)
You’re stuck either querying MySQL directly or proxying through REST endpoints from WordPress.
🚀 Meet WP-Node
WP-Node is a TypeScript toolkit that lets you interact with your WordPress database directly — without booting up WordPress or writing a single line of PHP.
It gives you a clean, fully-typed interface for querying, inspecting, and manipulating WordPress data using modern Node.js workflows.
🧪 Example: Fetch a Post by ID
With WP-Node, querying WordPress content is straightforward:
import Application from "@rnaga/wp-node/application";
(async () => {
// Initialize WP-Node application
const wp = await Application.getContext();
// Fetch a post with ID 1
const posts = await wp.utils.query.posts((query) => {
query.where("ID", 1);
});
console.log(posts);
process.exit(0);
})();
No WordPress bootstrap, no wp-load.php — just clean, TypeScript-native access to your content.
🔧 Key features:
-
Query core tables like
posts
,users
,terms
,comments
, andmeta
- Typed utility classes for common patterns like post & meta access, term relationships
- CLI-first mindset comes with built-in CLI commands and makes it easy to define your own custom scripts.
- No WordPress runtime required — Doesn’t depend on PHP, themes, plugins, or WordPress bootstrap. Just point it at your existing database.
- Modern architecture with decorators and dependency injection
- TypeScript + Knex.js + Zod for type-safe, validated, and fluent database access using a modern query builder.
🛠️ Use it for things like:
- Running cleanup scripts on postmeta
- Building internal admin tools
- Creating custom CLI commands (e.g. sync-users, seed-posts)
- Integrating with modern apps (Next.js, NestJS, etc.)
WP-Node focuses on what developers care about: structured data access, automation, and developer experience — without the bloat.
⚙️ Getting Started
WP-Node lets you build apps and scripts on top of WordPress data using only Node.js and TypeScript — no WordPress PHP runtime required. Follow these steps to get up and running.
1. Prerequisites
WP-Node requires a MySQL-compatible WordPress database. You can use your existing WordPress setup, or spin up a new one using Docker:
docker network create wpnet && \
docker run -d --name wpdb --network wpnet -p 33306:3306 \
-e MYSQL_ROOT_PASSWORD=example \
-e MYSQL_DATABASE=wordpress \
-e MYSQL_USER=wp \
-e MYSQL_PASSWORD=wp \
mariadb && \
docker run -d --name wp --network wpnet -p 8080:80 \
-e WORDPRESS_DB_HOST=wpdb:3306 \
-e WORDPRESS_DB_USER=wp \
-e WORDPRESS_DB_PASSWORD=wp \
-e WORDPRESS_DB_NAME=wordpress \
wordpress
Then visit http://localhost:8080 to complete WordPress setup.
2. Initialize WP‑Node Project
mkdir wp-node
cd wp-node
npx @rnaga/wp-node-cli -- init
Follow the prompts to enter your database settings.
✔ Enter your database hostname: · localhost
✔ Enter your database port: · 33306
✔ Enter your database username: · wp
✔ Enter your database password: · **
✔ Enter your database name: · wordpress
✔ Is it a multi-site? · No
✔ Enter your static assets path: · public
Project Structure
After initialization, your project will look like this:
./
├── _wp
│ ├── config
│ │ ├── index.d.ts
│ │ └── wp.json
│ └── settings.ts
├── .env
├── index.ts
├── package-lock.json
├── package.json
└── tsconfig.json
Key files
-
_wp/config/wp.json
: Holds configuration for WP-Node such as public path and multisite info. This file is imported by settings.ts. -
_wp/settings.ts
: Initializes the WP-Node Context, including config, database access and hooks. -
index.ts
: The main entry point for your WP-Node app. A basic sample is provided. -
.env
: Stores sensitive environment variables, including your database credentials and other configuration values required at runtime.
3. Run the App
Once the config is initialized, run the app using:
mvn use 22
npx ts-node ./index.ts
If everything is working correctly, you’ll see SQL output like:
select * from `wp_posts` as `posts_5` where `posts_5`.`ID` = 1
[
{
ID: 1,
post_author: 1,
post_title: 'Hello world!',
...
}
]
6. Use the CLI (Alternative)
You can also use the built-in CLI to query data without writing code:
npx @rnaga/wp-node-cli -- post get 1 -Z table -F ID,post_title,post_type
┌────────────┬────────────────┐
│ (index) │ Values │
├────────────┼────────────────┤
│ ID │ 1 │
│ post_title │ 'Hello world!' │
│ post_type │ 'post' │
└────────────┴────────────────┘
Run npx @rnaga/wp-node-cli -- -h
to discover all available commands
npx @rnaga/wp-node-cli -- -h
Usage: <command> <subcommand> [options]
Commands:
blog Blog commands
comment Comment commands
config Generate WP config files
init Initialize WP with Node. (Generate wp.json and install dependencies)
install Initialize a new blog and create a user
meta Meta commands (post, comment, blog, term, user, site)
option Options commands
post Post commands
repl Start a REPL
role Role commands
site Site commands
term Term commands
user User commands
⭐️ Conclusion
WP-Node gives developers a modern, TypeScript-first way to interact with WordPress data — no PHP, no themes, and no plugin overhead. Whether you're building a script, a custom CLI, or a backend service, WP-Node makes it fast and developer-friendly.
If you found this project useful, please consider giving it a ⭐️ on GitHub:
👉 GitHub: https://github.com/rnaga/wp-node
👉 Documentation https://rnaga.github.io/wp-node/docs/intro
Your support helps others discover the project and keeps the development going!
Top comments (0)