👉 **[View Full Documentation at rnaga.github.io/wp-node →](https://rnaga.github.io/wp-node/)**
npm install @rnaga/wp-node👉 View Full Documentation at rnaga.github.io/wp-node →
WP-Node is a Node.js project written in TypeScript that mirrors the WordPress database schema and functionality. It enables developers to build scalable, modern backends on top of existing WordPress data.
Key benefits include:
- No need to run WordPress PHP
- Type-safe interaction with WordPress tables (posts, users, terms, comments, etc.)
- Utility classes for querying posts, terms, users, comments, and metadata
- Supports both Single Site and Multi Site WordPress setups
- CLI tools to seed databases and run custom commands
- Clean architecture with Dependency Injection and decorators
Here's an example of how to initialize WP-Node app and access WordPress post:
``typescript
import Application from "@rnaga/wp-node/application";
(async () => {
// Initialize WP-Node application
const wp = await Application.getContext();
// Fetch a post with ID 1
const post = await wp.utils.query.posts((query) => {
query.where("ID", 1);
});
process.exit(0);
})();
`
- TypeScript-first: Fully typed interfaces and schema validation using Zod
- Knex.js Integration: Query builder with SQL injection prevention and fluent chaining
- Dependency Injection: Built-in decorator-based system for injecting services like PostUtil, TermUtil, and MetaUtil, enabling clean separation of concerns and easier testingdo_action
- Hooks API: Inspired by WordPress hooks (, apply_filters), and supports implementation as async-compatible functions
WP-Node is ideal for scenarios where you need direct access to WordPress database without relying on the full WordPress stack. Example use cases include:
- Running background jobs or cron tasks that update WordPress records — without needing a full WordPress installation
- Building a lightweight REST API using Node.js and TypeScript that interacts with WordPress data
- Debugging or inspecting database records from a modern TypeScript environment
- Creating a web app (e.g., using Next.js) that needs to pull or push data from a WordPress database, without relying on PHP codebase
- Node.js >=22.0.0
- MySQL or MariaDB
- nvm: Make sure you have command installed on your local machine.
- Optional: Docker for local WordPress database setup
To spin up a sample environment with WordPress and database in Docker:
`sh`
docker network inspect wpnet >/dev/null 2>&1 || 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
Visit http://localhost:8080 in your browser to complete the WordPress setup.
To get started, create a new folder for your project. This folder will serve as the root directory for your WP-Node application.
`sh`
mkdir wp-node
cd wp-node
Then, run the command to initialize the project and follow the prompts:
`sh`
npx @rnaga/wp-node-cli -- init
`sh`
✔ 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
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.
Once the config is initialized, run the app using:
`sh`
mvn use 22
npx ts-node ./index.ts
If everything is working correctly, you’ll see SQL output like:
`shwp_posts
select * from as posts_5 where posts_5.ID = 1`
[
{
ID: 1,
post_author: 1,
post_title: 'Hello world!',
...
}
]
WP-Node CLI provides a convenient way to interact with WordPress data without writing any code.
To query a post (e.g. ID = 1), run:
`sh
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' │
└────────────┴────────────────┘
`
To view all available CLI commands, run:
`
npx @rnaga/wp-node-cli -- -h
output:
`sh
Usage:
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
`
Example:
`ts`
@command("page", { description: "Page commands" })
export class PageCli extends Cli {
@subcommand("list", { description: "List pages" })
async list() {
const context = await Application.getContext();
const posts = await context.postUtil.findByType("page");
console.log(posts);
}
}
WP-Node uses a custom @component() decorator to support DI scopes:
- Singleton: One instance for entire app
- Context: One instance per context (e.g. HTTP request)
- Transient: New instance every time
`ts`
@component({ scope: Scope.Transient })
export class Post {
constructor(
public meta: Meta,
private logger: Logger,
private queryUtil: QueryUtil,
...
) {}
}
- Filter: Modify data in chainable handlers (similar to apply_filters)do_action` equivalent)
- Action: Fire off side effects (
WP-Node Core is designed specifically to interact with the WordPress database. It does not support traditional WordPress features such as:
- Themes and appearance settings, including updating styling
- WordPress Template rendering or theming APIs
- WordPress plugins
Its scope is intentionally limited to providing a type-safe, programmatic interface to WordPress data — not replicating the full behavior of the WordPress runtime.
Feel free to fork, open issues, or suggest improvements. This project is in active development.
---
MIT License.