Frontend Integration

Pionia is a REST framework that is entirely meant for the backend. It has no frontend capabilities.

However, Pionia has added support to scaffold one of the seven vite-supported frameworks. This is to help you get started with your frontend quickly.

Supported Frameworks#

To get the full list of supported frameworks, you can run the following command:

php pionia front:sc

The following are the supported frameworks:

1. [0] Vue
2. [1] React
3. [2] Z-js
4. [3] Qwik
5. [4] Lit
6. [5] Preact
7. [6] Svelte
8. [7] Solid

Scaffold Frontend#

To scaffold the frontend, you can run the following command:

php pionia front:sc 

If you pass -y flag, the command will assume the defaults and scaffold the frontend without asking for any input. This will scaffold Vuejs in the frontend directory of your project using npm as the package manager.

Scaffold Specific Framework#

Just select the option of the framework you want to scaffold. For example, to scaffold React, you can run the following command:

php pionia front:sc 

Then select the option for React which is 1 as illustrated in the image above.

Frontend Directory/folder.#

The frontend directory is where all the frontend code is stored. It is created by the front:sc command. The directory is created in the root of your project.

In the interactive shell of the front:sc command, you can specify the name of the directory you want to create. If you do not specify a name, the default name is frontend.

In the shell below, enter no to provide your custom frontend directory.

Example below will scaffold the frontend in the pages folder

Frontend Package Manager#

In the interactive shell of the front:sc command, you can specify the package manager you want to use. If you do not specify a package manager, the default package manager is npm.

The following are the available options:-

Scaffolding TS or JS#

Except z-js, for the other frameworks, you can choose between scaffolding the js or the ts version of the framework.

This will always default to js.

Other Frontend Operations.#

Pionia does not just stop at scaffolding the frontend. It also, gives you other features that you can do with your frontend.

Environment Setup#

Pionia sets up both the backend and the frontend environments so that they start communicating. In the backend, the following will be added in your settings.ini upon successful scaffolding of the frontend.

[frontend]
frontend_root_folder=pages
build_command=yarn build 
frontend_build_folder=dist
frontend_framework=Vue
package_manager=yarn

The frontend tells Pionia how to deal with the frontend that was just created.

1. frontend_root_folder is the root folder of the frontend. This is where the frontend code is stored.
2. build_command is the command that will be run to build the frontend. This command is run as is against your frontend, so feel okay to tweak it the way you see fit.
3. frontend_build_folder is the folder where the frontend will be built. Usually if this is not in dist, it will absolutely be in the build folder. When Pionia is going to serve your frontend, this is the folder it will read and ship to your backend.
4. frontend_framework is the framework that was used to scaffold the frontend.
5. package_manager is the package manager that was used to scaffold the frontend. This will be the package manager used even to build your frontend.

In the frontend directory created, two files were created. These might likely be in your src folder. Pionia adds the VITE_API_URL to your .env file. This is the url that your frontend will use to communicate with the backend.

In development mode, this will be http://localhost:8000/api/. In production mode, this will be relative to your application domain since the frontend and backend will be served together.

1. .env.development - This is the file that will be used to set the environment variables for your frontend in development mode.

# .env.development
VITE_API_URL=http://localhost:8000/api/ 

2. .env.production - This is the file that will be used to set the environment variables for your frontend in production mode.

# .env.production
VITE_API_URL=/api/

Build the frontend.#

In development, the frontend and backend run in isolation. This implies that both the frontend and backend servers must be started and run in two terminals. However, when you are done with your frontend, Pionia kicks in again.

Building the frontend and serving it with your backend.

Before proceeding, running http://localhost:8000/ if your backend is still running on the default port, you will see the default Pionia page.

To build the frontend, you can run the following command:

php pionia front:build

This command will build your frontend in your frontend directory, into your build folder, then will ship them to your backend for serving.

On successful running of the above command, http://localhost:8000/ should render your frontend instead.

Before build#

http://localhost:8000/

After build#

http://localhost:8000/

Cleaning up the build files.#

When you serve your frontend with your backend, Pionia drops all the necessary files in your root directory for serving. This can be messy and hard to truck.

Future versions might handle this in the public folder. But for now, Pionia has a way of trucking these files and cleaning them our if you nolonger want them.

Run the following command to clean the frontend served with backend. This is ensured by the manifest.json file that was created with the build command.

php pionia front:build:clean

On success, your root directory will be clean and only containing php files.

Dropping the entire frontend!#

In cases where maybe you wanted to scaffold Vuejs and instead scaffolded React, you can run this command to drop your entire frontend.

php pionia front:drop

It is advisable to run this command after running the front:build:clean so that any files that were created by the build command are also cleaned up.

With this in, Pionia now can handle both the backend and help you with your backend while maintaining each of them in isolation.

Need Help?#

For any technicalities that you may interface in this section, please refer to the vite docs for the specific framework you are using or the official documentation of the framework you’re trying to scaffold.