Download the PHP package dark-kitt/wordpress-theme-vue without Composer

WordPress - Vue 3 / TypeScript 5 / Webpack 5

Project: Part 1, Part 2, Part 3

Introduction

This is an example Vue/TypeScript project bundled with Webpack, based on Part 1 and Part 2 of the WordPress Boilerplate, which can be used to create a custom WordPress theme.

You can work with the WordPress backend system in two different ways. The first way would be to separate both systems from each other so that you have a headless backend with an unattached front-end system. The second way would be to use both systems together for an "Islands Architecture" so that you are still able to use the PHP files from WordPress and hydrate dynamic Vue components inside of your DOM structure.

In my case, I used the second option and configured all the necessary stuff to make it usable for the "Islands Architecture", but it's easy to modify the project to handle the first way and separate both systems. Just install the HtmlWebpackPlugin, and a template engine like Handlebars to render the output. Afterward, it's just necessary to modify the Webpack and the Apache configuration.

Requirements

• Yarn: ^1.* || npm: 10.*

Installation

If you have a specific path to your /themes directory, please add the following lines to your composer.json file.

common composer cmds

Quick start

Install all necessary node modules.

For development mode.

For production mode.

As described before I create only the output for the "Islands Architecture", which means that you only see the JS, the CSS, and the necessary assets files inside of the (/www) output directory. So, the output must be included with PHP, e.g. by WordPress with wp_enqueue_script.

Getting started!

I guess the best way to understand the project is to create an example project together. The following instructions are based on a macOS system, but it could be possible, with some troubleshooting, that it will also work on Windows.

As always, let's create a folder and change the directory.

Set up the environment

Keep it simple as it is. Go to Part 1 of the WordPress Boilerplate download the project as ZIP, and open and copy-paste the composer.json file in your project root directory (/example). If you have a GitHub account and want to fetch the file by curl you can use the following command.

composer.json

Or save your private access token in a curl header file, e.g. ~/.curl/github, and include your specific header in your command.

Composer

Let's continue. If you have an ACF Pro key, please add it manually inside of the composer.json file [25](replace <<ACF_KEY>> with your key) and call composer update. Otherwise, we will remove ACF Pro and get forward. Let's keep it quickly and remove ACF Pro. To do so, call the following command.

Now, your folder/file structure should be like this.

Docker

In the next step, we need a local server. Let's work with Docker. If you don't have Docker you can download it here. We need only 3 files to set up the environment for Docker. Please, copy and paste the following snippets and create each file in the root directory (/example) of our new project.

compose.yml

Dockerfile

vhosts.conf

As you can see we deny the access for the ./web/app/themes/example/config directory in the vhosts.conf file. This is important because we need a save area to configure our front-end project. But there is also another way to do it. If you don't prefer to extend your Apache vhosts.conf file, you can also add a .htaccess file that includes Deny from all inside of the ./web/app/themes/example/config directory.

Afterward, your folder/file structure should look like this.

⚠️ Necessary local configuration to resolve the custom domain.

Next, we need to add our local domain to our local hosts file to resolve the custom local domain in our browser. For this, you need to add the localhost IP (127.0.0.1) to your /etc/hosts file on your machine.

Open a new terminal window and call the following command.

Enter your machine password and open the hosts file. Add at the end of the file the following line.

MySQL

Before we can go ahead and configure the backend system, it is necessary to set the permissions for our database user. Open/Start your (downloaded) Docker application and call docker compose up in a terminal window.

After all necessary packages are installed and the containers are running, open another terminal window and connect to the MySQL container.

Log in as root user. The password is defined in the compose.yml file, in our case it is ro_password.

Now, set the privileges for the db_user.

Flush the privileges.

Logout.

Cancel the connection to the MySQL container by pressing ctrl + P and ctrl + Q. Close the new terminal window so that we have only one window again, where the containers are running.

Configure WordPress

Finally, we can start to configure the WordPress backend system and dive into the interesting part to start working with our new custom WordPress theme. But before we start and try to access the api.example.kitt domain to open the backend system, we will go one step back. Stop the running containers with ctrl + C inside of our terminal window.

After the containers are stopped we need to set up the .env and the ./web/.htaccess file. Please update the following values.

.env

If you already have an email account that is usable for PHPMailer you can also set up the following values.

.htaccess

Now, it is necessary to rebuild the containers. Call the following command.

Afterward, we will run the new containers.

⚠️ Keep in mind, that every time you edit your environment, you need to rebuild your containers. ⚠️

Let's try to access our configured backend system. Open your browser and enter the following domain.

You should see a mask from WordPress where you have to enter the first values of your custom backend system. We will enter the following data.

Press the button Install WordPress! And login as admin. Before we start to configure the theme, we need to activate our new custom theme, you'll find it under Appearance. Additionally, we need to activate all plugins, too.

The Front-End

Let's dive into the front-end directory ./web/app/themes/example and configure the last part for WordPress. I'll take some parts of the snippets from the example.functions.php file to handle some configurations. Please add the following lines below inside of the functions.php file.

functions.php / theme configuration

REST-API

In this example project we want to use the REST API to get some data from the backend system that's why we have also to configure it. Please add the following snippet for it.

functions.php / REST-API configuration

As you can see, I set the Access-Control-Allow-Origin header to WP_HOME, this means that requests are only allowed from example.kitt. This is important because we don't want, that other websites can access the data. The namespace is set to example by explode('.', parse_url(WP_HOME)['host'])[0], so if you want to make requests to the REST-API you need to call api.example.com/wp-json/example/endpoint.

After we added the REST-API configuration snippet and reloaded the backend system, we need to create a REST-API user. Go to Users and create a user with the credentials of our .env file. In this case, it is important to set the Username === REST_USER, the Password === admin, and the Role === REST API User.

JWT Token Handling

Obviously, we need a token for each request. To retrieve a token we will add now a small snippet to the functions.php file. Let's extend the instance and add a new endpoint and a callback function to handle the request.

functions.php / adding REST-API endpoint

What have we done? We added a new endpoint to $kitt_instance->rest_routes which is callable with token (api.example.com/wp-json/example/token). The method is set to GET by \WP_REST_Server::READABLE. Every endpoint needs a permission callback. With the WordPress Theme Configuration plugin, it is only possible to set the permission to rest_api_user (protected) or like in our case __return_true (public). Afterward, it is necessary to handle the request by a callback function, which is defined underneath the $kitt_instance->rest_routes configuration. You can also add some arguments in the last array, but in our case, it is not necessary.

PHPMailer

If you have entered email configurations in the .env file before, you can add the following snippet to configure PHPMailer, otherwise, you can ignore this step. Just add the snippet below and test the endpoint by calling a request to api.example.com/wp-json/example/email. Afterward, you should receive an email to your account by yourself.

functions.php / PHPMailer configuration

Add the output

As described before this example project used the second option to handle the "Islands Architecture". So we need to add the output files to the DOM by WordPress. Let's add another snippet. At this time, we will open and edit the index.php file.

index.php / enqueue scripts and styles

As you can see, I create a manifest.json file inside of the output directory (/www) by Webpack and read and add all scripts and styles that are listed in the JSON file. It is required to add an ID for each file, so, I remove the hash to have a readable ID name. I also create an exception for the main.bundle.js file, that this file is always included at the end of the DOM.

The last point is to request a token and hand over it to the front-end system. For this, I created just a global constant.

So, in the end, my index.php file is looking like this.

index.php

.env

The last step is to create the .env file inside of the /configs theme directory. Please copy and paste the .example.env file inside of the ./web/app/themes/example/configs directory.

Ok, that was a lot of instructions, but now you are done! Just install all necessary packages with yarn and start the front-end system by calling yarn dev. Afterward, all the necessary output should be created inside of the /www directory to make our example project visible at example.kitt.

Now it is up to you. Be creative and start coding. Just place your scripts and styles inside of the /src directory and create your own custom front-end system.

Happy coding!

License