Getting Started

Configuration

Configure your build tools and environment for Hydra SDK

Hydra SDK leverages WebAssembly (WASM) for high-performance Cardano operations. This guide covers how to configure your build tools and environment for optimal performance.

Full Examples

For complete working examples with full configuration, check out our examples repository:

React + Vite Example - Complete React application setup
Vue.js + TypeScript Example - Complete Vue.js application setup
Examples Repository - All examples on GitHub

Nuxt 3

For Nuxt.js projects, configure your nuxt.config.ts:

import wasm from 'vite-plugin-wasm'
import topLevelAwait from 'vite-plugin-top-level-await'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

export default defineNuxtConfig({
  ssr: false, // Disable SSR for wallet applications
  
  vite: {
    plugins: [
      wasm(),
      topLevelAwait(),
      nodePolyfills({
        include: ['buffer'],
        globals: {
          Buffer: true,
          global: false,
          process: false
        }
      })
    ],
    optimizeDeps: {
      exclude: ['@hydra-sdk/cardano-wasm']
    }
  }
})

Vue.js with Vite

Configure your vite.config.js for Vue projects:

💡 See the complete Vue.js example for a full working setup.

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import wasm from 'vite-plugin-wasm'
import topLevelAwait from 'vite-plugin-top-level-await'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

export default defineConfig({
  plugins: [
    vue(),
    wasm(),
    topLevelAwait(),
    nodePolyfills({
      include: ['buffer'],
      globals: {
        Buffer: true,
        global: false,
        process: false
      }
    })
  ],
  optimizeDeps: {
    exclude: ['@hydra-sdk/cardano-wasm']
  }
})

React with Vite

For React projects using Vite, update your vite.config.js:

💡 See the complete React example for a full working setup.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import wasm from 'vite-plugin-wasm'
import topLevelAwait from 'vite-plugin-top-level-await'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

export default defineConfig({
  plugins: [
    react(),
    wasm(),
    topLevelAwait(),
    nodePolyfills({
      include: ['buffer'],
      globals: {
        Buffer: true,
        global: false,
        process: false
      }
    })
  ],
  optimizeDeps: {
    exclude: ['@hydra-sdk/cardano-wasm']
  }
})

Excluding more than `cardano-wasm`

The Vite configs above exclude only @hydra-sdk/cardano-wasm from dependency pre-bundling. It is a wasm-bindgen module that needs vite-plugin-wasm and vite-plugin-top-level-await, so Vite cannot pre-bundle it.

If you also exclude @hydra-sdk/core or @hydra-sdk/transaction, the dev server returns a 500 on any route that imports the SDK:

The requested module '/_nuxt/@fs/.../@harmoniclabs/uplc/dist/index.js'
does not provide an export named 'Application'

An excluded package is served raw, so Vite follows its imports down to @harmoniclabs/uplc. That package is CommonJS, and because it is only reachable through an excluded package, Vite never pre-bundles it either — it is served as CJS-as-ESM, which exposes no analyzable named exports.

Force-include the leaf dependencies so Vite pre-bundles them with CJS→ESM interop. In a pnpm workspace, bare specifiers do not resolve from the app root, so use the nested importer > dep syntax:

optimizeDeps: {
  exclude: ['@hydra-sdk/cardano-wasm', '@hydra-sdk/core', '@hydra-sdk/transaction'],
  include: [
    '@hydra-sdk/core > @harmoniclabs/uplc',
    '@hydra-sdk/core > @harmoniclabs/plutus-data',
    '@hydra-sdk/core > @scure/base',
    '@hydra-sdk/core > axios',
    '@hydra-sdk/core > bip39',
    '@hydra-sdk/core > cbor-x'
  ]
}

Then restart the dev server with the caches cleared:

rm -rf node_modules/.cache/vite .nuxt/cache

Clearing the cache on its own does not fix this. The error follows deterministically from the exclude + CommonJS combination, so it returns on the next dependency-optimization pass.

If a new does not provide an export named … error appears for a different CommonJS dependency, add @hydra-sdk/core > <that-package> to the include list.

Next.js Configuration

Configure Next.js in your next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.experiments = {
        ...config.experiments,
        asyncWebAssembly: true,
      }
      
      config.resolve.fallback = {
        ...config.resolve.fallback,
        crypto: false,
        stream: false,
        util: false,
        buffer: require.resolve('buffer')
      }
    }
    
    return config
  },
  
  // Disable static optimization for wallet pages
  experimental: {
    esmExternals: 'loose'
  }
}

module.exports = nextConfig

For Next.js 13+ with app directory, also create a globals.d.ts:

declare global {
  var Buffer: typeof import('buffer').Buffer
}

export {}

Quick Start

Build your first Cardano wallet application with Hydra SDK

Guides

Task-oriented, step-by-step guides for building Cardano wallet apps with Hydra SDK.