📦 wp-ts-react

wp-ts-react is a WordPress theme starter preconfigured with a Typescript + React frontend which allows developers to handle WordPress configuration and a React frontend development from one repository.

#		Table of Content
1	📣	Statement
2	👟	Getting Started
3	⚙️	Wordpress Backend Configuration
4	⚛️	React Frontend Templates
5	⚛️	React Core Components
7	⚛️	React Wordpress Data Hooks
6	🌐	Public API
8	🔌	Plugin Compatibility
9	🆘	Help, Issues and Contribution

Statement

🔪 Do you need a ready-to-go tool for small websites (such as one page and small portfolios) which needs to run on an old scrappy server of some super cheap hosting?

🔪 Are you willing to work with React but proper template integration with WordPress is a real pain?

🔪 Have you ever thought WordPress development is a hell of PHP templating, messy API, and does not fit your development workflow?

🔪 Have you ever noticed that SEO/Socials previews are a pain when dealing with Create React App frontend and headless WordPress?

👌 Well, this repository is something you might be interested in.

Getting Started

Setup

Method 1 [Suggested]: Using GitHub templates

You can easily clone this starter as a new repository in your GitHub account by using the green button on the top right of the GitHub Repository.

Method 2: Download a zip

You can easily download this starter as a .zip file using the Code dropdown on the top right of the GitHub Repository.

Method 3: Manually clone this repository

1. Clone this repository;

2. Delete the existing .git folder;

   git clone git@github.com:hund-studio/wp-ts-react.git
   mv wp-ts-react my-project
   cd my-project
   sudo rm -r .git

3. If needed and strongly recommended, git init a new repository.

   git init
   git remote add origin <remotegiturl>
   git add .
   git commit -m "Initial Commit"
   git push --force origin master

Develop

Before proceeding, you must install all required node_modules by running:

npm install

Scripts

There are three available modes that you can use depending on what you are working on:

• Watch mode to test your template on a local WordPress instance;
• Serve mode to develop your UI using a remote staging WordPress instance;
• Build mode to build your template for production upload.

Use npm run watch to start watching your files for changes and build, in real-time, a local version of your theme inside the /build folder. You can symlink (Mac users should do it using the ln -s command instead of alias) the wp-ts-react folder inside your local /wp-content/themes directory.

Use npm run serve to start a Node instance at localhost:3000 to develop the React frontend while fetching data from a remote wp-ts-react theme.

Use npm run build to build the production theme inside the /build folder, ready to be uploaded on your server.

Configuration

Detailed documentation about WordPress configuration can be found in this section.

To start there is one last thing to do: configure your WordPress instances. You can find all the basic configurations inside the /config folder inside your project root:

• api.json: contains the API configurations required for the theme to work. You will likely keep the default values but you can change them if your WordPress instance needs specific configuration (ae. you changed the default WordPress API endpoint for whatever reason);

• app.json: contains the HTML elements IDs used from the theme to exchange server-side rendered data with the React frontend. We suggest keeping the default values but you can change them if names are conflicting with other ids inside your project;

• hosts.json: contains the different target instances used from the scripts to build and compile your code:

  ⚠️ If you don't use a staging or local instance (strongly suggested by the way) you can set all three values to your production/local/staging instance.

  • local value is your local WordPress Instance which you would likely use to test your WordPress configuration and set up the theme backend configuration. This value is used to target your WordPress instance when in watch mode;
  • staging value is your remote development WordPress instance. This instance will be used in serve mode to fetch data through the API;
  • production value targets the production remote WordPress Instance and is used to build your production theme which will be uploaded to the production server.

What's next

• How to configure your WordPress instance: Create Custom Post Types, Taxonomies, Custom Templates, Custom API endpoints, Menus, and Options Pages directly from your theme to, almost, avoid the use of external plugins.

Plugin Compatibility

To unlock the full potential of WordPress we added built-in support for a few, optional, well-known plugins. Full compatibility with the entire WordPress plugin ecosystem is not guaranteed but is presumed.

Here you can find a list with built-in supported plugins with their doc.

• Advanced Custom Fields (and its Pro version): It can be used to implement additional Custom Fields on categories and post types. ACF fields will automatically be included in each page's data.
• Rank Math: with this plugin page SEO is automatically handled by wp-ts-react.

Help, Issues and Contribution

There is no direct support line available. To report bugs, request new features, or ask for help, please file a new Issue or visit our Discussions page. We will answer you as soon as possible.

	I need...	What to do?
🆘	...some help using this repository	Search/Start a new Discussion
👾	...to report a bug	Search/Create an Issue for Bug Report
🆕	...to request a new feature	Search/Create an Issue for Feature Request
📄	...help with documentation	Search/Start a new Discussion
👆	...to create a pull request	Read: Collaborating with pull requests

This tool is open to everybody's contribution, fork it, open a Pull Request, or start a Discussion to discuss improvements.