Wondering what’s next for npm?Check out our public roadmap! »

    wp-types
    TypeScript icon, indicating that this package has built-in type declarations

    2.9.0 • Public • Published

    NPM

    WordPress TypeScript Definitions

    This package provides well-documented TypeScript definitions that describe the shape of:

    • WordPress PHP objects such as WP_Post, WP_Term, and WP_User
    • WordPress REST API responses such as from /wp/v2/posts and /wp/v2/users
    • Various property types and allowed values of both

    The definitions were last updated for WordPress 4.7.

    What's included?

    Interfaces for PHP objects

    • WP_Post
    • WP_Term
    • WP_User
    • WP_Comment
    • WP_Error
    • WP_Query
    • WP_Block
    • WP_Block_Type
    • WP_Site
    • WP_Locale
    • WP_Taxonomy
    • WP_Post_Type
    • WP_Role
    • WP_Network

    Interfaces for REST API response objects

    Route Schema
    /wp/v2/block-directory/search Todo
    /wp/v2/block-renderer/{name} Todo
    /wp/v2/block-types WP_REST_API_Block_Types
    /wp/v2/block-types/{name} WP_REST_API_Block_Type
    /wp/v2/blocks WP_REST_API_Blocks
    /wp/v2/blocks/{id} WP_REST_API_Block
    /wp/v2/blocks/{id}/autosaves Todo
    /wp/v2/blocks/{parent}/autosaves/{id} Todo
    /wp/v2/categories WP_REST_API_Categories
    /wp/v2/categories/{id} WP_REST_API_Category
    /wp/v2/comments WP_REST_API_Comments
    /wp/v2/comments/{id} WP_REST_API_Comment
    /wp/v2/media WP_REST_API_Attachments
    /wp/v2/media/{id} WP_REST_API_Attachment
    /wp/v2/media/{id}/edit Todo
    /wp/v2/media/{id}/post-process Todo
    /wp/v2/pages WP_REST_API_Posts
    /wp/v2/pages/{id} WP_REST_API_Post
    /wp/v2/pages/{id}/autosaves Todo
    /wp/v2/pages/{parent}/autosaves/{id} Todo
    /wp/v2/pages/{parent}/revisions WP_REST_API_Revisions
    /wp/v2/pages/{parent}/revisions/{id} WP_REST_API_Revision
    /wp/v2/plugins Todo
    /wp/v2/plugins/{plugin} Todo
    /wp/v2/posts WP_REST_API_Posts
    /wp/v2/posts/{id} WP_REST_API_Post
    /wp/v2/posts/{id}/autosaves Todo
    /wp/v2/posts/{parent}/autosaves/{id} Todo
    /wp/v2/posts/{parent}/revisions WP_REST_API_Revisions
    /wp/v2/posts/{parent}/revisions/{id} WP_REST_API_Revision
    /wp/v2/search WP_REST_API_Search_Results
    /wp/v2/settings Todo
    /wp/v2/statuses WP_REST_API_Statuses
    /wp/v2/statuses/{status} WP_REST_API_Status
    /wp/v2/tags WP_REST_API_Tags
    /wp/v2/tags/{id} WP_REST_API_Tag
    /wp/v2/taxonomies WP_REST_API_Taxonomies
    /wp/v2/taxonomies/{taxonomy} WP_REST_API_Taxonomy
    /wp/v2/themes Todo
    /wp/v2/themes/{stylesheet} Todo
    /wp/v2/types WP_REST_API_Types
    /wp/v2/types/{type} WP_REST_API_Type
    /wp/v2/users WP_REST_API_Users
    /wp/v2/users/({id}|me) WP_REST_API_User
    /wp/v2/users/({id}|me)/application-passwords Todo
    /wp/v2/users/({id}|me)/application-passwords/{uuid} Todo
    /wp/v2/users/({id}|me)/application-passwords/introspect Todo
    Any enveloped REST API response WP_REST_API_Envelope<T>
    Any REST API error WP_REST_API_Error

    Properties

    Interfaces are used for the structure of several properties:

    • WP_Error_Data
    • WP_Error_Messages
    • WP_Post_Type_Caps
    • WP_Post_Type_Labels
    • WP_Post_Type_Rewrite
    • WP_Taxonomy_Caps
    • WP_Taxonomy_Labels
    • WP_Taxonomy_Rewrite
    • WP_User_Cap_Name
    • WP_User_Caps
    • WP_User_Data

    Enums

    String enums are used for values of several properties:

    • WP_Comment_Status_Name
    • WP_Comment_Type_Name
    • WP_Post_Comment_Status_Name
    • WP_Post_Format_Name
    • WP_Post_Status_Name
    • WP_Post_Type_Name
    • WP_Taxonomy_Name
    • WP_User_Role_Name
    • WP_HTTP_Status_Code

    Installation

    npm install wp-types --save-dev

    Usage

    Usage with objects from PHP represented as JSON:

    import type { WP_Post } from 'wp-types';
    
    function get_title( post: WP_Post ): string {
    	return post.post_title;
    }

    Usage with the REST API, for example when using apiFetch():

    import type {
    	WP_REST_API_Posts,
    	WP_REST_API_Users,
    	WP_REST_API_Attachments,
    	WP_REST_API_Tags,
    	WP_REST_API_Envelope,
    	WP_REST_API_Error,
    } from 'wp-types';
    
    // Posts, Pages, and custom post types:
    const api: Promise<WP_REST_API_Posts> = wp.apiFetch( {
    	path: '/wp/v2/posts/',
    } );
    
    // Users:
    const api: Promise<WP_REST_API_Users> = wp.apiFetch( {
    	path: '/wp/v2/users/',
    } );
    
    // Media attachments:
    const api: Promise<WP_REST_API_Attachments> = wp.apiFetch( {
    	path: '/wp/v2/media/',
    } );
    
    // Enveloped responses (with `?_envelope`):
    const api: Promise<WP_REST_API_Envelope<WP_REST_API_Tags>> = wp.apiFetch( {
    	path: '/wp/v2/tags/?_envelope',
    } );
    
    // Errors from any of the above:
    api.catch( ( error: WP_REST_API_Error ) => {
    	alert( error.message );
    } );

    FAQs

    When do these definitions apply?

    The PHP object definitions apply whenever a supported PHP object is represented as JSON. How you do that depends on your application, but here is an example:

    printf(
    	'let wpPost = %s;',
    	wp_json_encode( get_post() )
    );

    The REST API object definitions apply to the response to a REST API request, for example when using apiFetch().

    The definitions also apply outside of the browser, for example if you're saving data as JSON and reading it in a Node application.

    How do I know these definitions are valid?

    They're generated directly from the wp-json-schemas package, which is itself tested using output from WordPress core.

    If you'd like to contribute to these definitions, please contribute upstream to the wp-json-schemas package. Thanks!

    Can I use the enums as values in my code?

    Yes, but:

    • You might need preserveConstEnums enabled in your TypeScript config
    • You should import enums as you would a regular module, not as a type
    • You cannot iterate enums (this is a TypeScript restriction)

    Example:

    import { WP_Post_Type_Name } from 'wp-types';
    
    console.log( WP_Post_Type_Name.auto_draft );

    License

    MIT

    Install

    npm i wp-types

    DownloadsWeekly Downloads

    498

    Version

    2.9.0

    License

    MIT

    Unpacked Size

    71.8 kB

    Total Files

    4

    Last publish

    Collaborators

    • avatar