Aspera file browsing and transfer application built with React, TypeScript, Vite, IBM Carbon Design System and the Aspera Web SDK.
Merci @m67hoff for the inspiration!
And merci IBM Bob for the vide coding.
- File Navigation: Browse directories with breadcrumb navigation
- Two Display Modes: Traditional list view or modern card view
- Drag & Drop: Upload files by drag and drop
- Transfer Management: Track your downloads and uploads in real-time
- Multiple Connection Types: Aspera Node API (node-user, access-key) and SSH/SFTP via
ascmd - Internationalization: Multi-language support (9 languages) with i18next
- Modern Interface: Uses IBM Carbon Design System for consistent UX
- TypeScript: Fully typed code for better maintainability
- React 19 with TypeScript
- Vite 8 - Ultra-fast build tool
- IBM Carbon Design System - UI Components
- i18next + react-i18next - Internationalization
- Zustand - Simple and performant state management
- TanStack Query - Server data management
- TanStack Router - Type-safe routing
- React Hook Form + Zod - Forms and validation
- Axios - HTTP requests
- date-fns - Date manipulation
- openapi-typescript - Type-safe API client generation
- Aspera Web SDK - File transfer integration
# Install dependencies
npm install
# Install SSH proxy backend dependencies
cd server && npm install && cd ..
# Start both Vite dev server and SSH proxy backend (port 3000 + 3001)
npm run dev
# Start only the Vite frontend (no SSH support)
npm run dev:vite
# Start only the SSH proxy backend
npm run dev:ssh
# Build for production
npm run build
# Preview production build
npm run preview
# Generate API types from OpenAPI spec
npm run generate:api-typesNote: SSH/SFTP connections require
ascmdto be installed on the remote Aspera HSTS server (it is part of the standard Aspera HSTS installation). The SSH proxy backend runs locally on port3001and is proxied through Vite at/api/ssh.
The application can be deployed for free on GitHub Pages:
# Deployment is automatic via GitHub Actions
# Each push to main branch triggers build and deployment
# To test the GitHub Pages build locally:
npm run build:gh-pages
npm run preview:gh-pagesRequired configuration:
- Enable GitHub Pages in repository settings (Settings > Pages)
- Select "GitHub Actions" as the source
- The
.github/workflows/deploy.ymlworkflow will run automatically
Deployment URL: https://<username>.github.io/aspera-browser-react/
# Build the Docker image
./scripts/build.sh v1.0.0
# Run with Docker
docker run -d -p 8080:80 aspera-browser:v1.0.0
# Or with Docker Compose
docker compose up -d# Deploy on Kubernetes
./scripts/deploy.sh production
# Or manually
kubectl apply -k k8s/ -n aspera-browserFor more details, see the Deployment Guide.
server/
βββ ascmd.js # TLV protocol implementation (ported from Go) + SSH connection factory
βββ index.js # Express backend β exposes /api/ssh/* routes
βββ package.json # Backend dependencies (express, ssh2)
src/
βββ components/
β βββ common/ # Reusable components (Breadcrumb, LanguageSwitcher, etc.)
β βββ file-browser/ # File navigation components
β βββ transfer/ # Transfer management panel
β βββ layout/ # Main application layout
βββ i18n/ # i18next configuration
βββ locales/ # Translation files (en, fr, de, es, ja, pt, ru, zh, ar)
β βββ en/ # English translations
β βββ fr/ # French translations
β βββ ... # Other languages
βββ services/
β βββ SSHService.ts # SSH/SFTP client (calls /api/ssh/* backend)
β βββ NodeUserService.ts # Aspera Node API β node-user auth
β βββ AccessKeyService.ts # Aspera Node API β access-key auth
β βββ FileServiceFactory.ts # Selects the right service from credentials
β βββ IFileService.ts # Common interface
βββ stores/ # Zustand stores (auth, files, transfers)
βββ types/ # TypeScript types and auto-generated API types
βββ utils/ # Utilities (formatters, etc.)
βββ App.tsx # Main component
βββ main.tsx # Entry point
The application supports three connection types, selectable in the login interface:
| Type | Description | Required fields |
|---|---|---|
node-user |
Aspera Node API with username/password | URL, username, password |
access-key |
Aspera Node API with access key | URL, access key ID, secret |
ssh |
SSH/SFTP via ascmd on the remote server |
ssh://host:port, username, password or private key |
The page can be opened with an account to pre-fill, for example by ascli node asperabrowser (IBM Aspera CLI):
https://laurent-martin.github.io/aspera-browser-react/#goto=<text>
<text> is a JSON object {"nodeURL":"https://...","nodeUser":"...","nodePW":"..."} (nodePW is optional) that is compressed (zlib deflate), encoded in Base64 URL-safe without padding, then reversed. It is not encrypted.
The account form opens pre-filled (type node-user): nothing is saved or connected until the user validates it.
Put it in the fragment (#goto=), not in the query (?goto=, accepted too): a browser never sends the fragment to the web server, so the password does not reach it or its logs.
The parameter is removed from the address bar once it is read.
The SSH proxy backend listens on port 3001 by default. Override with:
SSH_PROXY_PORT=4000 npm run devThe application uses a type-safe API client generated from the official IBM Aspera Node API OpenAPI specification (v4.4.6).
- Type-safe API calls: All API methods are fully typed with TypeScript
- Auto-generated types: Types are generated from the official OpenAPI spec
- Error handling: Custom error class with detailed error information
- Easy regeneration: Update types with a single command
- Table with columns: Type, Name, Size, Modified Date
- Sort by column
- Multiple selection with checkboxes
- Integrated search
- Responsive grid display
- Visual icons for files and folders
- Selection by checkbox
- Compact information
The application supports multiple languages using i18next:
- π¬π§ English (default)
- π«π· French
- π©πͺ German
- πͺπΈ Spanish
- π΅πΉ Portuguese
- π·πΊ Russian
- π¨π³ Chinese
- π―π΅ Japanese
- πΈπ¦ Arabic
Language is automatically detected from browser settings and can be changed using the language switcher component.
SSH connections cannot be made directly from a browser. This application uses a local Node.js proxy backend (server/) that:
- Receives HTTP
POSTrequests from the React frontend (/api/ssh/*) - Opens an SSH connection to the remote Aspera HSTS server
- Executes
ascmdβ the Aspera file-system command agent β over SSH - Speaks the binary TLV protocol to list files, create directories, rename, delete, etc.
- Returns JSON responses to the frontend
# From the project root
npm run dev:ssh
# Or standalone (e.g. on a separate machine)
cd server && npm install && npm startNote
The default port is 3001. Override it with the SSH_PROXY_PORT environment variable:
SSH_PROXY_PORT=4000 npm run dev:ssh
The proxy can run on any machine reachable from the browser β it does not need to be on the same host as the React app.
When creating or editing an SSH account, the "SSH Proxy Backend URL" field controls which proxy the frontend calls.
| Situation | What to enter |
|---|---|
Local dev (npm run dev) |
Leave empty β auto-detected as http://localhost:3001 |
| Remote proxy (e.g. deployed server) | Full URL, e.g. https://proxy.mycompany.com |
| GitHub Pages with external proxy | Full URL with CORS enabled on the proxy |
Auto-detection rule: when the app runs on
localhost, the proxy URL defaults tohttp://localhost:3001. On any other hostname the frontend uses the relative path/api/ssh(works when the proxy is co-hosted behind the same reverse proxy).
If the SSH proxy runs on a different origin than the React app (e.g. GitHub Pages + remote proxy),
restrict CORS to that origin using the ALLOWED_ORIGIN environment variable:
ALLOWED_ORIGIN=https://<username>.github.io node index.jsBy default (ALLOWED_ORIGIN unset) the proxy accepts requests from any origin.
| Route | Description |
|---|---|
POST /api/ssh/info |
Get platform info |
POST /api/ssh/browse |
List directory contents |
POST /api/ssh/mkdir |
Create a directory |
POST /api/ssh/delete |
Delete files or directories |
POST /api/ssh/rename |
Rename / move |
POST /api/ssh/stat |
Get file metadata |
POST /api/ssh/download-setup |
Verify paths before download |
POST /api/ssh/upload-setup |
Verify destination before upload |
The application is ready for production deployment with:
- Docker: Optimized multi-stage image with Nginx
- Kubernetes: Complete manifests (Deployment, Service, Ingress, ConfigMap)
- Kubernetes Operator: Structure for a custom operator (coming soon)
- Automated scripts: Simplified build and deployment
See the Deployment Guide for more details.
- Full integration with Aspera Web SDK for transfers
- File deletion implementation
- Folder creation implementation
- File upload (drag & drop)
- File download
- Media viewer (images, videos, audio)
- Video streaming support
- Enhanced error handling
- Unit and E2E tests
- Multi-language support (9 languages)
- Docker containerization
- Kubernetes deployment manifests
- Kubernetes operator implementation
- Dark mode
- SSH/SFTP support
- Access key authentication
- Node user authentication
Apache-2.0
This project uses the latest React 2026 development practices:
- TypeScript strict mode
- ESLint for code quality
- Prettier for formatting
- Vite for ultra-fast builds
- Instant Hot Module Replacement (HMR)
Contributions are welcome! Feel free to open an issue or pull request.