Documentation

Environment Configuration (.env)

The .env file in the project root holds your private configuration: database address, security keys, and provider credentials. This page documents every variable SaleX actually reads.

On this page

Creating and editing .env

# Windows (PowerShell)
copy .env.example .env

# macOS / Linux
cp .env.example .env

Edit it with any text editor (Notepad, VS Code, nano). After any change, restart the dev server (Ctrl+C, then npm run dev) — environment variables are only read at startup.

Never commit or share .env It contains live secrets. Never paste its contents into support tickets, screenshots, or public repositories.

Core variables

VariableRequiredPurposeSafe example
DATABASE_URLRequiredPostgreSQL connection string. Everything else fails without it.postgresql://user:pass@host:5432/salex
DIRECT_URLRequiredDirect (non-pooled) connection used for migrations. Same as DATABASE_URL on a normal Postgres; required distinct value on pooled hosts like Supabase (use the “direct” connection string they provide).same as above, or provider's direct URL
APP_URLRequiredThe public address of your site. Used in emails and absolute links. Must match your domain in production.https://yourstore.com
AUTH_SECRETRequiredSecret used to sign login sessions. Any long random string (32+ chars). Generate with openssl rand -base64 32.kX9mQ2...your-random-string
NODE_ENVOptionaldevelopment locally, production on the live server. Next.js sets this automatically in most cases; do not set it to production locally.production
LOG_LEVELOptionalLogging verbosity (debug, info, warn, error).info
NEXT_PUBLIC_SITE_URLOptionalSite URL available to browser code (some components read it).https://yourstore.com
REDIS_URLOptionalRedis connection for caching/rate limiting. The app runs without it; add one for heavier traffic.redis://localhost:6379
SEARCH_PROVIDEROptionalSearch backend selection; default database search needs nothing.leave unset unless advised
FLASH_DEALS_CRON_SECRETOptionalSecret protecting the flash-deals cron endpoint. Set it to the value your cron job sends.another-random-string

First admin (seed) variables

These are read by npm run db:seed to create the first administrator. Set them before seeding.

VariableRequiredPurposeNotes
SEED_SUPER_ADMIN_EMAILOptionalLogin email for the first admin.Defaults to a placeholder if unset — always set your real email.
SEED_SUPER_ADMIN_NAMEOptionalDisplay name of the admin.Free text.
SEED_SUPER_ADMIN_PASSWORDOptionalPlaintext dev password; the seed hashes it automatically.Dev use only — prefer the HASH variant on real servers.
SEED_SUPER_ADMIN_PASSWORD_HASHOptionalA pre-computed bcrypt hash, so the plaintext password never appears in .env.Generate with a bcrypt tool at cost 10+.

Provider variables

Payment, AI, and email credentials can be set in .env or in the admin panel (Admin → Settings → Integrations). Values in the admin panel are stored in the database and take effect immediately — no restart. The .env copies act as fallbacks.

VariableRequiredPurpose
STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_API_URLFor StripeStripe Checkout payments. Webhook secret comes from the Stripe Dashboard webhook settings.
PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_API_URLFor PayPalPayPal REST credentials.
SSLCOMMERZ_STORE_ID, SSLCOMMERZ_STORE_PASSWORD, SSLCOMMERZ_API_URLFor SSLCOMMERZStore credentials from the SSLCOMMERZ panel.
BKASH_APP_KEY, BKASH_APP_SECRET, BKASH_API_URLFor bKashbKash merchant API credentials.
NAGAD_MERCHANT_ID, NAGAD_PRIVATE_KEY, NAGAD_API_URLFor NagadNagad merchant credentials.
RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET, RAZORPAY_API_URLFor RazorpayRazorpay API keys.
PAYMENT_WEBHOOK_SECRETOptionalShared secret for non-Stripe payment webhooks.
AI_PROVIDER, AI_API_KEY, AI_BASE_URL, AI_MODELFor AI agentPowers the AI sales assistant and product Q&A. Without it the storefront works; the /ai page reports it as unconfigured.
FASHN_API_KEYOptionalVirtual try-on image generation.
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_SECURE, EMAIL_FROMFor emailOutgoing email (order confirmations, resets). Example: host smtp.gmail.com, port 587, an app password as SMTP_PASS, EMAIL_FROM like “SaleX <no-reply@yourstore.com>”.
NOTIFICATION_LOW_STOCK_THRESHOLDOptionalStock level that triggers low-stock alerts.e.g. 5

Admin-panel settings vs .env

Many platform settings are not environment variables — they live in the database and are edited in the admin panel (Settings). Examples: store name and logo, default currency and symbol position, vendor commission, classifieds options, per-gateway payment keys and TEST/LIVE modes, shipping methods, zones and rates, tax rates, RBAC roles.

Rule of thumb Secrets and infrastructure addresses go in .env. Business configuration you might change weekly goes in the admin panel. When both offer the same setting (e.g. Stripe key), the admin panel value wins.

Common mistakes