hamid
77 lines
3.2 KiB
Markdown
77 lines
3.2 KiB
Markdown
# Balinyaar — Web Client
|
|
|
|
Frontend for the Balinyaar application, built with **Next.js (App Router)**, **React**, **TypeScript**, and **Material UI (MUI)**.
|
|
|
|
It ships with a small library of reusable `App*` components, a theming system (light/dark), a lightweight global store, and public/private layouts wired for an authentication flow.
|
|
|
|
## Requirements
|
|
|
|
- Node.js 18+ and npm
|
|
- The backend API (see [`../server`](../server)) running for authenticated features
|
|
|
|
## Getting started
|
|
|
|
1. Install dependencies:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
2. Create your local environment file from the sample and adjust values:
|
|
|
|
```bash
|
|
cp .env.sample .env
|
|
```
|
|
|
|
Key variables (all `NEXT_PUBLIC_*` are exposed to the browser):
|
|
|
|
| Variable | Purpose |
|
|
| ------------------------ | ---------------------------------------------------- |
|
|
| `NEXT_PUBLIC_ENV` | `development` \| `preview` \| `production` |
|
|
| `NEXT_PUBLIC_DEBUG` | `true` enables extra console logging |
|
|
| `NEXT_PUBLIC_PUBLIC_URL` | Public URL of the site |
|
|
| `NEXT_PUBLIC_API_URL` | Base URL of the backend API (the `server` project) |
|
|
|
|
3. Run the dev server:
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Open [http://localhost:3000](http://localhost:3000).
|
|
|
|
## Available scripts
|
|
|
|
| Script | Description |
|
|
| ------------------ | ------------------------------------------------------- |
|
|
| `npm run dev` | Start the development server with hot reload |
|
|
| `npm run build` | Production build (static export to `out/`) |
|
|
| `npm run start` | Serve a production build |
|
|
| `npm run lint` | Run ESLint (`eslint-config-next`) |
|
|
| `npm run format` | Format the codebase with Prettier |
|
|
| `npm test` | Run Jest in watch mode |
|
|
| `npm run test:ci` | Run Jest once (CI) |
|
|
| `npm run type` | Type-check with `tsc` |
|
|
|
|
## Project structure
|
|
|
|
```
|
|
src/
|
|
├── app/ Next.js App Router routes (home, about, auth, me) + root layout
|
|
├── components/ Reusable UI: common App* components (AppButton, AppIcon, ...) + UserInfo
|
|
├── hooks/ Custom hooks (auth, layout, events, window size)
|
|
├── layout/ PublicLayout / PrivateLayout + TopBar, SideBar, BottomBar
|
|
├── store/ Global app store (React context + reducer)
|
|
├── theme/ MUI theme provider, light/dark palettes, colors
|
|
└── utils/ Helpers (storage, navigation, env, text, types)
|
|
```
|
|
|
|
The `@/*` import alias maps to `src/*` (see `tsconfig.json`).
|
|
|
|
> For a deeper, agent-oriented map of conventions and where to make changes, see [AGENTS.md](AGENTS.md).
|
|
|
|
## Notes
|
|
|
|
- `next.config.mjs` uses `output: 'export'`, producing a static site in `out/`.
|
|
- Authentication in `src/hooks/auth.ts` and `src/app/auth/login/LoginForm.tsx` is currently a stub (look for `// TODO: AUTH:`); wire it to the backend's JWT endpoints when implementing real auth.
|