Getting Started

Disclaimer

This is very new. Use with caution. Report bugs.

APIs may change.

Scaffolding your first project

Compatibility Note

Most create-fedimint-app templates require Node.js version 18+ or 20+.

npm

npm create fedimint-app

yarn

yarn create fedimint-app

pnpm

pnpm create fedimint-app

bun

bun create fedimint-app

Then follow the prompts!

You can also directly specify the project name and the template you want to use via additional command line options. For example, to scaffold a Fedimint + React project, run:

npm

npm create fedimint-app@latest my-fedimint-app -- --template vite-react-ts

yarn

yarn create fedimint-app my-fedimint-app --template vite-react-ts

pnpm

pnpm create fedimint-app my-fedimint-app --template vite-react-ts

bun

bun create fedimint-app my-fedimint-app --template vite-react-ts

See create-fedimint-app for more details on each supported template.

You can use . for the project name to scaffold in the current directory.

Manual Installation

To add @fedimint/core-web to your project, install the package using your preferred package manager:

npm

npm install @fedimint/core-web

yarn

yarn add @fedimint/core-web

pnpm

pnpm add @fedimint/core-web

bun

bun add @fedimint/core-web

Framework Setup

This package relies on a wasm module to be bundled with your application. You will likely need to update your bundler's or framework's configuration to load the wasm file.

See setup guides for some popular choices below. If your tool is not listed or the setup does not work, feel free to open an issue or contribute a guide.

Next.js

Next.js Setup

To use wasm in a Next.js project, you'll need to add the following to your next.config.ts file:

next.config.ts

/** @type {import('next').NextConfig} */

const nextConfig = {

  webpack(config) {
    config.experiments = {
      asyncWebAssembly: true,
      layers: true,
    };
    return config;
  },

};

export default nextConfig;

Check out the nextjs sample app for a full working example.

React

React.js Setup

TODO: Add setup guide for React.js

Will be similar to Next.js setup above... perhaps even simpler.

VanillaJS

VanillaJS Setup

TODO: Add setup guide for vanilla js.

Currently requires modifying the library and utilizing the @fedimint/wasm-web package directly.

See the bare-js sample app for a full working example.

Webpack

Webpack Setup

TODO: Verify this setup still works.

To use wasm in a webpack project, you'll need to modify your webpack configuration file.

webpack.config.js

module.exports = {
  experiments: {
      asyncWebAssembly: true,
      layers: true,
  }
}

Vite

Vite Setup

To use wasm in a vite project, you'll need to install the vite-plugin-wasm plugin.

If you you see errors with top level await, you may need to install the vite-plugin-top-level-await plugin.

npm

# Required
npm i vite-plugin-wasm

# Typically not needed, but may be required in some projects.
npm i vite-plugin-top-level-await

yarn

# Required
yarn add vite-plugin-wasm

# Typically not needed, but may be required in some projects.
yarn add vite-plugin-top-level-await

pnpm

# Required
pnpm add vite-plugin-wasm

# Typically not needed, but may be required in some projects.
pnpm add vite-plugin-top-level-await

bun

# Required
bun add vite-plugin-wasm

# Typically not needed, but may be required in some projects.
bun add vite-plugin-top-level-await

Then update your vite.config.ts file with the following:

vite.config.ts

vite.config.ts

import { defineConfig } from 'vite'
import wasm from 'vite-plugin-wasm'
import topLevelAwait from 'vite-plugin-top-level-await' // Optional

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    wasm(),
    topLevelAwait(), // Optional
  ],

  worker: {
    format: 'es',
    plugins: () => [
      wasm(),
      topLevelAwait(), // Optional
    ],
  },

  optimizeDeps: {
    exclude: ['@fedimint/core-web'],
  },
})

Check out the vite-react sample app for a full working example.

Usage

Here's a basic example of how to use the @fedimint/core-web library:

example.ts

import { FedimintWallet } from '@fedimint/core-web'

// Create the Wallet client
const wallet = new FedimintWallet()

// Open the wallet (should be called once in the application lifecycle)
await wallet.open()

// Join a Federation (if not already open)
if (!wallet.isOpen()) {
  const inviteCode = 'fed11qgqpw9thwvaz7t...'
  await wallet.joinFederation(inviteCode)
}

// Get Wallet Balance
const balance = await wallet.balance.getBalance()

// Subscribe to Balance Updates
const unsubscribe = wallet.balance.subscribeBalance((balance: number) => {
  // notwoslash
  console.log('Updated balance:', balance)
})
// Remember to call unsubscribe() when done

// Receive Ecash Payments
await wallet.mint.redeemEcash('A11qgqpw9thwvaz7t...')

// Create Lightning Invoice
await wallet.lightning.createInvoice(10_000, 'description')

// Pay Lightning Invoice
await wallet.lightning.payInvoice('lnbc...')

Examples

Check out an example app using Vite + React example.

Check out an example app using VanillaJS + HTML.

Resources

For a list of public federations with invite codes, visit Bitcoin Mints.

What's Next?

Check out the Example Projects

• Vite + React
• VanillaJS + HTML example

To learn more about Web SDK, explore the docs

• SDK Overview
• Library Architecture
• API Reference