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 .envEdit 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.
Core variables
| Variable | Required | Purpose | Safe example |
|---|---|---|---|
DATABASE_URL | Required | PostgreSQL connection string. Everything else fails without it. | postgresql://user:pass@host:5432/salex |
DIRECT_URL | Required | Direct (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_URL | Required | The public address of your site. Used in emails and absolute links. Must match your domain in production. | https://yourstore.com |
AUTH_SECRET | Required | Secret used to sign login sessions. Any long random string (32+ chars). Generate with openssl rand -base64 32. | kX9mQ2...your-random-string |
NODE_ENV | Optional | development locally, production on the live server. Next.js sets this automatically in most cases; do not set it to production locally. | production |
LOG_LEVEL | Optional | Logging verbosity (debug, info, warn, error). | info |
NEXT_PUBLIC_SITE_URL | Optional | Site URL available to browser code (some components read it). | https://yourstore.com |
REDIS_URL | Optional | Redis connection for caching/rate limiting. The app runs without it; add one for heavier traffic. | redis://localhost:6379 |
SEARCH_PROVIDER | Optional | Search backend selection; default database search needs nothing. | leave unset unless advised |
FLASH_DEALS_CRON_SECRET | Optional | Secret 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.
| Variable | Required | Purpose | Notes |
|---|---|---|---|
SEED_SUPER_ADMIN_EMAIL | Optional | Login email for the first admin. | Defaults to a placeholder if unset — always set your real email. |
SEED_SUPER_ADMIN_NAME | Optional | Display name of the admin. | Free text. |
SEED_SUPER_ADMIN_PASSWORD | Optional | Plaintext dev password; the seed hashes it automatically. | Dev use only — prefer the HASH variant on real servers. |
SEED_SUPER_ADMIN_PASSWORD_HASH | Optional | A 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.
| Variable | Required | Purpose | |
|---|---|---|---|
STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_API_URL | For Stripe | Stripe Checkout payments. Webhook secret comes from the Stripe Dashboard webhook settings. | |
PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_API_URL | For PayPal | PayPal REST credentials. | |
SSLCOMMERZ_STORE_ID, SSLCOMMERZ_STORE_PASSWORD, SSLCOMMERZ_API_URL | For SSLCOMMERZ | Store credentials from the SSLCOMMERZ panel. | |
BKASH_APP_KEY, BKASH_APP_SECRET, BKASH_API_URL | For bKash | bKash merchant API credentials. | |
NAGAD_MERCHANT_ID, NAGAD_PRIVATE_KEY, NAGAD_API_URL | For Nagad | Nagad merchant credentials. | |
RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET, RAZORPAY_API_URL | For Razorpay | Razorpay API keys. | |
PAYMENT_WEBHOOK_SECRET | Optional | Shared secret for non-Stripe payment webhooks. | |
AI_PROVIDER, AI_API_KEY, AI_BASE_URL, AI_MODEL | For AI agent | Powers the AI sales assistant and product Q&A. Without it the storefront works; the /ai page reports it as unconfigured. | |
FASHN_API_KEY | Optional | Virtual try-on image generation. | |
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_SECURE, EMAIL_FROM | For email | Outgoing 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_THRESHOLD | Optional | Stock 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.
.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
- Quotes and spaces: values with special characters should be wrapped in double quotes:
APP_URL="https://my store.com"— but URLs never contain spaces; that's a typo. - Editing .env without restarting the dev server — changes appear to “do nothing”.
- Using the pooled connection string in DIRECT_URL on Supabase/Neon — migrations fail with timeout errors. Use the provider's direct connection string.
- Localhost in production: leaving
APP_URL="http://localhost:3000"on the live server breaks email links and checkout redirects. - Sharing screenshots of .env — always crop out or redact values.