Frontend — Environment & Configuration
Installing dependencies and configuring the Next.js client
Step 1 — Install Frontend Dependencies
Open a second VS Code window with the saas-pos-frontend folder. In its terminal, run:
This may take 2–5 minutes.
Step 2 — Create the .env.local File
The repository ships a template with every supported variable. Copy it, then fill in your values:
(On Windows without Git Bash: duplicate .env.example in the VS Code sidebar
and rename the copy to .env.local.)
Required Variable
| Variable | Description | Development Value | |
|---|---|---|---|
| NEXT_PUBLIC_API_URL | Backend REST API base URL. Must include the /api/v1 suffix — the Socket.IO client derives the websocket URL from it by stripping /api/v1. | http://localhost:5000/api/v1 | Required |
Set NEXT_PUBLIC_API_URL=http://localhost:5000/api/v1 — not
…/api and not the bare host. Every API module and the realtime
socket connection build their URLs from this one value. There is no separate
socket URL variable.
Image Uploads — Cloudinary
Product, brand, and branding images are uploaded from the browser straight to
Cloudinary using an unsigned upload preset; deletions go through a small
server-side route that signs the request with your API secret. All four
variables live in the frontend .env.local (the backend does not talk to
Cloudinary).
| Variable | Description | Example / Format | |
|---|---|---|---|
| NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME | Your Cloudinary cloud identifier | my-cloud-name | Required |
| NEXT_PUBLIC_CLOUDINARY_UPLOAD_PRESET | Name of an unsigned upload preset | posvelo_unsigned | Required |
| CLOUDINARY_API_KEY | API key — server-side only, used to sign image deletions | 123456789012345 | Required |
| CLOUDINARY_API_SECRET | API secret — server-side only, never exposed to the browser | abc123xyz… | Required |
To get these values:
- Create a free account at cloudinary.com and copy the Cloud Name, API Key, and API Secret from the dashboard.
- Go to Settings › Upload › Upload presets › Add upload preset, set
Signing mode to Unsigned, save, and use the preset's name for
NEXT_PUBLIC_CLOUDINARY_UPLOAD_PRESET.
The app runs without Cloudinary — you just won't be able to upload product, brand, or logo images until the four values are set.
Optional Variables
| Variable | Description | Example | |
|---|---|---|---|
| NEXT_PUBLIC_CODECANYON_URL | Purchase link shown by the demo banner | https://codecanyon.net/item/… | Optional |
| NEXT_PUBLIC_DEMO_MODE | Shows the public demo banner/credentials on the login page. Pair with the backend's DEMO_MODE. | false | Optional |
| NEXT_PUBLIC_TEST_MODE | Enables developer quick-login buttons on the login page. Never enable in production. | false | Optional |
| NEXT_PUBLIC_TEST_ADMIN_EMAIL | Quick-login email for the Admin button (test mode only) | admin@example.com | Optional |
| NEXT_PUBLIC_TEST_MANAGER_EMAIL | Quick-login email for the Manager button | manager@example.com | Optional |
| NEXT_PUBLIC_TEST_CASHIER_EMAIL | Quick-login email for the Cashier button | cashier@example.com | Optional |
| NEXT_PUBLIC_TEST_HR_EMAIL | Quick-login email for the HR button | hr@example.com | Optional |
| NEXT_PUBLIC_TEST_EMPLOYEE_EMAIL | Quick-login email for the Employee button | employee@example.com | Optional |
Complete .env.local Example
The NEXT_PUBLIC_ prefix exposes variables to the browser bundle. Never
store secrets, passwords, or API keys with this prefix — they will be visible
to all users. That is why CLOUDINARY_API_KEY / CLOUDINARY_API_SECRET have
no prefix (they stay on the server) and why test-mode passwords are never put
in environment variables at all.