AWallet Algorand Development

Expert instructions for developing AWallet, a Vue 3-based cryptocurrency wallet for the Algorand blockchain. This skill provides comprehensive guidance for building, testing, and deploying the application with proper timing expectations and validation procedures.

Overview

AWallet is built with Vue 3, TypeScript, Vue CLI, and PrimeVue components. The application is packaged as both a web application and deployed via Docker/Kubernetes.

**Always reference these instructions first and fallback to search or bash commands only when encountering unexpected information.**

Bootstrap and Build Process

Installation

Execute: `CYPRESS_INSTALL_BINARY=0 npm install`

**CRITICAL**: Set timeout to 600+ seconds minimum

Installation takes 20-30 seconds

**NEVER CANCEL** this operation

The `CYPRESS_INSTALL_BINARY=0` flag skips Cypress binary download (which often fails due to network restrictions)

Expected warnings about deprecated packages are normal and acceptable

Production Build

Execute: `npm run build`

**CRITICAL**: Set timeout to 180+ seconds minimum

Build takes 65-70 seconds

**NEVER CANCEL** this operation

Outputs production files to `dist/` directory

Includes multiple PrimeVue theme files and assets

Shows webpack compilation warnings but builds successfully

Build Output Validation

After building, verify `dist/` directory contains:

`index.html` (main entry point)

`js/` directory with compiled JavaScript bundles

`css/` directory with compiled CSS

`themes/` directory with PrimeVue theme files

Static assets (fonts, images, manifest files)

Development Server

Execute: `npm run serve`

**CRITICAL**: Set timeout to 180+ seconds minimum

Initial compilation takes 80-90 seconds

**NEVER CANCEL** this operation

Runs on `http://localhost:8080` by default

Includes hot module replacement

Shows TypeScript and ESLint warnings but runs successfully

Wait for "App running at: Local: http://localhost:8080/" message indicating readiness

Production Server

1. Build first: `npm run build`

2. Serve production build: `npm run server`

- **CRITICAL**: Set timeout to 30+ seconds minimum

- Command appears to hang but works correctly - this is normal

- **NEVER CANCEL** this operation

- Uses browser-sync to serve from `dist/` directory

- Runs on port 8080

- Access via `http://localhost:8080`

Code Quality and Linting

Execute: `npm run lint`

Expected timing: 5-6 seconds

Shows many warnings (83) and some errors (20) - this is expected

Vue template HTML structure warnings are expected

ESLint errors in `vue.config.js` due to obfuscated code are expected

Exit code 1 is normal due to ESLint errors

Localization Management

Master File

`src/locales/en.json` is the source of truth for all localization keys.

Synchronization Rules

All other locale files (`af.json`, `cs.json`, `es.json`, `hu.json`, `it.json`, `nl.json`, `ru.json`, `sk.json`, `tr.json`) **MUST** have:

- The exact same keys as `en.json`

- In the exact same order as `en.json`

Adding Translations

If a key is missing in a target locale, add it

If a translation is not available, use the English value as a placeholder or attempt a translation

Ensure all JSON files use 2-space indentation and have a newline at the end

Testing Strategy

Cypress E2E Tests

**WARNING**: Cypress binary installation often fails due to network restrictions.

`npm run test` - Will fail without Cypress binary

Error message: "The cypress npm package is installed, but the Cypress binary is missing"

Do **NOT** attempt to install Cypress binary unless you have confirmed network access

Alternative commands (require binary):

- `npm run test:open` - Opens Cypress UI

- `npm run test1` - Runs specific test

Manual Validation Scenarios

**ALWAYS** perform these validation steps after making changes:

#### 1. Wallet Creation Flow

Navigate to homepage (shows wallet creation form)

Enter wallet name and password (12+ characters recommended)

Click "Create wallet"

Verify redirect to accounts page (`/accounts`)

Confirm wallet appears in dropdown on homepage after creation

#### 2. Account Creation Flow

From accounts page, click "Create your first account"

Verify mnemonic phrase generation (`/new-account/ed25519`)

Check that account address is generated

Verify buttons for mnemonic validation are present

#### 3. Navigation Testing

Test main navigation: Wallet, Payment gateway, Network selection (Mainnet), Theme switcher

Verify all menu items are accessible

Check responsive behavior

#### 4. Theme Switching

Click Theme dropdown in navigation

Select a different theme (e.g., switch from dark to light)

Verify theme changes are applied correctly (colors, styling)

Check that theme selection persists across page refreshes

#### 5. Language Support

Test flag-based language selector at bottom of page

Verify text changes for supported languages (if applicable)

#### 6. Wallet Management

Verify wallet dropdown shows created wallets

Test wallet selection and password entry form

Confirm wallet password field validation

Application URLs

Development URLs (`npm run serve`)

Main application: `http://localhost:8080/`

Wallet creation: `http://localhost:8080/new-wallet` (auto-redirects if no wallets)

Account creation: `http://localhost:8080/new-account/ed25519`

Accounts overview: `http://localhost:8080/accounts`

Payment gateway: `http://localhost:8080/payment-gateway`

Production URLs (`npm run server`)

Same URL structure as development, served from `dist/`

Docker Deployment

Execute: `cd docker && ./compose.sh`

Uses Node 22 for build stage

Serves via nginx on port 8080

Build process includes `npm ci`, `npm run build`

CI/CD Pipeline

GitHub Actions workflows in `.github/workflows/`:

`gh-pages.yml`: Builds and deploys to GitHub Pages

`awallet-main.yml`: Deploys to private K8S cluster

Build steps: `npm install` → `npm run build` → `npm run test`

**WARNING**: CI tests will fail without Cypress binary access

Key Project Structure

Source Code (`src/`)

`App.vue`: Main application component with gradient background

`main.ts`: Application entry point with PrimeVue setup

`components/`: Reusable Vue components

`pages/`: Application pages/routes

`store/`: Vuex state management modules

`router/`: Vue Router configuration

`locales/`: Internationalization files

Configuration Files

`package.json`: Dependencies and npm scripts

`vue.config.js`: Vue CLI configuration with crypto polyfills

`tsconfig.json`: TypeScript configuration

`cypress.config.ts`: Cypress test configuration

`.eslintrc.js`: ESLint configuration

Common Issues and Workarounds

Cypress Installation Issues

**Problem**: `npm install` fails with Cypress download errors

**Solution**: Use `CYPRESS_INSTALL_BINARY=0 npm install`

**Impact**: E2E tests cannot be run, but application development works normally

TypeScript Version Warnings

**Expected warning**: TypeScript 5.6.3 not officially supported by @typescript-eslint

**Impact**: Does not affect build or runtime functionality

Vue Template Warnings

**Expected warnings**: `<tr> cannot be child of <table>` in TransactionDetail.vue

**Impact**: Does not affect functionality, HTML still renders correctly

Build Cache Issues

**Problem**: Stale browserslist data warnings

**Solution**: Run `npx update-browserslist-db@latest` (optional)

**Impact**: Does not affect build success

Performance Expectations

Dependencies installation: 20-30 seconds

Production build: 65-70 seconds

Development server initial compilation: 80-90 seconds

Production server startup: ~10 seconds (appears to hang but normal)

Application startup after server ready: ~2-3 seconds

Theme switching: Instant

Wallet operations: Near-instant for local operations

Linting: 5-6 seconds

Development Workflow

1. **Setup**: `CYPRESS_INSTALL_BINARY=0 npm install` (wait 20-30 seconds)

2. **Development**: `npm run serve` (wait 80-90 seconds for compilation)

3. **Testing**: Manual validation scenarios (Cypress tests require binary)

4. **Linting**: `npm run lint` before committing

5. **Building**: `npm run build` for production (wait 65-70 seconds)

6. **Validation**: Test wallet creation and navigation flows

Critical Guidelines

**NEVER CANCEL** long-running commands (install, build, serve)

Always wait for builds and compilations to complete

The application has many dependencies and complex webpack configuration requiring adequate time to process

Set appropriate timeouts (600s for install, 180s for build/serve, 30s for server)

Commands that appear to hang are often working correctly - be patient

AWallet Algorand Development

AWallet Algorand Development

Overview

Bootstrap and Build Process

Installation

Production Build

Build Output Validation

Development Server

Production Server

Code Quality and Linting

Localization Management

Master File

Synchronization Rules

Adding Translations

Testing Strategy

Cypress E2E Tests

Manual Validation Scenarios

Application URLs

Development URLs (`npm run serve`)

Production URLs (`npm run server`)

Docker Deployment

CI/CD Pipeline

Key Project Structure

Source Code (`src/`)

Configuration Files

Common Issues and Workarounds

Cypress Installation Issues

TypeScript Version Warnings

Vue Template Warnings

Build Cache Issues

Performance Expectations

Development Workflow

Critical Guidelines

Reviews (0)