SansiStore Local Development Quickstart Guide

This guide walks you through cloning SansiStore, wiring up the Firebase emulators, seeding the local database with test data, and launching the dev server. The entire process takes under five minutes on a fresh machine.

Prerequisites

Before you begin, make sure you have the following installed:

Bun — the JavaScript runtime and package manager used throughout the project (bun, bunx)
Java 21 — required by the Firebase Firestore emulator (the emulator is a JVM process)
Node.js ≥ 22.12.0 — some tooling in the build pipeline requires Node; the version constraint is declared in package.json

Setup Steps

Clone the repository and install dependencies

git clone https://github.com/ProcesosAgilesUMSS/sansistore
cd sansistore
bun install

bun install reads package.json and installs all runtime and dev dependencies, including firebase-tools (the CLI that drives the emulators) and playwright.

Copy the environment file

cp .env.example .env

The .env.example ships with safe placeholder values that work out of the box against the local emulators:

PUBLIC_FIREBASE_API_KEY=dummy-api-key-for-emulator
PUBLIC_FIREBASE_AUTH_DOMAIN=sansistore.firebaseapp.com
PUBLIC_FIREBASE_PROJECT_ID=sansistore
PUBLIC_FIREBASE_STORAGE_BUCKET=sansistore.appspot.com
PUBLIC_FIREBASE_MESSAGING_SENDER_ID=000000000000
PUBLIC_FIREBASE_APP_ID=demo-app-id
PUBLIC_FIREBASE_MEASUREMENT_ID=

PUBLIC_APP_ENV=development

# Server-only Firebase Admin credentials for API routes.
# Use either FIREBASE_SERVICE_ACCOUNT_KEY as a full JSON string, or the pair below.
FIREBASE_SERVICE_ACCOUNT_KEY=
FIREBASE_CLIENT_EMAIL=
FIREBASE_PRIVATE_KEY=

# Local-only fallback while login/role HUs are not implemented.
# Never enable this in production.
ENABLE_DEV_ADMIN_BYPASS=true
DEV_ADMIN_UID=dev-admin

For local development (emulators), no changes are needed — PUBLIC_APP_ENV=development is already set and the Firebase SDK will automatically connect to the local emulators instead of the cloud.For production, replace all PUBLIC_FIREBASE_* values with your real Firebase project credentials and set PUBLIC_APP_ENV=production. The Admin SDK fields (FIREBASE_SERVICE_ACCOUNT_KEY or the FIREBASE_CLIENT_EMAIL / FIREBASE_PRIVATE_KEY pair) are required for server-side API routes. These secrets are held in Vercel project settings — ask the team.

Start the Firebase emulators

bun run emu

This runs firebase emulators:start --only firestore,auth,functions,pubsub and brings up:

Emulator	Port
Auth	9099
Firestore	8080
Functions	5001
Pub/Sub	8085
Emulator UI	auto (check terminal output)

Leave this terminal open. The frontend detects PUBLIC_APP_ENV=development and automatically connects to these local ports instead of the live Firebase project.

The Firebase client SDK uses connectFirestoreEmulator and connectAuthEmulator at startup when PUBLIC_APP_ENV !== 'production'. No manual switching is needed — just keep the emulators running.

Seed the local database

Open a new terminal (keep the emulators running) and run:

bun run seed

This executes node ./seed/index.mjs, which populates the local Firestore emulator with categories, products, inventory records, test users (with various roles), and sample orders so you can exercise every part of the UI immediately.

Start the development server

bun dev

Astro starts in SSR mode and listens at http://localhost:4321. Open your browser and log in with any email (the Auth emulator does not enforce the @umss.edu domain restriction).The dev server supports hot module replacement for React components and instant page reloads for Astro files.

Running Tests

Unit Tests
Playwright E2E Tests
Docker (CI-equivalent)

Unit tests are powered by Vitest:

bun run test:unit

End-to-end tests use Playwright. Install the browser binaries first:

bunx playwright install --with-deps

Then run the full suite:

bunx playwright test

Other useful commands:

# Run a specific test file
bunx playwright test path/to/test.spec.ts

# Filter tests by name
bunx playwright test -g "login"

# View the HTML report
bunx playwright show-report

Use Docker Compose to run E2E tests in a clean, CI-equivalent environment:

# Run all tests
docker compose up testing

# Run a specific file
docker compose run --rm testing bunx playwright test path/to/test.spec.ts

Test results and the Playwright report are written to mounted volumes (playwright-report/, test-results/), so you can view the report on your host machine after the container exits:

bunx playwright show-report

The emulators must be running before you execute E2E tests. Start them with bun run emu in a separate terminal and ensure PUBLIC_APP_ENV=development is set in .env.

Getting Started

Architecture

SansiStore Local Development Quickstart Guide

Prerequisites

Setup Steps

Running Tests

Build docs developers (and LLMs) love

Getting Started

Architecture

Documentation Index

​Prerequisites

​Setup Steps

​Running Tests

Build docs developers (and LLMs) love

Prerequisites

Setup Steps

Running Tests