https://github.com/hyperlane-xyz/hyperlane-warp-ui-template
A web app template for building Hyperlane Warp Route UIs
https://github.com/hyperlane-xyz/hyperlane-warp-ui-template
hyperlane interchain route template warp
Last synced: 3 months ago
JSON representation
A web app template for building Hyperlane Warp Route UIs
- Host: GitHub
- URL: https://github.com/hyperlane-xyz/hyperlane-warp-ui-template
- Owner: hyperlane-xyz
- License: other
- Created: 2022-12-04T16:49:36.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-04-02T15:27:41.000Z (3 months ago)
- Last Synced: 2026-04-03T23:47:08.328Z (3 months ago)
- Topics: hyperlane, interchain, route, template, warp
- Language: TypeScript
- Homepage: https://hyperlane-warp-template.vercel.app
- Size: 29 MB
- Stars: 184
- Watchers: 20
- Forks: 204
- Open Issues: 76
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Hyperlane Warp Route UI Template
This repo contains an example web interface for interchain tokens built with [Hyperlane Warp Route](https://docs.hyperlane.xyz/docs/reference/applications/warp-routes). Warp is a framework to permissionlessly bridge tokens to any chain.
## Architecture
This app is built with Next & React, Wagmi, RainbowKit, and the Hyperlane SDK.
- Constants that you may want to change are in `./src/consts/`, see the following Customization section for details.
- The index page is located at `./src/pages/index.tsx`
- The primary features are implemented in `./src/features/`
## Customization
See [CUSTOMIZE.md](./CUSTOMIZE.md) for details about adjusting the tokens and branding of this app.
## Development
### Setup
#### Configure
You need a `projectId` from the WalletConnect Cloud to run the Hyperlane Warp Route UI. Sign up to [WalletConnect Cloud](https://cloud.walletconnect.com) to create a new project.
#### Build
```sh
# Install dependencies
pnpm install
# Build Next project
pnpm run build
```
### Run
You can add `.env.local` file next to `.env.example` where you set `projectId` copied from WalletConnect Cloud.
```sh
# Start the Next dev server
pnpm run dev
# Or with a custom projectId
NEXT_PUBLIC_WALLET_CONNECT_ID= pnpm run dev
```
### Test
```sh
# Run unit tests
pnpm test
# Run E2E tests (reuses running dev server, or starts one via Playwright)
pnpm test:e2e
# Run E2E tests with headed browser and slow motion for debugging
SLOW_MO=2000 pnpm test:e2e --headed --workers=1
# Run a single E2E test file with headed browser
SLOW_MO=2000 pnpm test:e2e --headed --workers=1 tests/wallet-connect/protocol-wallet-modals.spec.ts
# Lint check code
pnpm run lint
# Check code types
pnpm run typecheck
```
### Format
```sh
# Format code using Prettier
pnpm run prettier
```
### Clean / Reset
```sh
# Delete build artifacts to start fresh
pnpm run clean
```
### Local package linking to hyperlane-monorepo
If you have to make changes to the widgets package to edit e.g. the Connect Button or other components linking
the widgets package locally to test it is necessary. To do that you can run the following commands
```sh
# Link monorepo packages with the warp-ui
pnpm link:monorepo
# Unlink packages again after testing
pnpm unlink:monorepo
```
## Embed Widget
The Warp UI can be embedded as an iframe on any website, giving your users a bridge experience directly in your app.
### Setup
Once deployed (e.g., to Vercel), the embed is available at `/embed`:
```html
```
You can pre-select transfer routes using query params:
```text
/embed?origin=ethereum&destination=arbitrum&originToken=USDC&destinationToken=USDC
```
### Theme Customization
Customize colors via URL params (hex values without `#`):
| Param | Description | Default (light) |
| ------------ | ---------------------------------------------- | --------------- |
| `accent` | Primary/accent color (buttons, headers, links) | `9A0DFF` |
| `bg` | Page background | transparent |
| `card` | Card/surface background | `ffffff` |
| `text` | Text color | `010101` |
| `buttonText` | Button text color | `ffffff` |
| `border` | Border color | `BFBFBF40` |
| `error` | Error state color | `dc2626` |
| `mode` | `dark` or `light` — applies preset defaults | `light` |
**Examples:**
```html
```
### PostMessage Events
The embed page sends events to the parent window via `postMessage`:
```js
window.addEventListener('message', (event) => {
if (event.data?.type !== 'hyperlane-warp-widget') return;
const { type, payload } = event.data.event;
if (type === 'ready') {
console.log('Widget ready at', payload.timestamp);
}
});
```
### Solving CSP Issues
If your site has a Content Security Policy that blocks iframes, you'll need to allow the Warp UI origin in your CSP `frame-src` directive:
```text
Content-Security-Policy: frame-src https://your-warp-ui-domain.com;
```
For sites where you can't modify CSP headers (e.g., WordPress, Shopify), check if the platform has an iframe allowlist setting, or use a reverse proxy to serve the embed from your own domain.
If you self-host the Warp UI and want to restrict which sites can embed it, set the `NEXT_PUBLIC_EMBED_ALLOWED_ORIGINS` environment variable:
```text
NEXT_PUBLIC_EMBED_ALLOWED_ORIGINS=https://app-a.com https://app-b.com
```
If not set, any site can embed the widget (default: `*`).
## Deployment
The easiest hosting solution for this Next.JS app is to create a project on Vercel.
## Learn more
For more information, see the [Hyperlane documentation](https://docs.hyperlane.xyz/docs/protocol/warp-routes/warp-routes-overview).