https://github.com/bfloo-app/web-client-dashboard
Bfloo Web Dashboard is a modern, responsive SvelteKit application featuring a branded UI, Tailwind CSS, and full PWA support.
https://github.com/bfloo-app/web-client-dashboard
database-management sveltekit tailwindcss web webapplication
Last synced: 2 months ago
JSON representation
Bfloo Web Dashboard is a modern, responsive SvelteKit application featuring a branded UI, Tailwind CSS, and full PWA support.
- Host: GitHub
- URL: https://github.com/bfloo-app/web-client-dashboard
- Owner: Bfloo-App
- Created: 2025-02-02T16:40:27.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-24T01:20:40.000Z (2 months ago)
- Last Synced: 2026-04-24T02:32:36.999Z (2 months ago)
- Topics: database-management, sveltekit, tailwindcss, web, webapplication
- Language: TypeScript
- Homepage: https://my.bfloo.com
- Size: 7.91 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Build Status
# Bfloo Web Client Dashboard
Modern SvelteKit-based web dashboard for Bfloo App, built with TypeScript, Tailwind CSS v4, and comprehensive testing.
## Table of Contents
- [Overview](#overview)
- [Tech Stack](#tech-stack)
- [Quick Start](#quick-start)
- [Development](#development)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Available Scripts](#available-scripts)
- [Environment Setup](#environment-setup)
- [Architecture](#architecture)
- [Project Structure](#project-structure)
- [Path Aliases](#path-aliases)
- [Component Organization](#component-organization)
- [Testing](#testing)
- [Test Structure](#test-structure)
- [Running Tests](#running-tests)
- [Writing Tests](#writing-tests)
- [Code Quality](#code-quality)
- [Git Hooks](#git-hooks)
- [Commit Message Format](#commit-message-format)
- [Linting & Formatting](#linting--formatting)
- [Deployment](#deployment)
- [Docker](#docker)
- [Production Build](#production-build)
- [Contributing](#contributing)
- [License](#license)
## Overview
The Bfloo web client dashboard is a modern, responsive web application built to provide a comprehensive dashboard interface for the Bfloo platform. It features a component-based architecture, real-time data visualization, and a responsive design optimized for various screen sizes.
## Tech Stack
- **Framework**: SvelteKit 2 with Svelte 5 (runes syntax)
- **Build Tool**: Vite 7 with TypeScript
- **Styling**: Tailwind CSS v4 (via `@tailwindcss/vite` plugin)
- **Testing**: Vitest with dual environment setup (browser + node)
- **E2E Testing**: Playwright for end-to-end testing
- **Deployment**: Node.js adapter with Docker containerization
- **Code Quality**: ESLint, Prettier, Husky hooks
- **CI/CD**: GitHub Actions for automated testing and builds
## Quick Start
```sh
# Clone the repository
git clone https://github.com/Bfloo-App/web-client-dashboard.git
cd web-client-dashboard
# Install dependencies
npm install
# Start development server
npm run dev
# Open in browser
open http://localhost:3000
```
## Development
### Prerequisites
- **Node.js**: >= 18.x
- **npm**: >= 9.x
- **Git**: For version control and hooks
### Installation
```sh
# Install all dependencies
npm install
# Initialize Husky git hooks
npm run prepare-pre-commit
# Prepare SvelteKit (sync types and generate files)
npm run prepare
```
### Available Scripts
| Command | Description |
| --------------------- | ---------------------------------------------- |
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Build for production |
| `npm run preview` | Preview production build locally |
| `npm run start` | Start production server (requires build) |
| `npm run check` | Run TypeScript type checking |
| `npm run check:watch` | Run type checking in watch mode |
| `npm run test` | Run all tests (unit + integration) |
| `npm run test:unit` | Run tests in watch mode |
| `npm run lint` | Check code formatting and linting |
| `npm run lint:fix` | Fix auto-fixable linting and formatting issues |
| `npm run format` | Format code with Prettier |
### Environment Setup
Create a `.env` file in the root directory based on `.env.example`:
```env
# Environment configuration
NODE_ENV=development
PORT=3000
HOST=localhost
# Add other environment variables as needed
TEST_SECRET=your_test_secret_here
```
## Architecture
### Project Structure
```
src/
├── lib/
│ ├── assets/
│ │ ├── icons/ # SVG icon components
│ │ └── images/ # Static images and imports
│ ├── components/
│ │ ├── layouts/ # Layout components (Header, etc.)
│ │ └── pages/ # Page-specific components
│ └── types/ # TypeScript type definitions
├── routes/ # SvelteKit file-based routing
├── styles/ # Global CSS files
└── app.html # HTML template
```
### Path Aliases
Configure in `svelte.config.js` for clean imports:
```typescript
// Instead of: import { Header } from '../../../lib/components/layouts'
import { Header } from '$components/layouts';
```
| Alias | Path |
| ------------- | ----------------------- |
| `$components` | `src/lib/components` |
| `$icons` | `src/lib/assets/icons` |
| `$images` | `src/lib/assets/images` |
### Component Organization
All component directories use **barrel exports** via `index.ts` files:
```typescript
// src/lib/components/layouts/index.ts
export { default as Header } from './Header.svelte';
```
**Adding New Components:**
1. Create the `.svelte` file
2. Export it in the local `index.ts`
3. Import using path aliases
## Testing
### Test Structure
Dual environment testing setup using Vitest:
- **Browser tests**: Svelte components using `@vitest/browser` + `vitest-browser-svelte`
- **Node tests**: Utilities, server-side logic, and non-DOM functionality
- **E2E tests**: Playwright for full application testing
```
tests/
├── lib/
│ ├── components/ # Component unit tests
│ └── utils/ # Utility function tests
└── routes/ # Integration tests for pages
```
### Running Tests
```sh
# Run all tests
npm run test
# Run tests in watch mode
npm run test:unit
# Run with UI (install vitest UI first)
npx vitest --ui
```
### Writing Tests
**Component Testing Pattern:**
```typescript
import { render } from 'vitest-browser-svelte';
import { expect, test } from 'vitest';
import MyComponent from './MyComponent.svelte';
test('should render correctly', async () => {
render(MyComponent, { props: { title: 'Test' } });
await expect.element().getByRole('heading').toHaveTextContent('Test');
});
```
**Key Testing Practices:**
- Use `data-testid` attributes for complex component selection
- Prefer accessible selectors (`getByRole`, `getByAltText`)
- Test both unit behavior and integration functionality
- Include visual regression tests for critical UI components
## Code Quality
### Git Hooks
Automated quality checks using [Husky](https://typicode.github.io/husky/):
**Pre-commit Hook:**
1. 🎨 Formats staged files with Prettier
2. 🔧 Auto-fixes ESLint issues
3. 🔍 Runs TypeScript type checking
4. ✅ Re-stages formatted files automatically
**Commit Message Hook:**
- Validates conventional commit format
- Enforces consistent commit history
### Commit Message Format
Follow [Conventional Commits](https://www.conventionalcommits.org/) specification:
```
():
Examples:
feat(dashboard): add user metrics visualization
fix(nav): resolve mobile menu z-index issue
docs(readme): update installation instructions
test(header): add navigation accessibility tests
```
**Commit Types:**
- `feat`: New features
- `fix`: Bug fixes
- `docs`: Documentation updates
- `style`: Code formatting changes
- `refactor`: Code restructuring
- `test`: Test additions/modifications
- `chore`: Maintenance tasks
- `perf`: Performance improvements
### Linting & Formatting
**ESLint Configuration:**
- Extends `@eslint/js` recommended rules
- Svelte-specific linting via `eslint-plugin-svelte`
- TypeScript integration with `typescript-eslint`
- Prettier integration for consistent formatting
**Prettier Configuration:**
- Tailwind CSS class sorting via `prettier-plugin-tailwindcss`
- Svelte template formatting via `prettier-plugin-svelte`
- Project-specific config in `.prettierrc.project`
## Deployment
### Docker
Multi-stage Docker build for optimized production images:
```sh
# Build Docker image
docker build -t bfloo-web-dashboard .
# Run container
docker run -p 3000:3000 bfloo-web-dashboard
```
**Docker Features:**
- Alpine Linux base for minimal image size
- Non-root user for security
- Optimized dependency caching
- Production-only runtime dependencies
### Production Build
```sh
# Build for production
npm run build
# Preview production build
npm run preview
# Start production server
npm run start
```
The build outputs to the `build/` directory using the Node.js adapter for server-side deployment.
## Contributing
1. **Fork & Clone**: Create your own fork and clone it locally
2. **Branch**: Create a feature branch (`git checkout -b feat/amazing-feature`)
3. **Develop**: Make your changes following the architecture patterns
4. **Test**: Ensure all tests pass and add new tests for your changes
5. **Commit**: Use conventional commit messages
6. **Push**: Push to your fork and create a Pull Request
**Before Contributing:**
- Review existing component patterns
- Ensure your code follows the established conventions
- Run the full test suite before submitting
## License
This project is proprietary software. All rights reserved.