Skip to content

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+.

bash
npm create fedimint-app
bash
yarn create fedimint-app
bash
pnpm create fedimint-app
bash
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:

bash
npm create fedimint-app@latest my-fedimint-app -- --template vite-react-ts
bash
yarn create fedimint-app my-fedimint-app --template vite-react-ts
bash
pnpm create fedimint-app my-fedimint-app --template vite-react-ts
bash
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:

bash
npm install @fedimint/core-web
bash
yarn add @fedimint/core-web
bash
pnpm add @fedimint/core-web
bash
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:

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.

ts
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.

bash
# Required
npm i vite-plugin-wasm

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

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

# Typically not needed, but may be required in some projects.
pnpm add vite-plugin-top-level-await
bash
# 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:

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:

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


To learn more about Web SDK, explore the docs