envHelper/blueprint.md

{{ template:title }}

{{ template:badges }}

{{ template:section-line }} {{ template:table-of-contents }}

{{ template:section-line }}

Overview

EnvHelper reads .env files or plain text, detects CHANGE_ME placeholders, infers the required value format, and produces a ready-to-use output file. Identical placeholders are replaced with the same generated value, so related variables such as DATABASE_URL and POSTGRES_PASSWORD stay in sync.

The app is local-first. It does not send generated secrets or input files to external services.

{{ template:section-line }}

Features

Area	Description
File and text input	Load .env files, paste text directly, copy output, or save a new .env
Placeholder replacement	Detects CHANGE_ME... values and replaces them with format-aware values
Consistency	Reuses the same generated value for repeated placeholders
Supported formats	Passwords, secrets, Base64, hex, UUIDs, ports, URLs, email addresses, and API key prefixes
Default values	Detects likely defaults automatically and allows manual overrides
Desktop UI	Compact Windows app with a native title bar, dark mode, and settings
Languages	German, English, Spanish, French, and Dutch
Build output	Windows setup and portable executables via Gitea Runner

{{ template:section-line }}

Workflow

1. Load a .env file or paste text.
2. Review automatically detected defaults or add your own.
3. Generate values for CHANGE_ME placeholders.
4. Copy the output or save it as a new .env file.

Input                    Processing                    Output
-----                    ----------                    ------
DATABASE_URL=...         Detect placeholders            DATABASE_URL=...
POSTGRES_PASSWORD=... -> Infer formats            ->    POSTGRES_PASSWORD=...
SESSION_SECRET=...       Generate local values          SESSION_SECRET=...

{{ template:section-line }}

Example

Input:

APP_PORT=3000
NODE_ENV=production
PUBLIC_BASE_URL=CHANGE_ME_PUBLIC_URL

DATABASE_URL=postgresql://app_user:CHANGE_ME_POSTGRES_PASSWORD@postgres:5432/app_db
POSTGRES_PASSWORD=CHANGE_ME_POSTGRES_PASSWORD

SESSION_SECRET=CHANGE_ME_AT_LEAST_32_RANDOM_CHARACTERS
ENCRYPTION_KEY_BASE64=CHANGE_ME_32_RANDOM_BYTES_AS_BASE64
BOOTSTRAP_ADMIN_EMAIL=CHANGE_ME_EMAIL
BOOTSTRAP_ADMIN_PASSWORD=CHANGE_ME_LONG_INITIAL_ADMIN_PASSWORD

Possible output:

APP_PORT=3000
NODE_ENV=production
PUBLIC_BASE_URL=https://example.local

DATABASE_URL=postgresql://app_user:K2d8rF7s...@postgres:5432/app_db
POSTGRES_PASSWORD=K2d8rF7s...

SESSION_SECRET=n9pS...urlSafeSecret
ENCRYPTION_KEY_BASE64=4G8t...base64Value
BOOTSTRAP_ADMIN_EMAIL=admin@example.local
BOOTSTRAP_ADMIN_PASSWORD=Wz4...strongPassword

The actual values are generated randomly on the local machine.

{{ template:section-line }}

Placeholder Detection

EnvHelper prioritizes the placeholder text over the surrounding variable name. This prevents cases such as CHANGE_ME_POSTGRES_PASSWORD inside DATABASE_URL from being misclassified as a URL.

Supported examples:

Pattern	Result
CHANGE_ME_POSTGRES_PASSWORD	Strong URL-safe password
CHANGE_ME_32_RANDOM_BYTES_AS_BASE64	32 random bytes encoded as Base64
CHANGE_ME_HEX_TOKEN	Random bytes encoded as hex
CHANGE_ME_UUID	UUID v4
CHANGE_ME_PUBLIC_URL	HTTPS URL
CHANGE_ME_EMAIL	Email address
STRIPE_SECRET_KEY=CHANGE_ME	Stripe-like sk_test_... value
STRIPE_WEBHOOK_SECRET=CHANGE_ME	Stripe-like whsec_... value
AWS_ACCESS_KEY_ID=CHANGE_ME	AWS/S3-like access key ID format

Additional heuristics cover common .env.example variables for SMTP, S3/MinIO, Redis, RabbitMQ, CORS, log levels, environment flags, and API keys.

{{ template:section-line }}

Default Values

Default values are shown in their own section. EnvHelper detects likely defaults automatically, for example:

Key	Default
BOOTSTRAP_ADMIN_EMAIL	admin@example.local
NODE_ENV	production
LOG_LEVEL	info
SMTP_PORT	587
S3_REGION	eu-central-1
REDIS_URL	redis://redis:6379/0

Manual defaults can always be added. They override automatically detected defaults and only affect the output, never the input template.

{{ template:section-line }}

Downloads and Artifacts

The current Windows build can be downloaded directly from the Gitea Generic Package registry:

Variant	Download
Installer	EnvHelper-setup-x64.exe
Portable	EnvHelper-portable-x64.exe

Private package downloads may require an active Gitea session or a token with package read access.

Each build also produces versioned executable artifacts:

EnvHelper-0.1.0-setup-x64.exe
EnvHelper-0.1.0-portable-x64.exe

The files are published by the Gitea Runner as an Actions artifact, as an immutable version-sha Generic Package, and as the moving latest Generic Package used by the links above.

{{ template:section-line }}

Development

Install dependencies:

npm install

Start the Vite development server:

npm run dev

Check the production build:

npm run build

Build Windows packages:

npm run dist:win

{{ template:section-line }}

Windows Build

The production Windows build runs through Gitea Actions:

.gitea/workflows/build-windows.yml

The runner:

1. checks out the repository,
2. installs Node.js,
3. installs Wine for Windows packaging on Linux,
4. builds Vite, TypeScript, and Electron,
5. creates setup and portable executables,
6. uploads artifacts and packages to Gitea.

{{ template:section-line }}

README Generation

The README structure follows the blueprint-based workflow from andreasbm/readme.

Source files:

blueprint.md
blueprint.json

Section dividers are configured as the custom section-line template in blueprint.json and stamped from blueprint.md, so generated README updates keep the same rainbow separators.

Regenerate the README with:

npm run readme

The generated output is committed as README.md so Gitea can render it directly without any additional tooling.

{{ template:section-line }}

Security

EnvHelper generates values locally in the renderer using Web Crypto. It is a helper for .env templates and is not a replacement for a central secret manager in production infrastructure.

Security posture:

Area	State
Secret generation	Uses crypto.getRandomValues and crypto.randomUUID
Renderer isolation	Electron contextIsolation and sandbox are enabled
Node access	nodeIntegration is disabled in the renderer
Navigation	New windows and renderer navigation are blocked
Content policy	The app ships with a restrictive Content Security Policy
Default storage	Sensitive manual defaults such as passwords, tokens, and API keys are not persisted
External services	No .env input or generated secret is sent to external services

Windows Defender and SmartScreen

Windows may block or delay apps from unknown publishers. This is usually caused by missing reputation or by the absence of a trusted code-signing certificate.

The workflow is prepared for code signing:

WINDOWS_CSC_LINK
WINDOWS_CSC_KEY_PASSWORD

WINDOWS_CSC_LINK is the certificate, for example a Base64-encoded .pfx file or a reachable certificate URL. WINDOWS_CSC_KEY_PASSWORD is the certificate password.

{{ template:section-line }}

Project Info

Field	Value
Author	MrSphay
Repository	MrSphay/envHelper
App ID	de.wilkensxl.envhelper
Stack	Electron, React, Vite, TypeScript
README workflow	Blueprint-inspired workflow based on andreasbm/readme