-
Notifications
You must be signed in to change notification settings - Fork 21
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #39 from perawallet/next-release
perawallet/[email protected]
- Loading branch information
Showing
10 changed files
with
193 additions
and
211 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| ### Contributing | ||
|
|
||
| To contribute to the codebase, you will need to fork the repository. | ||
|
|
||
| The following steps will get you setup to contribute changes to this repo: | ||
|
|
||
| - Fork the repo and create your branch from `next-release`. | ||
| - Install depencencies and build. | ||
|
|
||
| We use npm to manage installation of dependencies and running various scripts. To get everything installed, make sure you have npm and run `npm install` from the root of the repository. | ||
|
|
||
| #### Reporting new issues | ||
|
|
||
| When opening a new issue, always make sure to fill out the issue template. | ||
|
|
||
| - One issue, one bug: Please report a single bug per issue. | ||
| - Provide reproduction steps: List all the steps necessary to reproduce the issue. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort. | ||
|
|
||
| #### Development | ||
|
|
||
| ##### Building | ||
|
|
||
| Running npm run build from the root directory will run the build command for package. | ||
|
|
||
| ##### Branch Organization | ||
|
|
||
| - main Branch: main branch is used version in npm. | ||
| - next-release Branch: next-release branch includes tested and ready for next version of package. | ||
|
|
||
| ##### Feature Branches | ||
|
|
||
| When starting to work on a new feature development or a bug fix, you must branch out from next-release. The name of the branch should reflect its purpose. | ||
|
|
||
| ##### Commit Messages | ||
|
|
||
| To standardize our commit messages, we follow the convention described on Conventional Commits. | ||
|
|
||
| ```ssh | ||
| feat(connect-modal): change typography of connect modal. | ||
| ^--^^----^ ^----------------------------------^ | ||
| | | | | ||
| | | +-> Summary in present tense. | ||
| | | | ||
| | +-> The place that this change affected. | ||
| | | ||
| +-------> Type | ||
| ``` | ||
|
|
||
| ##### Pull Requests | ||
|
|
||
| When the work on a feature/bug-fix branch is completed, a pull request (PR) should be opened to next-release. | ||
|
|
||
| ##### PR Titles | ||
|
|
||
| A similar convention with the commit messages applies to PR titles. Avoid giving too much detail on the PR titles, maximum of 4-5 words would be enough to explain the purpose of the PR. | ||
|
|
||
| ```ssh | ||
| <type>(scope): <pr summary> | ||
| ``` | ||
|
|
||
| ##### PR Descriptions | ||
|
|
||
| Include the purpose of the PR, the changes you made, and the expected behavior to PR descriptions. Please fill the PR template, you can feel free to add more sections. | ||
|
|
||
| ##### Work on local | ||
|
|
||
| You can work on your local project with this package. All you have to do is replace the version part of @perawallet/connect in the package.json file with "file:path/connect" like this. | ||
|
|
||
| ```json | ||
| "@perawallet/connect": "file:../connect" | ||
| ``` | ||
|
|
||
| After doing this, you can run `npm run dev` and in this way, you can see the changes you have made to the package simultaneously. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,197 +1,79 @@ | ||
|  | ||
|  | ||
|
|
||
| ### @perawallet/connect | ||
|
|
||
| JavaScript SDK for integrating [Pera Wallet](https://perawallet.app) to web applications. | ||
| JavaScript SDK for integrating [Pera Wallet](https://perawallet.app) to web applications. For more detailed information, please check our [Pera Connect Docs](https://docs.perawallet.app/references/pera-connect/). | ||
|
|
||
| [](https://www.npmjs.com/package/@perawallet/connect) [](https://www.npmjs.com/package/@perawallet/connect) | ||
|
|
||
| ### Getting Started | ||
|
|
||
| [Try it out using CodeSandbox](#example-applications) | ||
|
|
||
| [Learn how to integrate with your JavaScript application](#guide) | ||
|
|
||
| [Learn how to Sign Transactions](#sign-transaction) | ||
|
|
||
| [Try it out using CodeSandbox](#example-applications) | ||
|
|
||
| ### Example Applications | ||
|
|
||
| [Using React Hooks](https://codesandbox.io/s/perawallet-connect-react-demo-ib9tqt?file=/src/App.js) | ||
| - [Using React Hooks](https://codesandbox.io/s/perawallet-connect-react-demo-zlvokc) | ||
|
|
||
| [Using Vue3](https://codesandbox.io/s/perawallet-connect-vue-demo-m8q3sl?file=/src/App.vue) | ||
| - [Using React Hooks with React@18](https://codesandbox.io/s/perawallet-connect-react-18-demo-tig2md) | ||
|
|
||
| ### Guide | ||
| - [Using Vue3](https://codesandbox.io/s/perawallet-connect-vue3-demo-yiyw4b) | ||
|
|
||
| Let's start with installing `@perawallet/connect` | ||
| - [Using Svelte](https://codesandbox.io/s/perawallet-connect-svelte-demo-ys1m4x) | ||
|
|
||
| ``` | ||
| npm install --save @perawallet/connect | ||
| ``` | ||
| - [Using Next.js](https://codesandbox.io/s/perawallet-connect-next-js-demo-ryhbdb) | ||
|
|
||
| <details> | ||
| <summary>Using with React 18</summary><br/> | ||
|
|
||
| When you want to use `@perawallet/connect` library with React 18, you need to make some changes. `react-scripts` stopped polyfilling some of the packages with the `[email protected]` version. After creating a new app with `npx create-react-app my-app` or in your react application, the following changes should be made. | ||
| - [Using Nuxt.js](https://codesandbox.io/s/perawallet-connect-nuxt-js-demo-s65z58) | ||
|
|
||
| 1. Firstly, install the following packages. | ||
| - [Vanilla JS](https://codesandbox.io/s/perawallet-connect-vanillajs-demo-s5pjeo) | ||
|
|
||
| ```sh | ||
| npm install buffer | ||
| npm install crypto-browserify | ||
| npm install process | ||
| npm install react-app-rewired | ||
| npm install stream-browserify | ||
| ``` | ||
| ### Quick Start | ||
|
|
||
| 2. After that you need to override some webpack features. Create the following file in the root directory of the project and copy the following code block into it. | ||
| Let's start with installing `@perawallet/connect` | ||
|
|
||
| `config-overrides.js` | ||
| ``` | ||
| npm install --save @perawallet/connect | ||
| ``` | ||
|
|
||
| ```jsx | ||
| // eslint-disable-next-line @typescript-eslint/no-var-requires | ||
| const webpack = require("webpack"); | ||
|
|
||
| module.exports = function override(config) { | ||
| const fallback = config.resolve.fallback || {}; | ||
|
|
||
| Object.assign(fallback, { | ||
| crypto: require.resolve("crypto-browserify"), | ||
| stream: require.resolve("stream-browserify") | ||
| // Connect handler | ||
| peraWallet | ||
| .connect() | ||
| .then((newAccounts) => { | ||
| // Setup the disconnect event listener | ||
| peraWallet.connector?.on("disconnect", handleDisconnectWalletClick); | ||
|
|
||
| setAccountAddress(newAccounts[0]); | ||
| }) | ||
| .reject((error) => { | ||
| // You MUST handle the reject because once the user closes the modal, peraWallet.connect() promise will be rejected. | ||
| // For the async/await syntax you MUST use try/catch | ||
| if (error?.data?.type !== "CONNECT_MODAL_CLOSED") { | ||
| // log the necessary errors | ||
| } | ||
| }); | ||
| config.resolve.fallback = fallback; | ||
| // ignore warning about source map of perawallet/connect | ||
|
|
||
| config.ignoreWarnings = [/Failed to parse source map/]; | ||
| config.plugins = (config.plugins || []).concat([ | ||
| new webpack.ProvidePlugin({ | ||
| process: "process/browser", | ||
| Buffer: ["buffer", "Buffer"] | ||
| }) | ||
| ]); | ||
| return config; | ||
| }; | ||
| ``` | ||
| 3. Finally, you need to update the npm scripts. | ||
|
|
||
| `{ "start": "react-app-rewired start", "build": "react-app-rewired build" }` | ||
|
|
||
| After that, you are good to go! 🎊 | ||
|
|
||
| </details> | ||
|
|
||
| #### Using React Hooks | ||
|
|
||
| ```typescript | ||
| import {PeraWalletConnect} from "@perawallet/connect"; | ||
|
|
||
| // Create the PeraWalletConnect instance outside of the component | ||
| const peraWallet = new PeraWalletConnect(); | ||
|
|
||
| function App() { | ||
| const [accountAddress, setAccountAddress] = useState<string | null>(null); | ||
| const isConnectedToPeraWallet = !!accountAddress; | ||
|
|
||
| useEffect(() => { | ||
| // Reconnect to the session when the component is mounted | ||
| peraWallet.reconnectSession().then((accounts) => { | ||
| // Setup the disconnect event listener | ||
| peraWallet.connector?.on("disconnect", handleDisconnectWalletClick); | ||
|
|
||
| if (accounts.length) { | ||
| setAccountAddress(accounts[0]); | ||
| } | ||
| }); | ||
| }, []); | ||
|
|
||
| return ( | ||
| <button | ||
| onClick={ | ||
| isConnectedToPeraWallet ? handleDisconnectWalletClick : handleConnectWalletClick | ||
| }> | ||
| {isConnectedToPeraWallet ? "Disconnect" : "Connect to Pera Wallet"} | ||
| </button> | ||
| ); | ||
|
|
||
| function handleConnectWalletClick() { | ||
| peraWallet | ||
| .connect() | ||
| .then((newAccounts) => { | ||
| // Setup the disconnect event listener | ||
| peraWallet.connector?.on("disconnect", handleDisconnectWalletClick); | ||
|
|
||
| setAccountAddress(newAccounts[0]); | ||
| }) | ||
| .reject((error) => { | ||
| // You MUST handle the reject because once the user closes the modal, peraWallet.connect() promise will be rejected. | ||
| // For the async/await syntax you MUST use try/catch | ||
| if (error?.data?.type !== "CONNECT_MODAL_CLOSED") { | ||
| // log the necessary errors | ||
| } | ||
| }); | ||
| } | ||
| If you don't want the user's account information to be lost by the dApp when the user closes the browser with user’s wallet connected to the dApp, you need to handle the reconnect session status. You can do this in the following way. | ||
| function handleDisconnectWalletClick() { | ||
| peraWallet.disconnect(); | ||
| ```jsx | ||
| // On the every page refresh | ||
| peraWallet.reconnectSession().then((accounts) => { | ||
| // Setup the disconnect event listener | ||
| peraWallet.connector?.on("disconnect", handleDisconnectWalletClick); | ||
|
|
||
| setAccountAddress(null); | ||
| if (accounts.length) { | ||
| setAccountAddress(accounts[0]); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Sign Transaction | ||
|
|
||
| `@perawallet/connect` also allows signing transactions using the Pera Wallet application. Once the `signTransaction` method is triggered if the user is on a mobile browser, the Pera Wallet app will be launched automatically, if the browser blocks the redirection there's also a popup that links to the Pera Wallet app. | ||
|
|
||
| `@perawallet/connect` guides users with a toast message when the `signTransaction` is triggered on desktop. It's enabled by default but in some cases, you may not need to the toast message (e.g. you already have signing guidance for users). There's an option called `shouldShowSignTxnToast` to disable it, see the example below: | ||
|
|
||
| ```js | ||
| const peraWallet = new PeraWalletConnect({shouldShowSignTxnToast: false}); | ||
| ``` | ||
|
|
||
| You can also call the `closePeraWalletSignTxnToast` function to hide the toast. | ||
|
|
||
| ```js | ||
| import {closePeraWalletSignTxnToast} from "@perawallet/connect"; | ||
|
|
||
| // ...Business logic | ||
|
|
||
| // Close the toast message | ||
| closePeraWalletSignTxnToast(); | ||
| ``` | ||
|
|
||
| `signTransaction` accepts `SignerTransaction[][]` the type can be found [here](./src/util/model/peraWalletModels.ts) | ||
|
|
||
| **To see more details & working examples please [visit here](https://codesandbox.io/s/txns-demo-pj3nf2)** | ||
|
|
||
| ```javascript | ||
| // Setting up algosdk client | ||
| const algod = new algosdk.Algodv2("", "https://node.testnet.algoexplorerapi.io/", 443); | ||
|
|
||
| // Setting up Transactions | ||
| const suggestedParams = await algod.getTransactionParams().do(); | ||
| const optInTxn = algosdk.makeAssetTransferTxnWithSuggestedParamsFromObject({ | ||
| from: FROM_ADDRESS, | ||
| to: FROM_ADDRESS, | ||
| assetIndex: ASSET_ID, | ||
| amount: 0, | ||
| suggestedParams | ||
| }); | ||
| const optInTxn2 = algosdk.makeAssetTransferTxnWithSuggestedParamsFromObject({ | ||
| from: FROM_ADDRESS, | ||
| to: FROM_ADDRESS, | ||
| assetIndex: ASSET_ID, | ||
| amount: 0, | ||
| suggestedParams | ||
| }); | ||
| ``` | ||
| // Mapping `Transaction` to `SignerTransaction[]` | ||
| const singleTxnGroups = [{txn: optInTxn, signers: [FROM_ADDRESS]}]; | ||
| const multipleTxnGroups = [ | ||
| {txn: optInTxn, signers: [FROM_ADDRESS]}, | ||
| {txn: optInTxn2, signers: [FROM_ADDRESS]} | ||
| ]; | ||
| After that you can sign transaction with this way | ||
| ```jsx | ||
| // Single Transaction | ||
| try { | ||
| const signedTxn = await peraWallet.signTransaction([singleTxnGroups]); | ||
|
|
@@ -207,6 +89,17 @@ try { | |
| } | ||
| ``` | ||
| ### Customizing Style | ||
| You can override the z-index using the `.pera-wallet-connect-modal` class so that the modal does not conflict with another component on your application. | ||
| ```scss | ||
| .pera-wallet-connect-modal { | ||
| // The default value of z-index is 10. You can lower and raise it as much as you want. | ||
| z-index: 11; | ||
| } | ||
| ``` | ||
| ### Your app name on Pera Wallet | ||
| By default, the connect wallet drawer on Pera Wallet gets the app name from `document.title`. | ||
|
|
@@ -216,3 +109,7 @@ In some cases, you may want to customize it. You can achieve this by adding a me | |
| ```html | ||
| <meta name="name" content="My dApp" /> | ||
| ``` | ||
| ### Contributing | ||
| All contributions are welcomed! To get more information about the details, please read the [contribution](./CONTRIBUTING.md) guide first. | ||
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.