WordPress in TypeScript — Build Fast Without PHP

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.

👉 View on GitHub

🧩 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 data

  Requires 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, and meta
• 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!

Comments

[Karl Kubelet]

Nice one.

The biggest problem I see here is object cache. Anything you do to the WordPress database directly will by-pass a persistent object cache backend, such as Redis or Memcache, and I don't even see a way to flush the cache here since you're not working in a WordPress context at all. This will inevitably lead to stale cache unfortunately, causing all kinds of unexpected problems.

For this very same reason we strongly discourage making any changes via phpMyAdmin or the MySQL shell, unless you're prepared to wp cache flush right after.

[rnaga]

Thanks a lot for the thoughtful feedback! The package is still experimental, and I’ll definitely keep caching considerations in mind for future updates.

Some of the use cases I’m aiming for involve building new apps (for example with Next.js) without relying on WordPress PHP layer, so the built-in WordPress object cache isn’t directly in play here.

One example is WP-Next, which I built using this package — a CMS that interacts directly with WordPress database.

That said, you’re right that caching is a broad challenge—whether it’s WordPress object caching, CDN layers, or other strategies, consistency is always tricky and there’s no one-size-fits-all solution. It’s definitely something worth exploring more as the project evolves.