⚠️⚠️⚠️ This is a beta version plugin

⚠️⚠️⚠️ Don't use it in production mode

demo link ( coming soon )

• Before getting start - Front-end - Back-end
• Install
• Configuration
• Build
• Custom Hooks ⛏️⛏️⛏️
  • useOne
    • - Properties:
    • - Return:
    • - Example:
  • useMany
    • - Properties:
    • - Return:
    • - Example:
• How to use Front-End Router with WordPress
  • Problems
  • Reason
  • Solution
• Reference

Tech stacks (knowledge you need to have)

1. Vite - build tool
2. React v18
3. TypeScript - compile project with type safe
4. Tailwind v3 - you can install any UI library, like Ant Design, MUI, Chakra...etc
5. SCSS
6. Zod - ⚡runtime⚡ type safe🔰
7. MSW - mock API data
8. React Query v4 - managing API status
9. React Router v6 - front-end router

1. usefulteam/jwt-auth - get JWT if a wordpress user is logged in

1. Clone this repository into /wp-content/plugins.

   cd {your-project}/wp-content/plugins

2. Install dependencies:

   npm run init npm run dev

3. Activate the plugin from WordPress admin /wp-admin.

4. Visit your site's homepage and see the rendered application on the footer 🚀

5. Click Count, Get Post Example, Get Users Example button to ensure the State and the WordPress API works

6. 🎉🎉🎉 Enjoy the dev 🎉🎉🎉

.env.development

VITE_BASE_URL='/' # the path this plugin be used at VITE_RENDER_ID='my-app' # by default, the footer will render a <div id="my-app"></div> container at footer # You can custom the render id VITE_API_URL='http://plugindev.local/wp-json' # ⭐ set your WordPress RESTFUL API url here # ⭐ {site_url}/wp-json VITE_API_TIMEOUT='30000'

npm run build

After you build the project will apply .env.production and enqueue the hashed assets in js/dist folder.

the files in js/dist is EXACT the files of your plugin, you can only upload the js/dist if you don't want to share the src source code

{ resource: string // WordPress RESTFUL API Endpoint like: posts, users, products id: number queryOptions?: { // please visit React Query for more detail staleTime?: number cacheTime?: number refetchOnWindowFocus?: boolean refetchOnMount?: boolean refetchOnReconnect?: boolean refetchInterval?: number retry?: boolean | number retryDelay?: number enabled?: boolean } }

WordPress Object

// get the post with id = 200 const post = useOne({ resource: 'posts', id: 200, }) // get the user with id = 1 const user = useOne({ resource: 'users', id: 1, })

{ resource: string // WordPress RESTFUL API Endpoint like: posts, users, products args?: Record<string, any> // please visit WordPress RESTFUL API Handbook for more detail queryOptions?: { // please visit React Query for more detail staleTime?: number cacheTime?: number refetchOnWindowFocus?: boolean refetchOnMount?: boolean refetchOnReconnect?: boolean refetchInterval?: number retry?: boolean | number retryDelay?: number enabled?: boolean } }

WordPress Object Array

// get all posts that author_id = 1 const posts = useMany({ resource: 'posts', args: { author: 1, }, })

Sometimes we need a MPA ( Multi Page Application ), not just SPA ( Single Page Application ).

1. WordPress use backend router
2. Our React plugin using frontend router

there would be a conflict.

You will get a ❌404 page if you press F5 to refresh to page at /get-posts

Because every time you press F5 to refresh the page, you will send a request to the server and the server will handle the request in WordPress's route, then it will found nothing.

That's why we got 404

But why don't we get 404 if we click the button from base url?

That's because frontend router uses window history API, it won't send request to server

All we need to do is

1. (BE) redirect any URL with {baseUrl}/any-path to {baseUrl} ( APP's root url )

2. (FE) save the url state in sessionStorage when user link to a page of your plugin

3. (FE) set the condition to restore the url state, so the we can navigate to the right page by front end router

   * BE means Back End * FE means Front End

We use React Router v6 for example

coming soon ⛏️⛏️⛏️

1. Inspired by Vite for WP
2. WordPress REST API Handbook