Jupiter Developers

This guide walks through integrating Jupiter Plugin into a React application from scratch. It covers TypeScript declarations, embedding the plugin script, and two initialization methods: the window object approach and the @jup-ag/plugin npm package.

Prerequisites

Before you begin, make sure you have the following installed on your system. Node.js and npm: Download and install from nodejs.org

Step 1: Create a New React Project

Head to your preferred directory and create a new React project using create-react-app with TypeScript template (you can use other templates or methods to start your project too):

npx create-react-app plugin-demo --template typescript
cd plugin-demo
npm start

Step 2: Add TypeScript Support

Create a type declaration file plugin.d.ts in your project’s /src/types folder:

declare global {
  interface Window {
    Jupiter: JupiterPlugin;
  }
};
export {};

Full TypeScript Declaration

declare global {
  interface Window {
      Jupiter: JupiterPlugin;
  }
}

export type WidgetPosition = 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
export type WidgetSize = 'sm' | 'default';
export type SwapMode = "ExactInOrOut" | "ExactIn" | "ExactOut";
export type DEFAULT_EXPLORER = 'Solana Explorer' | 'Solscan' | 'Solana Beach' | 'SolanaFM';

export interface FormProps {
  swapMode?: SwapMode;
  initialAmount?: string;
  initialInputMint?: string;
  initialOutputMint?: string;
  fixedAmount?: boolean;
  fixedMint?: string;
  referralAccount?: string;
  referralFee?: number;
}

export interface IInit {
  localStoragePrefix?: string;
  formProps?: FormProps;
  defaultExplorer?: DEFAULT_EXPLORER;
  autoConnect?: boolean;
  displayMode?: 'modal' | 'integrated' | 'widget';
  integratedTargetId?: string;
  widgetStyle?: {
      position?: WidgetPosition;
      size?: WidgetSize;
  };
  containerStyles?: CSSProperties;
  containerClassName?: string;
  enableWalletPassthrough?: boolean;
  passthroughWalletContextState?: WalletContextState;
  onRequestConnectWallet?: () => void | Promise<void>;
  onSwapError?: ({
      error,
      quoteResponseMeta,
  }: {
      error?: TransactionError;
      quoteResponseMeta: QuoteResponse | null;
  }) => void;
  onSuccess?: ({
      txid,
      swapResult,
      quoteResponseMeta,
  }: {
      txid: string;
      swapResult: SwapResult;
      quoteResponseMeta: QuoteResponse | null;
  }) => void;
  onFormUpdate?: (form: IForm) => void;
  onScreenUpdate?: (screen: IScreen) => void;
}

export interface JupiterPlugin {
  _instance: JSX.Element | null;
  init: (props: IInit) => void;
  resume: () => void;
  close: () => void;
  root: Root | null;
  enableWalletPassthrough: boolean;
  onRequestConnectWallet: IInit['onRequestConnectWallet'];
  store: ReturnType<typeof createStore>;
  syncProps: (props: { passthroughWalletContextState?: IInit['passthroughWalletContextState'] }) => void;
  onSwapError: IInit['onSwapError'];
  onSuccess: IInit['onSuccess'];
  onFormUpdate: IInit['onFormUpdate'];
  onScreenUpdate: IInit['onScreenUpdate'];
  localStoragePrefix: string;
}

export { };

Step 3: Embed the Plugin Script

In your /public/index.html, add the Jupiter Plugin script:

<head>
  <script src="https://plugin.jup.ag/plugin-v1.js" data-preload defer></script>
</head>

Step 4: Initialize Plugin

There are two ways to initialize Jupiter Plugin in a React application:

Method 1: Using Window Object

In your /src/App.tsx, use the following code to initialize the plugin.

import React, { useEffect } from 'react';
import './App.css';
import './types/plugin.d';

export default function App() {
  useEffect(() => {
    // Initialize plugin
    window.Jupiter.init({
      displayMode: "widget",
      integratedTargetId: "jupiter-plugin",
    });
  }, []);

  return (
    <div className="App">
      <h1>Jupiter Plugin Demo</h1>
      <div id="jupiter-plugin" />
    </div>
  );
}

Method 2: Using @jup-ag/plugin Package

WARNINGDo note that using this method will require you to maintain its dependencies.

Install the package:

npm install @jup-ag/plugin

Initialize the plugin:

import React, { useEffect } from "react";
import "@jup-ag/plugin/css";
import "./App.css";
import "./types/plugin.d";

export default function App() {
  useEffect(() => {
    import("@jup-ag/plugin").then((mod) => {
      const { init } = mod;
      init({
        displayMode: "widget",
        integratedTargetId: "jupiter-plugin",
      });
    });
  }, []);

  return (
    <div>
      <h1>Jupiter Plugin Demo</h1>
      <div id="jupiter-plugin" />
    </div>
  );
}

There you have it! You’ve successfully integrated Jupiter Plugin into your Next.js application.

Please test the swap functionality and check the transaction.
If you require more customizations, check out the Plugin Playground or the Customization documentation.
If you have any questions or issues, please refer to the FAQ or contact us on Discord.

Tool Kits

Jupiter Plugin

Jupiter Wallet Kit

Jupiter Referral Program

React App Example

Prerequisites

Step 1: Create a New React Project

Step 2: Add TypeScript Support

Step 3: Embed the Plugin Script

Step 4: Initialize Plugin

Method 1: Using Window Object

Method 2: Using @jup-ag/plugin Package

​Prerequisites

​Step 1: Create a New React Project

​Step 2: Add TypeScript Support

​Step 3: Embed the Plugin Script

​Step 4: Initialize Plugin

​Method 1: Using Window Object

​Method 2: Using @jup-ag/plugin Package

Prerequisites

Step 1: Create a New React Project

Step 2: Add TypeScript Support

Step 3: Embed the Plugin Script

Step 4: Initialize Plugin

Method 1: Using Window Object

Method 2: Using @jup-ag/plugin Package