Vue + Vite

This guide shows you how to integrate the Capsule Modal—which is React-based—within a Vue application using Vite. While mixing React with Vue isn’t always considered best practice, it is entirely possible by bridging to the React modal via a connector. If you prefer to build your own custom UI, you can also use @usecapsule/web-sdk directly.

​

Prerequisites

To use Capsule, you need an API key. This key authenticates your requests to Capsule services and is essential for integration.

​

Installing Dependencies

First, install both the Capsule React SDK and the React dependencies, since the modal relies on React under the hood:

​

Setting Up Polyfills

Like any React + Vite project that may rely on Node modules (crypto, buffer, stream), you’ll likely need polyfills:

Then, update your vite.config.js or vite.config.ts:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import react from "@vitejs/plugin-react"; // Needed for the React-based modal
import { nodePolyfills } from "vite-plugin-node-polyfills";

export default defineConfig({
  plugins: [
    vue(),
    react(),
    nodePolyfills({
      protocolImports: true,
    }),
  ],
});

​

Setting Up the Capsule SDK

Now that you’ve installed the necessary dependencies, let’s set up the Capsule SDK in your Vue project. This involves creating a client instance and optionally configuring Next.js to transpile external modules if needed.

​

Creating a Capsule Client Instance

Just like in React apps, you need a Capsule client instance. You can keep it in a dedicated file (e.g., client/capsule.ts):

import { Environment, CapsuleWeb } from "@usecapsule/react-sdk";

const CAPSULE_API_KEY = import.meta.env.VITE_CAPSULE_API_KEY;
export const capsuleClient = new CapsuleWeb(Environment.BETA, CAPSULE_API_KEY);

​

Building a Connector for the React Modal

To display the React-based Capsule Modal from within Vue, we’ll create a “connector” that mounts the React modal into a DOM element. You can store this in a file such as capsule-modal-connector.tsx:

import React from "react";
import { createRoot } from "react-dom/client";
import { CapsuleModal, CapsuleModalProps } from "@usecapsule/react-sdk";
import "@usecapsule/react-sdk/styles.css";

export const createCapsuleModalConnector = (targetEl: HTMLElement, props: Omit<CapsuleModalProps, "isOpen">) => {
  const root = createRoot(targetEl);

  const state = {
    isOpen: false,
    render: (isOpen: boolean) => {
      state.isOpen = isOpen;
      root.render(
        <CapsuleModal
          {...props}
          isOpen={isOpen}
          onClose={() => {
            state.isOpen = false;
            state.render(false);
            props.onClose?.();
          }}
        />
      );
    },
  };

  return {
    open: () => state.render(true),
    close: () => state.render(false),
    isOpen: () => state.isOpen,
    unmount: () => root.unmount(),
  };
};

This connector creates a React root within a given DOM element and renders the Capsule Modal into it. It also provides a few methods to open, close, and check the modal’s state.

​

Integrating in a Vue Component

Use Vue’s lifecycle hooks to create and destroy the modal connector. Below is a simplified example (index.vue):

<template>
  <div style="text-align: center; margin-top: 50px">
    <h1>Capsule Modal Starter (Vue + Vite)</h1>
    <button @click="openModal">Open Capsule Modal</button>
  </div>
</template>

<script setup lang="ts">
  import { onMounted, onUnmounted, ref } from "vue";
  import { createCapsuleModalConnector } from "./capsule-modal-connector.tsx";
  import { capsuleClient } from "./client/capsule";

  const modalConnector = ref<any>(null);

  onMounted(() => {
    // Create a container for the React modal
    const container = document.createElement("div");
    document.body.appendChild(container);

    modalConnector.value = createCapsuleModalConnector(container, {
      capsule: capsuleClient,
      onClose: () => {
        modalConnector.value?.close();
      },
      appName: "Capsule in Vue + Vite",
      // ...any additional CapsuleModal props
    });
  });

  onUnmounted(() => {
    modalConnector.value?.unmount();
  });

  const openModal = () => {
    modalConnector.value?.open();
  };
</script>

When you click the Open Capsule Modal button, the React-based Capsule Modal will appear within your Vue application.

​

Customizing the Capsule Modal

All the usual customization props apply, just as in a React app:

<CapsuleModal
  capsule={capsuleClient}
  isOpen={true}
  onClose={() => {}}
  appName="My Vue App"
  oAuthMethods={["GOOGLE", "DISCORD"]}
/>

Pass them through your connector’s props object as needed.

​

If You Don’t Want to Use the React Modal

You can also build a custom UI using @usecapsule/web-sdk. This SDK gives you direct access to Capsule functionality (authentication, signing, etc.), letting you craft your own Vue components without bridging to React.

​

Examples

For an example of a fully working Vue + Vite integration, check out our starter templates or example repositories:

​

Next Steps

After integrating Capsule, you can explore other features and integrations to enhance your Capsule experience. Here are some resources to help you get started:

​

Ecosystems

Learn how to use Capsule with popular Web3 clients and wallet connectors. We’ll cover integration with key libraries for EVM, Solana, and Cosmos ecosystems.

If you’re ready to go live with your Capsule integration, make sure to review our go-live checklist:

​

Troubleshooting

​

Integration Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our team for assistance. To help us resolve your issue quickly, please include the following information in your request:

1. 1

   A detailed description of the problem you’re encountering.

2. 2

   Any relevant error messages or logs.

3. 3

   Steps to reproduce the issue.

4. 4

   Details about your system or environment (e.g., device, operating system, software version).

Providing this information will enable our team to address your concerns more efficiently.