Skip to main content

Introduction

Welcome to WP-Node - a modern TypeScript WordPress-compatible Node.js project.

What is WP-Node?​

WP-Node is a Node.js project written entirely in TypeScript that's compatible with WordPress. It provides a modern, type-safe way to interact with WordPress database tables and perform operations that WordPress core typically handles, but with the power and flexibility of Node.js and TypeScript.

What you'll need​

  • Node.js version 22.0 or above:
    • When installing Node.js, you are recommended to check all checkboxes related to dependencies.

Key Technologies​

Knex.js for Database Operations​

To keep things simple and avoid the complexity of raw MySQL queries, WP-Node uses Knex.js as its query builder. Knex provides several important benefits:

  • SQL Injection Protection: Knex automatically escapes and sanitizes query parameters, protecting against SQL injection attacks
  • Clean Query Building: Construct complex queries using a fluent, chainable API that's more readable than raw SQL
  • Transaction Support: Built-in support for database transactions to ensure data consistency

Zod for Data Validation​

The project uses Zod as its data validation library, offering several advantages:

  • TypeScript-First: Zod schemas automatically generate TypeScript types, ensuring your data validation and type definitions stay in sync
  • Runtime Safety: Validates data at runtime, catching invalid data before it reaches your business logic
  • Composable Schemas: Build complex validation schemas by combining simpler ones
  • Detailed Error Messages: Provides clear, actionable error messages when validation fails
  • Zero Dependencies: Lightweight library with no external dependencies

Minimal Dependencies Philosophy​

Other than Knex and Zod, WP-Node (core) intentionally keeps npm dependencies to a minimum. This approach:

  • Reduces Security Risk: Fewer dependencies mean fewer potential security vulnerabilities
  • Minimizes Bugs: Less external code reduces the chance of encountering third-party bugs
  • Simplifies Maintenance: Easier to keep dependencies up-to-date with fewer packages to manage

Limitations​

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.

Use Cases​

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

💡 Examples: For practical implementations of these use cases, explore the example projects in the repository.

Getting Started​

Ready to start using WP-Node? Check out the tutorial sections to learn how to set up your first WP-Node project and start interacting with WordPress data using modern TypeScript patterns.