Skip to content

SPA Config Demo

React SPA demonstrating AppMecca's runtime configuration injection for static frontends.

Overview
Tech Stack React / Vite / nginx
Services 1
Pattern SPA runtime config injection

The appmecca.yaml

containers:
  - name: spa-config-demo
    dockerfile: Dockerfile
    context: .

deploy:
  - name: web
    container: spa-config-demo
    type: spa
    command: 'nginx -g "daemon off;"'   # serves the built bundle from a container
    spa_root: /usr/share/nginx/html
    port: 80
    health_check:
      path: /health
    environment:
      PUBLIC_API_URL: "https://api.example.com"
      PUBLIC_APP_TITLE: "My Configured App"

Key Concepts

SPA Runtime Config Injection

When type: spa is set, AppMecca generates a __appmecca_config.js file at deploy time containing the app's browser-safe environment variables. The file is mounted read-only into the container at {spa_root}/__appmecca_config.js.

Load it from your index.html, before your own bundle:

<script src="/__appmecca_config.js"></script>

The JavaScript code then reads config from window.__APPMECCA_CONFIG__:

const config = window.__APPMECCA_CONFIG__ || {}
const API_URL = config.PUBLIC_API_URL || 'default-value'

Build-Time vs Runtime Config

Without SPA injection, environment variables are baked into the JavaScript bundle at build time. This means you need to rebuild to change configuration. With type: spa, the same Docker image works across all environments -- only the injected config changes.

Which variables get exposed

Only variables whose names start with one of these prefixes are included in the injected config file:

Prefix Typical toolchain
PUBLIC_ framework-agnostic; the AppMecca convention
VITE_ Vite
NEXT_PUBLIC_ Next.js
REACT_APP_ Create React App

Everything else is dropped, which is what stops server-side secrets — the database password, the mailer token — from reaching the browser. As an extra guard, a variable using one of the framework prefixes is also dropped if its name contains PASSWORD, SECRET, KEY, CREDENTIAL or TOKEN. The PUBLIC_ prefix is exempt from that substring check, because using it is an explicit statement that the value is safe to publish.

Step-by-Step Deployment

1. Register the app

mecca register git@gitlab.com:appmecca-sample-apps/spa-config-demo.git \
  -e dev

2. Build

mecca build trigger \
  -e dev \
  -g git@gitlab.com:appmecca-sample-apps/spa-config-demo.git

3. Deploy

mecca app deploy -e dev spa-config-demo

4. Verify

curl https://spa-config-demo-web.dev.yourdomain.io/health
open https://spa-config-demo-web.dev.yourdomain.io

The app should show "Runtime (AppMecca)" as the config source with the injected values.

What's Next