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 PHP Framework
• 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
• mako-template-pp for enhanced templating capabilities
• mako-mailer for email sending and templating
• Inertia.js for seamless server-driven SPA experience
• intertia-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 components and layout for Vue.js
• Minimal banner to indicate non-production environments
• Simple authentication scaffolding
• 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, and Node/Vite
  • 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*
  • 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:

1. 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

2. 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

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.