@twobitedd/ergo-dapp-kit

React helpers for Ergo browser dApps: Dynamic.xyz bootstrap, Nautilus (EIP-12) wallet connector, ErgoWalletProvider / ErgoDynamicProvider, Explorer-backed balances, and token metadata normalization.

Performance-minded usage

• sideEffects: false — Bundlers can tree-shake unused exports when you import explicitly.
• Wallet balance token rows: REACT_APP_WALLET_FULL_TOKEN_DETAIL (or NEXT_PUBLIC_WALLET_FULL_TOKEN_DETAIL). Defaults on (full NFT/metadata enrichment). Set false to skip extra Explorer HTTP calls — recommended for animation-heavy apps / busy wallets.
• Prefer narrow entrypoints so your app does not pull in React/Dynamic code paths it never uses:
  • @twobitedd/ergo-dapp-kit/env — env parsing only (no React).
  • @twobitedd/ergo-dapp-kit/branding — Dynamic widget styling helpers (React hooks live here).
  • @twobitedd/ergo-dapp-kit/explorer — read-only Explorer HTTP helpers (no wallet UI).
  • @twobitedd/ergo-dapp-kit/eip12 — formatting + bare EIP-12 / window helpers (no React).

Import the main package only where you need ErgoWalletProvider, ErgoDynamicProvider, or NautilusWalletConnectors.

Create React App (CRA / webpack 5)

CRA resolves ES modules strictly (fullySpecified). Mirror craco.config.js from ergo-basic-template:

1. resolve.fullySpecified: false for paths matching .../node_modules/@twobitedd/ergo-dapp-kit/dist/.
2. Jest transformIgnorePatterns allowlist for @twobitedd and moduleNameMapper for subpaths @twobitedd/ergo-dapp-kit/env → dist/env.js, branding → dist/branding.js, explorer → dist/explorer.js if tests import those entrypoints.

TypeScript: CRA keeps "moduleResolution": "node" by default. This package sets package.json → typesVersions so subpath imports like @twobitedd/ergo-dapp-kit/env resolve to dist/*.d.ts without forcing bundler / nodenext in tsconfig.json.

Also enable legacy-peer-deps (CRA / react-scripts vs TypeScript 5 peer quirks): .npmrc with legacy-peer-deps=true or pass npm install --legacy-peer-deps.

Install

npm install @twobitedd/ergo-dapp-kit

Peers: @dynamic-labs/sdk-react-core, @dynamic-labs/ethereum, @dynamic-labs/wallet-connector-core, @dynamic-labs/types, react, react-dom.

Git & GitHub

This folder is its own git repo (ergo-dapp-kit/.git/).

Push code (remote empty)

From ergo-dapp-kit/:

git remote add origin https://github.com/twobitEDD/ergo-dapp-kit.git
git push -u origin main

(Skip git remote add if origin already exists — check with git remote -v.)

Push rejected? (“non-fast-forward” / “unrelated histories”)

If GitHub created the repo with “Add a README” (or .gitignore / license), the remote already has commits your laptop doesn’t have. Merge once, then push:

git remote add origin https://github.com/twobitEDD/ergo-dapp-kit.git   # if needed
git fetch origin
git pull origin main --allow-unrelated-histories --no-edit
git push -u origin main

Resolve conflicts only if Git prompts you (often README-only).

npm publish fails separately from Git

Publishing goes to registry.npmjs.org, not GitHub. Typical fixes:

| Error | What to do | |--------|------------| | 403 Forbidden / you must verify email | npm login, verify npm email, ensure token/account may publish @twobitedd | | cannot publish over existing version | Bump version in package.json (e.g. 0.1.3), commit, then npm publish | | 404 scope / organization | On npm, scoped packages under @twobitedd must be tied to your user/org |

GitHub repo creation alone never blocks npm publish; only npm auth and version collisions do.

Ignored by git: node_modules/, dist/, *.tgz. After clone run npm ci — prepare builds dist/.

Scripts

| Script | Purpose | |--------|---------| | npm run build | Emit dist/ | | npm run test | Vitest | | npm run pack:check | npm pack --dry-run ( tarball sanity ) |

prepublishOnly runs tests then build before publish.

First npm release (maintainers)

Copy-paste checklist: docs/RELEASE.md (npm login → npm publish --access public).

GitHub Actions: add repo secret NPM_TOKEN. Then:

• .github/workflows/ci.yml — test + build on PR/main
• .github/workflows/publish.yml — manual run or push tag v*.*.* (matches package.json version)

After publish, consumers use "@twobitedd/ergo-dapp-kit": "^0.1.2" (or your bumped semver).

Mirror into ERGnomes monorepo

If you maintain both repos: push standalone tags/releases here; optionally subtree-merge or copy dist-published artefact only—the canonical npm identity is @twobitedd/ergo-dapp-kit.

Repository

• Source: github.com/twobitEDD/ergo-dapp-kit

License

MIT