Getting started with Emporia
This guide takes you from the download to your own store admin in six steps: run it, make it look
like your brand, add a page, connect your backend, apply roles and deploy. The README.md in the
download is the full reference; this page is the path through it.
- Live demo: https://demo.rr-dev.eu/emporia/overview
- Every endpoint the template calls:
docs/openapi.yaml(OpenAPI 3.1)
1. Install and run
You need Node.js 22.22+, 24.15+ or 26+. A global Angular CLI is not needed.
npm install
npm start # http://localhost:4200
Sign in with demo@emporia.app / emporia-demo, or register a new account.
Out of the box the app runs in mock mode: every page talks to an in-browser fake backend
with realistic data, latency and errors, and saves your changes in localStorage. You can build the
whole UI before your backend exists, then switch to it with one line (step 4).
The fake store (120 products, 800 customers, about 5,000 orders over 18 months, 12 discount codes)
is generated from a fixed seed. What you change in the demo (ship, refund or cancel an order, edit
products, adjust stock, edit customers, create discounts) is kept apart in
src/app/core/mock/store-state.ts, saved under the emporia.mock.store key, and every page reads
from it. That is why a refund with "Restock items" shows up in Inventory, Products, Customers and
the Overview at once. The generated data itself is never modified.
Two things worth trying in the running app:
- Settings → Appearance → Mock API: simulate a slow network or failing requests to see skeletons, error states and Retry buttons.
- Account menu → Preview as role: see the app as an Admin, Staff or Viewer.
To reset the demo, clear the site's localStorage in the browser's dev tools (Application →
Local storage → Clear). Every key starts with emporia., so you can also delete only those.
2. Make it yours
Name and logo
Search the project for Emporia (sidebar, sign-in pages, page titles in app.routes.ts,
index.html). The logo mark is the logo icon in src/app/shared/ui/icon.ts: replace its SVG
markup with yours, then swap public/favicon.svg, favicon.ico and apple-touch-icon.png.
The emporia. prefix of the keys saved in the browser is in src/app/core/storage/local-storage.ts
(and in index.html, which reads the saved theme before the app starts): change it in both places
so your app does not share keys with other apps on the same domain.
Brand color
All colors are tokens in src/styles.css, one block for light and one for dark. Orange is the
default accent; to use your brand color, change the --app-accent* tokens in both blocks:
:root {
--app-accent: #0f766e; /* buttons, links, active menu item */
--app-accent-hover: #115e59;
--app-accent-soft: #ccfbf1; /* tinted backgrounds */
--app-accent-ink: #ffffff; /* text on accent buttons */
}
.dark {
--app-accent: #2dd4bf;
/* … the same four tokens, tuned for the dark background */
}
Every button, badge, chart highlight and focus ring follows. Check that text on the accent and
accent text on surfaces still reach WCAG AA contrast (4.5:1). The other accent colors that users can
pick in Settings → Appearance are data-accent blocks further down the same file.
Links
src/app/config/links.ts holds the optional "Getting started", "API reference" and "Support" links
of the sidebar and the "Download" button of the topbar. In the download they ship empty, so they are
hidden: fill them in or leave them.
3. Add a page
As an example, a Suppliers page with its own data. Every feature follows the same layout, so once you have done this you can read the rest of the code.
3.1 Model and contract
src/app/features/suppliers/data-access/suppliers.models.ts
export interface Supplier {
id: string;
name: string;
country: string;
leadTimeDays: number;
status: 'active' | 'paused';
}
src/app/features/suppliers/data-access/suppliers.api.ts: the page depends only on this class.
import { Observable } from 'rxjs';
import { Supplier } from './suppliers.models';
export abstract class SuppliersApi {
abstract list(): Observable<Supplier[]>;
}
3.2 Mock and HTTP implementations
suppliers.api.mock.ts: data in the browser, with the same simulated latency and errors as the
rest of the app.
import { Injectable } from '@angular/core';
import { Observable } from 'rxjs';
import { mockResponse } from '../../../core/mock/mock-response';
import { SuppliersApi } from './suppliers.api';
import { Supplier } from './suppliers.models';
const SUPPLIERS: Supplier[] = [
{ id: 's1', name: 'Nordic Textiles', country: 'Sweden', leadTimeDays: 12, status: 'active' },
{ id: 's2', name: 'Porto Ceramics', country: 'Portugal', leadTimeDays: 21, status: 'paused' },
];
@Injectable()
export class MockSuppliersApi extends SuppliersApi {
list(): Observable<Supplier[]> {
return mockResponse(() => SUPPLIERS);
}
}
suppliers.api.http.ts: the only file that knows your backend's URL.
import { HttpClient } from '@angular/common/http';
import { Injectable, inject } from '@angular/core';
import { Observable } from 'rxjs';
import { API_BASE_URL } from '../../../core/api/api.config';
import { SuppliersApi } from './suppliers.api';
import { Supplier } from './suppliers.models';
@Injectable()
export class HttpSuppliersApi extends SuppliersApi {
private readonly http = inject(HttpClient);
private readonly baseUrl = inject(API_BASE_URL);
list(): Observable<Supplier[]> {
return this.http.get<Supplier[]>(`${this.baseUrl}/suppliers`);
}
}
3.3 The page
src/app/features/suppliers/suppliers.page.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { rxResource } from '@angular/core/rxjs-interop';
import { errorMessage } from '../../core/api/api-error';
import { LoadError } from '../../shared/ui/load-error';
import { PageHeader } from '../../shared/ui/page-header';
import { SuppliersApi } from './data-access/suppliers.api';
@Component({
selector: 'app-suppliers-page',
changeDetection: ChangeDetectionStrategy.OnPush,
imports: [PageHeader, LoadError],
template: `
<app-page-header title="Suppliers" description="Who you buy your stock from." />
<div class="card">
@if (suppliers.error(); as err) {
<app-load-error class="m-4 block" [message]="message(err)" (retry)="suppliers.reload()" />
} @else if (suppliers.isLoading()) {
<p class="p-4 text-sm text-muted">Loading…</p>
} @else {
<ul class="divide-y divide-line">
@for (supplier of suppliers.hasValue() ? suppliers.value() : []; track supplier.id) {
<li class="flex items-center justify-between p-4">
<div>
<p class="font-medium">{{ supplier.name }}</p>
<p class="text-sm text-muted">{{ supplier.country }} · {{ supplier.leadTimeDays }} days lead time</p>
</div>
<span class="badge">{{ supplier.status }}</span>
</li>
}
</ul>
}
</div>
`,
})
export class SuppliersPage {
private readonly api = inject(SuppliersApi);
protected readonly suppliers = rxResource({ stream: () => this.api.list() });
protected readonly message = errorMessage;
}
Read the resource with hasValue() ? value() : …: value() throws while the request is in error.
For loading skeletons, empty states, filters in the URL and tables, copy from an existing page such
as features/discounts/discounts.page.ts and reuse the pieces in shared/ui (<app-load-error>,
<app-pagination>, <app-kpi-card>, <app-segmented>…). Prices are cents; formatPrice() in
shared/utils/money.ts formats them.
3.4 Route and menu
src/app/features/suppliers/suppliers.routes.ts binds the contract to the mock or HTTP class,
depending on the mode chosen in app.config.ts:
import { Routes } from '@angular/router';
import { apiProvider } from '../../core/api/provide-api';
import { SuppliersApi } from './data-access/suppliers.api';
import { HttpSuppliersApi } from './data-access/suppliers.api.http';
import { MockSuppliersApi } from './data-access/suppliers.api.mock';
import { SuppliersPage } from './suppliers.page';
export default [
{
path: '',
providers: [apiProvider(SuppliersApi, { mock: MockSuppliersApi, http: HttpSuppliersApi })],
component: SuppliersPage,
},
] satisfies Routes;
In src/app/app.routes.ts, next to the other pages inside the shell:
{
path: 'suppliers',
title: 'Suppliers · Emporia',
loadChildren: () => import('./features/suppliers/suppliers.routes'),
},
In src/app/layout/navigation.ts, add the menu entry to the first section:
{ label: 'Suppliers', path: '/suppliers', icon: 'package' },
Icons come from shared/ui/icon.ts; to add one, paste its Lucide SVG markup
into the ICONS map. Run npm start and Suppliers is in the sidebar, the command palette and on
phones.
4. Connect your backend
Switch the mode
In src/app/app.config.ts:
provideApi({ mode: 'http', baseUrl: 'https://api.your-store.com' }),
Every feature now uses its *.api.http.ts class. Nothing in the pages changes. Role previews
(Preview as role) are only available in mock mode.
What your backend must answer
docs/openapi.yaml (OpenAPI 3.1) lists every endpoint, request and response the HTTP classes use.
Generate a server stub or client types from it, render it with any OpenAPI viewer, or run a mock
server: npx @stoplight/prism-cli mock docs/openapi.yaml. Errors are JSON { "message": "…" } and
the message is shown to the user as is.
Start with authentication. POST /auth/login receives { email, password, remember } and
returns:
{
"token": "eyJhbGciOi…",
"expiresAt": "2026-12-31T23:59:59Z",
"user": {
"id": "usr_1",
"name": "Alex Morgan",
"email": "alex@your-store.com",
"company": "Your Store",
"role": "owner"
}
}
role is one of owner, admin, staff, viewer. From then on the interceptor
(core/auth/auth.interceptor.ts) sends Authorization: Bearer <token> with every request to
baseUrl. If your API runs on another domain, allow the app's origin in its CORS settings.
Different response shapes
If your API returns other field names, adapt in the HTTP class only, with RxJS map:
list(): Observable<Supplier[]> {
return this.http
.get<{ data: { uuid: string; title: string; country_name: string; lead_days: number; is_paused: boolean }[] }>(
`${this.baseUrl}/v2/suppliers`,
)
.pipe(
map((res) =>
res.data.map((s) => ({
id: s.uuid,
name: s.title,
country: s.country_name,
leadTimeDays: s.lead_days,
status: s.is_paused ? ('paused' as const) : ('active' as const),
})),
),
);
}
(Import map from rxjs.)
One feature at a time
You can connect features one by one: keep the mock for a page whose endpoints are not ready by
binding it explicitly in its routes file, instead of apiProvider:
providers: [{ provide: SuppliersApi, useClass: MockSuppliersApi }],
5. Roles and permissions
The role comes from user.role in the login response. What each role may do is one table in
src/app/core/auth/permissions.ts:
| Permission | What it allows | Owner | Admin | Staff | Viewer |
|---|---|---|---|---|---|
orders.manage |
Fulfill and cancel orders | yes | yes | yes | no |
orders.refund |
Refund orders | yes | yes | no | no |
products.write |
Create, edit and delete products, change prices | yes | yes | no | no |
inventory.adjust |
Adjust stock levels | yes | yes | yes | no |
customers.write |
Create and edit customers | yes | yes | yes | no |
discounts.manage |
Create, edit and delete discount codes | yes | yes | no | no |
store.manage |
Store settings | yes | no | no | no |
team.manage |
Invite members, change roles, remove members | yes | yes | no | no |
developers.manage |
API keys and webhook endpoints | yes | yes | no | no |
To protect the Suppliers page, add a permission to the Permission type and to the roles that
have it:
export type Permission =
| 'orders.manage'
// …
| 'suppliers.manage';
export const ROLE_PERMISSIONS: Record<UserRole, readonly Permission[]> = {
owner: [/* … */ 'suppliers.manage'],
admin: [/* … */ 'suppliers.manage'],
staff: [/* … */],
viewer: [],
};
Then use it where it matters:
Menu:
{ label: 'Suppliers', path: '/suppliers', icon: 'package', permission: 'suppliers.manage' }hides the entry for the other roles.Route: in
app.routes.tsthe guard shows the "no access" page to whoever opens the URL anyway;runGuardsAndResolvers: 'always'checks it again when the role changes on that page (Preview as role):{ path: 'suppliers', title: 'Suppliers · Emporia', canActivate: [permissionGuard('suppliers.manage')], runGuardsAndResolvers: 'always', loadChildren: () => import('./features/suppliers/suppliers.routes'), },Import it with
import { permissionGuard } from './core/auth/permission.guard';.Buttons: inject
AccessServiceand write@if (access.can('suppliers.manage')) { … }.
The UI only hides what a role may not do. Your backend must check the same permissions and
answer 403, otherwise anyone can call the API directly. The mock APIs already do (see
core/mock/mock-access.ts), so you can see how each page reacts to a 403 with Preview as role.
6. Build and deploy
npm test # unit tests
npm run e2e # end-to-end tests (run `npx playwright install` once first)
npm run build # output: dist/emporia/browser/
The output is a static site: host it on Netlify, Vercel, Cloudflare Pages, S3 or Nginx. Configure
the host to serve index.html for unknown paths (examples for each host are in the README, section Deployment), and
enable gzip or Brotli compression and long caching for the hashed .js and .css files.
Before going live:
provideApi({ mode: 'http', … })inapp.config.ts.- Remove the demo account hint from
features/auth/login/login.page.ts(the "Demo account" line with the fill-in button) and the demo password hint fromfeatures/settings/security/security-settings.ts(thedescriptionof the password card). Then deleteDEMO_CREDENTIALSand the hard-coded demo password check in the mock if you no longer use mock mode. - Replace the logo, favicons and the
Emporianame (step 2). - Check that your backend enforces the permissions (step 5).
- Fill in or leave empty the links in
config/links.ts.
Questions or a bug? Write to the support address in config/links.ts (SUPPORT_EMAIL).
Get Emporia
Free for personal and commercial projects, pay what you want. The demo runs entirely in your browser on generated data.