Development Server Setup

This guide explains how to set up and run the Alviere UI Svelte development server.

Prerequisites

• Node.js 22+ and pnpm installed
• Alviere API credentials (client ID, client secret, and an account UUID that shoudl represent a Payee)

Quick Start

1. Create Environment File

Copy the example environment file and fill in your credentials:

cd packages/ui
cp .env.example .env

2. Add Your Credentials

Edit .env and add your Alviere API credentials:

ALVIERE_CLIENT_ID=your-client-id-here
ALVIERE_CLIENT_SECRET=your-client-secret-here
ALVIERE_ACCOUNT_UUID=your-account-uuid-here

⚠️ IMPORTANT: Never commit the .env file to version control! It contains sensitive credentials.

3. Start the Development Server

# From the ui package directory
pnpm run dev:server

# Or from the monorepo root
pnpm --filter @alviere/ui dev:server

The development server will start on http://localhost:8000

Available Scripts

• pnpm run dev:server - Start the Express development server
• pnpm run dev - Start Vite development server (for component development)
• pnpm run a11y:all - Run the full local accessibility audit toolchain
• pnpm run a11y:report:generate - Generate consolidated auditor-facing a11y report (HTML/MD/JSON)

Accessibility Audits (WCAG/508)

For VPAT/Section 508 evidence generation, use the local accessibility audit pipeline documented in:

• test/README.md

This includes:

• Component-level axe checks (vitest-axe)
• Browser-level axe audits (Playwright)
• Page-level WCAG checks (pa11y-ci)
• Lighthouse accessibility assertions and reports

For more information on how the dev server is setup see here

Environment Variables

| Variable | Required | Default | Description | | ----------------------- | -------- | ------------------------------------- | ------------------------------- | | ALVIERE_CLIENT_ID | ✅ Yes | - | Your Alviere API client ID | | ALVIERE_CLIENT_SECRET | ✅ Yes | - | Your Alviere API client secret | | ALVIERE_ACCOUNT_UUID | ✅ Yes | - | Your Alviere account UUID | | ALVIERE_AUTH_URL | No | https://api.dev.alviere.com/v3/auth | Alviere authentication endpoint | | PORT | No | 8000 | Development server port |

⚠️ IMPORTANT: Bear in mind that all subsquent requests will be made to the same environment the auth was made, since, behind the curtains the CORE package will use the key api_domain retrieved from the auth JWT.

Getting Credentials

To get your Alviere API credentials:

1. Get in touch with your contact point from Alviere to get the Client_ID, Client_Secret and Starting Account UUID (If you don't have one already)

Troubleshooting

"Missing required environment variables" error

If you see this error, make sure:

1. You've created a .env file in packages/ui/
2. All three required variables are set in the .env file
3. The .env file has no typos in variable names

Server won't start

• Check that port 8000 is not already in use
• Try setting a different port: PORT=3000 pnpm run dev:server
• Ensure you've run pnpm install in the workspace root

⚠️ IMPORTANT: Bear in mind that port 8000 is CORS cleared, other ports might not be and if you really need a different port you'll need to contact Alviere as this needs a case-by-case decision and it's based on necessity.

Security Notes

• The .env file is already in .gitignore and will not be committed
• Never share your credentials publicly or in code repositories
• Use different credentials for development, staging, and production environments
• Rotate credentials regularly and if they're ever exposed