https://github.com/Beszt/ng-ultimate-base
Everything you need to kick off new Angular projects with a ready-to-go developer experience.
https://github.com/Beszt/ng-ultimate-base
angular angular-20 angular-material angular-standalone angular-template ci-cd clean-architecture developer-experience eslint github-actions husky i18n ngx-translate prettier signal-store signals starter-template storage-service tailwindcss typescript
Last synced: 20 days ago
JSON representation
Everything you need to kick off new Angular projects with a ready-to-go developer experience.
- Host: GitHub
- URL: https://github.com/Beszt/ng-ultimate-base
- Owner: Beszt
- License: mit
- Created: 2025-09-16T20:41:58.000Z (about 1 month ago)
- Default Branch: develop
- Last Pushed: 2025-10-03T16:49:01.000Z (26 days ago)
- Last Synced: 2025-10-03T17:55:53.372Z (25 days ago)
- Topics: angular, angular-20, angular-material, angular-standalone, angular-template, ci-cd, clean-architecture, developer-experience, eslint, github-actions, husky, i18n, ngx-translate, prettier, signal-store, signals, starter-template, storage-service, tailwindcss, typescript
- Language: TypeScript
- Homepage:
- Size: 75.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-angular - ng-ultimate-base - Angular 20 template with Angular Material UI, Tailwind CSS, i18n, ESLint, Prettier, Husky, and CI/CD. (Site Templates / Free Templates)
- fucking-awesome-angular - ng-ultimate-base - Angular 20 template with Angular Material UI, Tailwind CSS, i18n, ESLint, Prettier, Husky, and CI/CD. (Site Templates / Free Templates)
README
⚡ ng-ultimate-base ⚡
> A template Angular 20 project with Material UI, Tailwind CSS, Signals, i18n, ESLint, Prettier, Husky, and CI/CD.
> Designed to kickstart new apps with a clean architecture and ready-to-go developer experience.
---
## ✨ Highlights
🚀 **Angular 20** + standalone APIs + Angular Material
🎨 **Tailwind CSS** with Prettier-powered class sorting
🧠 **Signals + Signal Store** for reactive state management
🌐 **ngx-translate** with runtime `/assets/settings.json`
📜 **Toast & Storage Services** with smart fallback logic
🧰 **ESLint, Prettier, Husky** for consistent commits
🗂️ **Ready-to-use VS Code workspace**
🐳 **GitHub Actions & Docker** for CI/CD and release pipelines
---
## 🚀 Getting Started
1. Run `npm ci`.
2. Start the dev server with `npm start` and open `http://localhost:4200`.
3. Walk through [CHECKLIST.md](./documentation/CHECKLIST.md) to align tooling, runtime configuration, and CI.
4. Review [ARCHITECTURE.md](./documentation/ARCHITECTURE.md) for the folder structure and conventions.
---
## 🧩 Core Building Blocks
### Services
- `ConfigService` Loads `/assets/settings.json` during bootstrap through an `APP_INITIALIZER`, exposes the values via the `APP_CONFIG` injection token, and provides helpers like `storageKey('suffix')` that respect the configured namespace.
- `ThemeService` Provides light/dark themes, system preference detection, and persists the last choice. It is initialized through `provideAppInitializer` in `main.ts`, so the theme is ready before the first paint.
```ts
this.themeService.toggleTheme();
this.themeService.setTheme('dark');
this.themeService.useSystemPreference();
```
- `StorageService` Wrapper around `localStorage` and `sessionStorage` with JSON serialization, graceful fallback when storage is blocked, and helpers for scoped clearing.
```ts
this.storage.setLocal('auth-user', user);
const profile = this.storage.getLocal('auth-user');
this.storage.clearSession();
```
- `LanguageService` Bootstraps the active language based on the browser locale and keeps `document.documentElement.lang` in sync. Extend translations under `src/assets/i18n`.
- `ToastService` Simplifies translated toast notifications. Provide translation keys and optional interpolation params.
```ts
this.toast.showSuccess('demo.fetch.success', { count });
this.toast.showError('demo.fetch.error');
```
- `SpinnerService` provides a global loading overlay driven by signals. Call `show()`/`hide()` directly or wrap async flows with `trackObservable`/`trackPromise` to keep UX consistent.
### Theming
- Theme styles live in `src/styles/themes/light.scss` and `dark.scss`. Extend design tokens or CSS variables there. Both files target `[data-theme=""]` so additions work for light and dark variants.
- Global base styles are gathered in `src/styles/styles.scss`. Tailwind utilities are available through `tailwind.css`.
- When adding a new theme name, update `ThemeService.availableThemes` and create a matching stylesheet.
### Base Core
- Application level providers, interceptors, and config live under `src/app/core`.
- Shared UI building blocks are under `src/app/shared` and should stay framework agnostic (no feature-specific logic).
- Feature modules sit in `src/app/features/` and can be lazy loaded or standalone. The `demo` feature shows API fetching, toast usage, theme reactions, and storage helpers working together.
---
## ⚙️ Runtime Configuration
Runtime settings are loaded at startup from `/assets/settings.json` (copied from `src/assets/settings.json` during build). `ConfigService` merges the JSON with sane defaults and normalizes values such as the storage namespace.
```json
{
"app": {
"name": "Demo Playground",
"storageNamespace": "demo"
}
}
```
- Access configuration anywhere by injecting the `APP_CONFIG` token or the `ConfigService`.
- Use `configService.storageKey('suffix')` to build namespaced keys that match the runtime namespace.
- Override settings in containerized deployments by providing environment variables (see the Docker section) or mount a custom `settings.json`.
---
## 🐳 Docker Deployment
The repository ships a multi-stage `Dockerfile` (`node:20-alpine` -> `nginx:alpine`) that builds the Angular app and serves it through Nginx. At container start the entrypoint script rewrites `/usr/share/nginx/html/assets/settings.json` from environment variables so you can _build once, run anywhere_.
### Runtime environment variables
| Variable | Default | Description |
| ----------------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
| `APP_NAME` | `Demo Playground` | Display name exposed via `ConfigService.appConfig.name`. |
| `APP_STORAGE_NAMESPACE` | `demo` | Prefix used for storage keys. Normalized (trimmed & trailing dot removed). |
| `CONFIG_PATH` | `/usr/share/nginx/html/assets/settings.json` | Override only if the app is hosted from a different root. |
### Build and run locally
```bash
# Build image
DOCKER_BUILDKIT=1 docker build -t your-org/ng-ultimate-base:local .
# Run container with custom runtime config
docker run --rm -p 8080:80 \
-e APP_NAME="My Awesome App" \
-e APP_STORAGE_NAMESPACE="myapp" \
your-org/ng-ultimate-base:local
```
### Docker Compose snippet
```yaml
services:
ng-ultimate-base:
image: your-org/ng-ultimate-base:latest
ports:
- '8080:80'
environment:
APP_NAME: 'Compose Demo'
APP_STORAGE_NAMESPACE: 'compose'
```
### Release workflow & Docker Hub
The `release` GitHub Action can optionally build and push the Docker image after the Angular build. Toggle the _Build and push Docker image_ prompt (`publish_docker`) when you dispatch the workflow. Configure the following repository secrets before triggering a release if you plan to publish the container:
- `DOCKERHUB_USERNAME` – Docker Hub account used for pushes.
- `DOCKERHUB_TOKEN` – Access token or password for that account.
- `DOCKERHUB_REPOSITORY` – Target repository in `user/image` format (e.g. `acme/ng-ultimate-base`).
Tags published when enabled:
- `user/image:X.Y.Z` (from the workflow input)
- `user/image:latest`
If the Docker option is left unchecked the workflow skips container publishing and still produces the ZIP artifact and GitHub Release. When the option is enabled the workflow requires the Docker Hub secrets and aborts the release if building/pushing the image fails.
---
## 🧠 What's Next
- Replace the demo feature with your domain feature set and keep the same folder conventions.
- Tailor `src/assets/settings.json` (or runtime env vars) with your product name, storage namespace, and other config values.
- Harden CI by adding test coverage thresholds or integration tests that reflect your stack.
- Extend the release workflow if you need to publish to additional targets (e.g. Firebase Hosting, Vercel).
- Add more languages by dropping new JSON files into `assets/i18n` and extending the language selector UI.
---
## 💡 Pro Tips
- Keep shared services stateless where possible; prefer Signal Stores inside features for business data.
- Use `ConfigService.storageKey()` for any persisted state so runtime namespaces stay in sync.
- Call `ThemeService.toggleTheme()` from UI controls instead of manipulating classes manually.
- Group Tailwind utility classes logically; Prettier with the Tailwind plugin keeps them sorted for you.
- Treat `develop` as the integration branch and protect it with required status checks provided by the existing GitHub Actions workflows.
- For quick pimp-up code you can use `npx prettier --write .` and `ng lint --fix` in root folder to automatic format code and fix minor eslint problems in all files.
---
## 📚 Additional Documentation
- [CHANGELOG.md](./documentation/CHANGELOG.md) - release history.
- [ARCHITECTURE.md](./documentation/ARCHITECTURE.md) - folder layout, layers, and extension guidance.
- [CHECKLIST.md](./documentation/CHECKLIST.md) - one-time setup steps after cloning.
- `.github/workflows/` - CI/CD definitions for pull requests, releases, and Docker pushes.