Welcome page and branding

Who this is for#

You just created pionia-shop and opened http://127.0.0.1:8000/ — you want the page to say Pionia Shop (or your product name), not a generic placeholder, and you need to know when the framework welcome page goes away.

What you will learn#

• How GET / chooses between the framework welcome page and your SPA
• Where APP_NAME is used (welcome, docs title, logger)
• Optional [welcome] toggles to hide sections

Before you start#

How it works#

flowchart TD
  Get["GET /"] --> Spa{"public/index.html exists?"}
  Spa -->|yes| Index[Serve SPA shell]
  Spa -->|no| Welcome[FrameworkWelcomePage]
  Welcome --> Assets["/__pionia/* assets"]

The welcome page is framework-owned. Brand it with config; do not fork the HTML into your app.

Set your app name#

In environment/.env (preferred) or settings:

APP_NAME=Pionia Shop

Pionia humanizes the value for display (e.g. pionia-shop → a readable title). The welcome navbar leads with this name, and Moonlight docs / logger naming pick it up too.

Optional welcome sections#

environment/settings.ini:

[welcome]
HIDE_CONTEXT=false
HIDE_QUICK_START=false
HIDE_ENV=false
HIDE_PORT=false

Set any flag to true to hide that block on the welcome page (useful for demos).

When the welcome page disappears#

After php pionia frontend:build (or any process that writes public/index.html), / serves your SPA. API routes under /api/ are unchanged. Framework assets remain at /__pionia/.

Environment directory#

Pionia loads .env and settings.ini from the app’s environment/ directory (resolved from the application base path). Running the CLI from a subdirectory still finds the correct environment/ — you do not need to cd for config to load.

Common mistakes#

• Leaving APP_NAME as the Composer package slug — set a product name people recognize on the welcome page.
• Copying /__pionia assets into public/static/ — they are served from the framework package; duplication goes stale on upgrades.
• Expecting the welcome page after deploying a Vite build — public/index.html wins by design.

What’s next#