{"id":13408115,"url":"https://github.com/multiversx/mx-template-dapp","last_synced_at":"2025-10-06T14:04:26.392Z","repository":{"id":37725390,"uuid":"366736596","full_name":"multiversx/mx-template-dapp","owner":"multiversx","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-30T08:21:02.000Z","size":23407,"stargazers_count":70,"open_issues_count":3,"forks_count":79,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-09-30T08:40:47.980Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/multiversx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-05-12T14:05:00.000Z","updated_at":"2025-09-10T07:51:23.000Z","dependencies_parsed_at":"2023-12-21T13:10:32.184Z","dependency_job_id":"58347b94-f856-4ebd-9427-1f8c0f2a3690","html_url":"https://github.com/multiversx/mx-template-dapp","commit_stats":null,"previous_names":[],"tags_count":1,"template":true,"template_full_name":null,"purl":"pkg:github/multiversx/mx-template-dapp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiversx%2Fmx-template-dapp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiversx%2Fmx-template-dapp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiversx%2Fmx-template-dapp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiversx%2Fmx-template-dapp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/multiversx","download_url":"https://codeload.github.com/multiversx/mx-template-dapp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiversx%2Fmx-template-dapp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278621844,"owners_count":26017253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T20:00:50.846Z","updated_at":"2025-10-06T14:04:26.380Z","avatar_url":"https://github.com/multiversx.png","language":"TypeScript","readme":"# @multiversx/template-dapp\n\nThis project was bootstrapped with [Vite](https://vitejs.dev/guide/).\n\nThe **MultiversX dApp Template**, built using [React.js](https://reactjs.org/) and [Typescript](https://www.typescriptlang.org/).\nIt's a basic implementation of [@multiversx/sdk-dapp](https://www.npmjs.com/package/@multiversx/sdk-dapp), providing the basics for MultiversX authentication and TX signing.\n\nSee [Dapp template](https://template-dapp.multiversx.com/) for live demo.\n\n### Tests\n\n[![E2E tests](https://github.com/multiversx/mx-template-dapp/actions/workflows/playwright.yml/badge.svg)](https://github.com/multiversx/mx-template-dapp/actions/workflows/playwright.yml)\n\n## Requirements\n\n- Node.js version 16.20.0+\n- pnpm version 8.19.4+\n\n## Getting Started\n\n### Step 1. Install modules\n\nFrom a terminal, navigate to the project folder and run:\n\n```bash\npnpm install\n```\n\n### Step 2. Running in development mode\n\nIn the project folder run:\n\n```bash\npnpm start-devnet\npnpm start-testnet\npnpm start-mainnet\n```\n\nThis will start the React app in development mode, using the configs found in the `vite.config.ts` file.\nOpen [http://localhost:3000](http://localhost:3000) to view it in the browser.\n\nThe page will reload if you make edits.\\\nYou will also see any lint errors in the console.\n\n## Passkey Testing Setup (CRITICAL for Passkey Development)\n\n### Step 1: System Configuration\n\n**MUST configure hosts file for passkey functionality:**\n\n```bash\n# Add to /etc/hosts (macOS/Linux) or C:\\Windows\\System32\\drivers\\etc\\hosts (Windows):\n127.0.0.1    localhost.multiversx.com\n\n# Edit hosts file:\n# macOS/Linux:\nsudo nano /etc/hosts\n\n# Windows (run as Administrator):\nnotepad C:\\Windows\\System32\\drivers\\etc\\hosts\n```\n\n### Step 2: Generate Locally-Trusted SSL Certificates\n\n**CRITICAL: WebAuthn requires valid HTTPS certificates to prevent TLS certificate errors:**\n\n```bash\n# Install mkcert (if not already installed)\nbrew install mkcert\n\n# Install the local CA in your system trust store\nmkcert -install\n\n# Generate certificates for localhost.multiversx.com\nmkcert localhost.multiversx.com localhost 127.0.0.1 ::1\n```\n\nThis creates two files in `certificates` folder:\n- `localhost.multiversx.com+3.pem` (certificate)\n- `localhost.multiversx.com+3-key.pem` (private key)\n\n### Step 3: Configure vite.config.ts with SSL Certificates\n\n**Update vite.config.ts to use port 443:**\n\n```typescript\nimport fs from 'fs';\n// import basicSsl from '@vitejs/plugin-basic-ssl'; // Remove this - use mkcert certificates instead\n\nconst https = {\n  key: fs.readFileSync('./certificates/localhost.multiversx.com-key.pem'),\n  cert: fs.readFileSync('./certificates/localhost.multiversx.com.pem')\n};\n\nexport default defineConfig({\n  server: {\n    port: Number(process.env.PORT) || 443,\n    strictPort: true,\n    https,\n    host: true\n  }\n});\n```\n\n### Step 4: Browser Setup for Passkeys (Optional)\n\n**With proper certificates, you can use regular Chrome. For additional debugging, use Chrome with security flags:**\n\n```bash\n# Close all Chrome instances first, then run:\nopen -a Google\\ Chrome --args --ignore-certificate-errors --ignore-urlfetcher-cert-requests --disable-web-security --user-data-dir=/tmp/chrome_dev_passkey\n```\n\n**⚠️ Important:** Always close these Chrome instances after testing.\n\n### Step 5: Start the Development Server\n\n```bash\npnpm start-devnet --force\n```\n\n**Test URLs:**\n- **Template dApp**: https://localhost.multiversx.com\n\n### Troubleshooting WebAuthn TLS Errors\n\nIf you encounter `NotAllowedError: WebAuthn is not supported on sites with TLS certificate errors`, ensure:\n\n1. ✅ mkcert is installed and CA is trusted (`mkcert -install`)\n2. ✅ Certificates are generated for localhost.multiversx.com\n3. ✅ vite.config.ts uses the certificate files\n4. ✅ Browser shows a valid HTTPS lock icon\n5. ✅ No mixed content warnings in DevTools\n\n## Available Scripts\n\nIn the project directory, you can run:\n\n### `pnpm start` / `pnpm start-devnet`\n\nRuns the app in the development mode.\n**For passkey testing**: Run with `pnpm start` and open [https://localhost.multiversx.com](https://localhost.multiversx.com) to view it in the browser.\n\nThe page will reload if you make edits.\nYou will also see any lint errors in the console.\n\n### `pnpm test`\n\nLaunches the test runner in the interactive watch mode.\nSee the section about [running tests](https://vitejs.dev/guide/static-deploy.html#testing-the-app-locally) for more information.\n\n### `pnpm build` / `pnpm build-devnet`\n\nBuilds the app for production to the `build` folder.\nIt correctly bundles React in production mode and optimizes the build for the best performance.\n\nThe build is minified and the filenames include the hashes.\nYour app is ready to be deployed!\n\nSee the section about [deployment](https://vitejs.dev/guide/static-deploy.html#building-the-app) for more information.\n\n### Build for testing and production use\n\nA build of the app is necessary to deploy for testing purposes or for production use.\nTo build the project run:\n\n```bash\npnpm build-devnet\npnpm build-testnet\npnpm build-mainnet\n```\n\n## Configure Theme (Optional)\n\nThis template comes with three built-in themes:\n- TealLab (mvx:dark-theme)\n- VibeMode (mvx:vibe-theme)\n- BrightLight (mvx:light-theme)\n\nBut you can customize the appearance of your project by defining your own theme using CSS variables. \nFollow these steps to set it up.\n\n### Step 1. Update `tailwind.css` file \n\nThis is the main place where you customize your theme. You add your project specific colors and update \nCSS variables that style your elements, according to your theme.\n\nDefine your color palette in the `:root` section:\n\n```css\n:root {\n  --mvx-custom-primary-color: #your-color;\n  --mvx-custom-secondary-color: #your-color;\n}\n```\n\nNext, configure your theme-specific variables:\n\n```css\n:root[data-mvx-theme='mvx:your-theme'],\n[data-mvx-theme='mvx:your-theme'] {\n  --mvx-bg-color-primary: var(--mvx-custom-primary-color);\n  --mvx-bg-color-secondary: var(--mvx-custom-secondary-color);\n}\n```\n\n### Step 2. Add your theme in `useHandleThemeManagement.ts` hook\n\nThis hook registers and manages all available themes in your project.\nIt maintains a list of all theme options, tracks the currently active theme and \nprovides a `handleThemeSwitch` function that updates the `data-mvx-theme` attribute. \n\n```typescript\nconst allThemeOptions: ThemeOptionType[] =\n[\n    { identifier: 'mvx:dark-theme', label: 'TealLab' },\n    { identifier: 'mvx:vibe-theme', label: 'VibeMode' },\n    { identifier: 'mvx:light-theme', label: 'BrightLight' },\n\n    { identifier: 'mvx:your-theme', label: 'Your Theme Label' }\n];\n```\n\n### Step 3. Add colors for your theme tooltip in `ThemeTooltip.tsx`\n\nThis allows you to see the theme options available in the project. They are listed in a tooltip\ndropdown in header with visual color previews for each theme.\n\n```typescript\nconst themeDotColors: Record\u003cstring, string[]\u003e = \n{\n  'mvx:dark-theme': ['#23F7DD', '#262626', '#B6B3AF', '#FFFFFF'],\n  'mvx:vibe-theme': ['#471150', '#5A2A62', '#D200FA', '#FFFFFF'],\n  'mvx:light-theme': ['#000000', '#A5A5A5', '#E2DEDC', '#F3EFED'],\n\n  'mvx:your-theme': ['#color1', '#color2', '#color3', '#color4']\n};\n```\n\n### Step 4. Add theme properties for hero section in `HomeHero.tsx`\n\nAdd your icon in `assets` folder and import it as:\n\n```typescript\nimport { ReactComponent as YourThemeIcon } from 'assets/icons/your-theme-icon.svg';\n```\n\nAdd a background image for your theme in `public` folder and reference it in `tailwind.css`:\n\n```css\n@theme {\n  --background-image-your-theme: url('/your-theme-bg.png');\n}\n```\n\nAnd then update `themeExtraProperties` object with your values. These properties are used for \ncustomizing your hero section from home page. It adds background image and icon + title for the \ntheme switch section in hero.\n\n```typescript\nconst themeExtraProperties: Record\u003c\n  string,\n  Omit\u003cHomeThemeOptionType, keyof ThemeOptionType\u003e\n\u003e = {\n  // existing themes\n  'mvx:your-theme': {\n    icon: YourThemeIcon,\n    title: 'Your Title',\n    backgroundClass: 'bg-your-theme'\n  }\n};\n```\n\n### Step 5. Set your theme as default in `initConfig.ts`\n\n```typescript\ndAppConfig: {\n    theme: 'mvx:your-theme',\n  }\n```\n\nNow the project will start with your configured theme. \nAll variables will have the colors you have set. If you don't set custom colors, the default ones will apply.\nYou can see the current theme in `data-mvx-theme` attribute in browser inspector.\n\n## Learn More\n\nYou can learn more in the [Vite documentation](https://vitejs.dev/).\n\nTo learn React, check out the [React documentation](https://reactjs.org/).\n\n## Roadmap\n\nSee the [open issues](https://github.com/multiversx/mx-template-dapp/issues) for a list of proposed features (and known issues).\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nOne can contribute by creating _pull requests_, or by opening _issues_ for discovered bugs or desired features.\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n","funding_links":[],"categories":["MultiversX official","TypeScript"],"sub_categories":["Dev dApps"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultiversx%2Fmx-template-dapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmultiversx%2Fmx-template-dapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultiversx%2Fmx-template-dapp/lists"}