XRPL Explorer

The explorer uses RouteDefinition to provide type safety for route parameters. A RouteDefinition object defines the URL path and uses a generic type to specify the expected shape of the parameters. This definition is then used by useRouteParams and RouteLink to ensure parameter names and types are correct at compile time.

export const ACCOUNT_ROUTE: RouteDefinition<{
    id?: string
    tab?: 'assets' | 'transactions'
    assetType?: 'issued' | 'nfts'
}> = {
    path: '/accounts/:id?/:tab?/:assetType?',
}

To support a new language in the XRPL Explorer, follow these steps:

1. Register the language: Add the new language code and its corresponding language name to the supportedLanguages map located in src/i18n/baseConfig.ts.
2. Create the directory: Create a new folder inside public/locales/ named after the language code (e.g., ja-JP).
3. Create the translation file: Add a file named translations.json inside your new language folder.
4. Populate translations: Translate all entries in the JSON file. If you want the application to fall back to the English version for a specific key, set its value to null.

/* Example structure for public/locales/ja-JP/translations.json */
{
  "key_name": "日本語の翻訳",
  "another_key": null
}

When implementing or debugging analytics in the explorer, follow these techniques:

• Data Availability: Use the screen_view event only once the required data is available. For example, on a transaction page, wait until the transaction data is successfully retrieved before sending the event. This ensures you can include properties like transactionType in the same event rather than sending one event for the page visit and a second one for the data.
• Page Views: Send the entire URL path for page view events; specific details can be parsed from the path during post-processing.
• Debugging: Use the Adswerve browser plugin to debug analytics events.
• Environment Usage: It is acceptable to use the production tracking ID on all servers, including local, dev, and staging. Data can be filtered or trimmed on the Google Analytics side.

When modifying existing strings in en-US/translations.json, follow these rules to maintain localization quality:

• Minor changes: If the meaning of the string does not change materially (e.g., adding a small clarification like "Please check your transaction hash" $\rightarrow$ "Please check your transaction hash or CTID"), you can leave the existing translations in other language files as they are.
• Meaningful changes: If the entry's meaning changes significantly, you must set the value to null in all other translations.json files.

Note: Setting a value to null triggers a fallback to the English version and serves as a signal to language contributors that a new localization is required.

To enable analytics, you must install Google Tag Manager by adding two snippets to your application.

1. Paste the main script as high in the <head> of the page as possible.
2. Paste the <noscript> snippet immediately after the opening <body> tag.

<!-- Google Tag Manager (Head) -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;
f.parentNode.insertBefore(j,f);})
(window,document,'script','dataLayer','GTM-KCQZ3L8');</script>

<!-- Google Tag Manager (Body) -->
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-KCQZ3L8"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>

When adding a new string to the application, you must ensure all supported languages are updated to prevent missing keys:

1. Create the new entry in the base English file: en-US/translations.json.
2. Add the same key to every other translations.json file in the public/locales/ directory.
3. Set the value for these new keys to null in the non-English files. This ensures the application defaults to the English version instead of failing to find the key.

Use the following commands to manage the test suite:

• Watch mode: npm test
• Coverage report: npm run test:coverage
• View coverage: After running coverage, open coverage/index.html in your browser.

Debugging in Chrome

To debug a specific unit test using Chrome Developer Tools:

1. Insert a debugger; statement in your test code.
2. Run npm run test:debug.
3. Open about:inspect in Chrome.
4. Click the inspect link for the target process.
5. Click the play button in Chrome DevTools to start execution; the test will pause at your debugger; statement.

To set up the XRPL Explorer locally, ensure you have Node.js 22 and npm 8+ installed. Follow these steps:

1. Install dependencies: npm install
2. Configure environment: Copy the example environment file: cp .env.example .env
3. Run in development mode: npm start
4. Run in production mode: Build the project first, then start the production server: npm run build followed by npm run prod-server.

# Development mode
npm install
cp .env.example .env
npm start

# Production mode
npm install
cp .env.example .env
npm run build
npm run prod-server

The server follows this request handling order:

1. Compression: Responses are compressed using compression().
2. JSON Parsing: Requests with JSON bodies are parsed via bodyParser.json().
3. Static Files: Files from the /../build directory are served.
   • .html files are served with Cache-Control: no-cache.
   • Versioned files (matching the pattern .[0-9a-f]{20}.) are served with Cache-Control: max-age=31536000 (1 year).
4. API Routes: All requests starting with /api/v1 are routed to the API handlers.
5. Production SPA Fallback: If NODE_ENV is set to production, any request that does not match an API route or a static file is served the index.html file to support client-side routing.
6. 404 Error: If no routes match and it is not in production mode, the server returns a 404 status with { "error": "route not found" }.

To run the explorer against a network other than the live net, modify your .env file with the following settings:

Testnet mode

• Set VITE_RIPPLED_HOST=s.altnet.rippletest.net
• Set VITE_ENVIRONMENT=testnet (enables the TESTNET banner)

Devnet mode

• Set VITE_RIPPLED_HOST=s.devnet.rippletest.net
• Set VITE_ENVIRONMENT=devnet (enables the TESTNET banner)

# Testnet configuration
VITE_RIPPLED_HOST=s.altnet.rippletest.net
VITE_ENVIRONMENT=testnet

# Devnet configuration
VITE_RIPPLED_HOST=s.devnet.rippletest.net
VITE_ENVIRONMENT=devnet