Env & Secrets

When building a static site, you often need to inject configuration values at runtime – for example, the base URL of your site or feature flags that vary between environments. LeadCMS provides a simple mechanism to expose public environment variables to your front‑end without rebuilding the site. At the same time, you must protect secrets by keeping them server‑side.

Build once, use everywhere

A key principle of static site deployment is build once, use everywhere. You shouldn’t need to rebuild your site for each environment (development, staging, production). Instead, you build once and inject environment‑specific values when serving. In LeadCMS, variables starting with NEXT_PUBLIC_ are treated as public configuration that can be safely exposed in the browser.

Runtime injection with __env.js

The LeadCMS SDK includes a helper script to generate a special file at runtime:

• inject-runtime-env.sh: During container start‑up (or in your deployment pipeline), this script reads all environment variables that begin with NEXT_PUBLIC_ and writes them into public/__env.js as JavaScript code.
• __env.js: This file defines a window.__env object containing the values of your public variables. Your front‑end code can read from window.__env to access these values.

When you use the leadcms docker command, the generated Dockerfile runs inject-runtime-env.sh before Nginx starts, ensuring __env.js is always up‑to‑date for each environment. For static exports, you need to run a similar injection step in your deployment pipeline:

# Example of generating __env.js during static deployment
cat > public/__env.js <<'EOT'
window.__env = {
  NEXT_PUBLIC_SITE_URL: "https://staging.example.com",
  NEXT_PUBLIC_FEATURE_FLAG: "true"
}
EOT

Place this script in your CI/CD workflow so that __env.js is generated with the correct values before deploying your static files.

Managing secrets

Secrets such as API keys, database passwords or authentication tokens must remain on the server. For container deployments, pass them as regular environment variables (without the NEXT_PUBLIC_ prefix) and use them only in server‑side code. For purely static sites, consider using serverless functions or proxies to handle secret values.

Some best practices:

• Use environment variables for secrets: Set sensitive variables at deploy time (e.g. LEADCMS_API_KEY, LEADCMS_URL, LEADCMS_DEFAULT_LANGUAGE). These are consumed by the LeadCMS SDK and not exposed to the client.
• Avoid committing secrets to version control: Keep secrets out of your repository by using .env files locally and environment variables in CI/CD.
• Rotate secrets regularly: Regenerate API keys and update your deployment pipeline accordingly. LeadCMS CLI commands like leadcms login let you obtain new tokens.

Multi‑environment deployment

When deploying the same build to multiple environments:

1. Build your static site once (for example, in a CI build job).
2. Store the build artifacts (e.g. in an artifact store or container registry).
3. For each environment, inject environment‑specific NEXT_PUBLIC_ variables using __env.js (or via the Docker runtime).
4. Deploy the build artifacts along with the generated __env.js file.

This pattern avoids the need to rebuild the site for each environment and ensures consistent behaviour across staging and production.

Summary

• Prefix public configuration variables with NEXT_PUBLIC_ to make them available to your front‑end.
• Use inject-runtime-env.sh or a similar script to populate public/__env.js with runtime values.
• Keep secrets out of the public runtime; supply them via private environment variables and server‑side code.
• Build once, deploy everywhere by injecting environment values at serve time.

With these practices, your LeadCMS site remains flexible and secure across environments.

Next steps

With secure environment configuration in place, you're ready to deploy and manage your LeadCMS instance: