README

An opinionated boilerplate for web applications using PHP/Mako on the backend and Vue.js on the frontend.

This is my personal starter template for building web applications with Mako and Vue.js. It aims to provide a solid foundation with common features and best practices, allowing developers to focus on building their applications rather than setting up the initial structure. It's been a common starting point for my own projects, so I'm sharing it in hopes that it can be useful to others as well.

Features & Stack

Mako 12 PHP Framework
PHP 8.5+
Environment-specific configuration via hierarchical pattern with Mako's built-in config system
Persistent storage tailored to MySQL/MariaDB databases
Database migrations via built-in Mako migration system, including separate user for running migrations
Policy-driven, database-backed request rate limiting with IP, identity, actor, and path buckets
Content Security Policy with nonce support and standard security response headers
mako-template-pp for enhanced templating capabilities
mako-mailer for email sending and templating
Inertia.js for seamless server-driven SPA experience
inertia-mako adapter
Vue.js 3 with Composition API and Single File Components
Vite for fast development and build process
Vue DevTools for easier frontend debugging
Bootstrap for responsive UI
Bootstrap Icons for iconography
Bootswatch for easy theming
Common pre-built Vue components and layouts, including standard/floating form labels and an opt-in minimal layout
Minimal banner to indicate non-production environments
Simple authentication scaffolding
Attribute-based cron jobs with locking and validation
MJML email sources with reusable headers/footers and compiled Mako templates
Opt-in soft-delete support for ORM models
IDE helpers for VSCode
Dockerization for consistent development and deployment
- Separation of dev and prod environments by utilizing compose.override.yml
- Separate services for PHP, MariaDB, Node/Vite, Mailpit, and Adminer
- Isolated test profile with a throwaway MariaDB and backend test container
- File ownership and permissions handling for seamless host-container interaction*
- Pre-configured for Xdebug with VSCode integration*
- Caddy for HTTPS in local development*
- mkcert for local HTTPS certificate creation*
- Mailpit for local email testing*
- Adminer for database management*
- Optional Tailscale HTTPS routing for testing from other devices*
- Host networking allows local domain name usage*
- Allows concurrent projects to run locally without the need for port separation or reverse proxies*
PHPUnit for backend testing
Vitest, jsdom, and Vue Test Utils for frontend testing

* Local development only.

Development Prerequisites

Docker and Docker Compose installed on your host machine
Docker Rootless mode configured
CAP_NET_BIND_SERVICE set on rootlesskit to allow binding to privileged ports
mkcert installed on your host machine for local HTTPS

How to Use It

To avoid any potential host incompatibilities, the recommended way to set up this boilerplate is to use the setup.sh script, which will use ephemeral Docker containers to run the necessary setup commands for you, and coordinate mkcert and /etc/hosts updates for local HTTPS and domain name usage.

setup.sh supports two workflows:

Create a brand-new project from this boilerplate (./setup.sh <project-name>)

curl -sLo /tmp/setup.sh https://raw.githubusercontent.com/inventor96/mako-vue/refs/heads/main/setup.sh && bash /tmp/setup.sh your-project-name

Initialize an already-cloned repository (./setup.sh from the repo root)
```
cd your-project-name
./setup.sh
```

If you wish, and if your host meets all dependencies, you can also use composer directly on your host:

# creating a new project from the boilerplate
composer create-project inventor96/mako-vue your-project-name

# setting up an already-cloned repository
composer install
php app/reactor post-create-project

Common commands

# Apply reviewed migrations using the dedicated migration configuration
composer migrate

# Validate and run scheduled jobs
composer cron:validate
composer cron:run

# Run PHP tests; integration tests should use the isolated Docker profile
composer test:unit
docker compose --profile test run --rm backend-tests

# Run frontend tests and build frontend assets plus email templates
npm test
npm run build:all
npm run mjml:watch

For production-like local testing, run:

docker compose -f compose.yml -f compose.localprod.yml up -d

Tailscale routing is disabled by default. Configure TS_DOMAIN, TS_AUTHKEY, TS_HOST, and TS_CERT_DOMAIN, then start it explicitly with:

docker compose --profile tailscale up

The post-create-project script (which is also automatically run by the composer create-project command) will attempt to run the mkcert command, but you will be responsible for editing your /etc/hosts file (a one-liner command will be provided).

For additional details, please see the wiki for detailed instructions on setting up and using this boilerplate.

Limitations

vite.config.js is setup for HTTPS via Caddy in Docker. If you are not using Docker, you may need to adjust the Vite server settings for HTTPS or switch to HTTP.
Local development environment is optimized for Linux hosts. Other OSes may require additional configuration.
Vue DevTools in Docker cannot open files in an IDE running on the host.

inventor96 / mako-vue

Package info

Security

Statistics