rrstudio Dashboards

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.


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:

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:

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:

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.