Frontend in MintHCM

Short Description

This guide shows you how to set up, run, build and deploy the Vue 3 frontend shipped under vue. We use Vite as our dev server and build tool.

Prerequisites

• Node.js v16.x or v21.x (per package.json “engines”)
• npm (comes with Node.js)
• Git (optional, for version control)
• A terminal on Linux

Initial Setup

Open a terminal and navigate into the Vue project:

cd <instance_directory>/vue

Install all dependencies:

npm install

Environment Variables

Create a .env file in vue (copy from the example) to configure runtime proxies or other settings:

# copy from .env.example and adjust
PROXY_URL=http://localhost:8080/minthcm

Vite will automatically load any VITE_* or plain entries from this file.

Development Mode

Run the Vite dev server with hot module replacement:

npm run dev

• By default it serves at http://localhost:5173
• Edits to .vue, .ts, .scss, etc. reload instantly
• You can change port with, for example, npm run dev -- --port 3000

Linting & Formatting

Check (and auto-fix) code style with ESLint & Prettier:

npm run lint

This invokes vue-cli-service lint against your .vue and .ts files.

Deploying into the PHP App

The project defines a convenient script to build and copy assets into the PHP root:

npm run build:repo

Under the hood it:

1. Runs npm run build
2. Removes assets
3. Copies vue/dist/* → <root folder>
4. Deletes the leftover index.html in the PHP root

After this, your compiled JS/CSS lives in assets.

If you build the frontend on installed application, copy index.html file cp vue/dist/index.html ./index.html

How index.php Integrates the Frontend

First, when the application is launched, it runs the index.php file. The file checks the requirements, for example, access to the .htaccess file. If everything is OK, the system copies the index.html file from the source into the root directory of the application. The PHP file is removed and the whole application is refreshed. The application is then run via index.html and the compiled frontend.

Troubleshooting

Dependencies broken

rm -rf node_modules package-lock.json
npm install

Port conflicts:

npm run dev -- --port 3001

Environment variables not loaded?

• Ensure .env lives in vue
• Prefix custom keys with VITE_ if you need them in client code